pulumi-sandbox 0.1.0

package/dist/docker/mask-volumes.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+import fs from "node:fs";
+import { warn } from "../terminal.js";
+/**
+ * Walks a repository and returns one container-local mask volume for every
+ * directory the given rules mark as locally generated — directories whose
+ * contents must not round-trip between the host bind mount and the
+ * container, which is essential when host and container run different
+ * platforms (a Windows host building inside a Linux container, for example).
+ *
+ * Detection keys off the marker files — which exist from the first
+ * checkout — never off the masked directories themselves, so a directory
+ * that does not exist yet is still masked: docker creates the empty volume
+ * on first start and the first in-container build writes there, never back
+ * to the host. Add a module to the repository and its masks appear on the
+ * next `create`, with no list to maintain.
+ */
+export function discoverMaskVolumes(rootDirectory, options) {
+    const root = path.resolve(rootDirectory);
+    const prune = new Set(options.prune ?? []);
+    const volumes = [];
+    const seenContainerPaths = new Set();
+    const containerPathByKey = new Map();
+    const uniqueKey = (prefix, relativeDirectory, leaf, containerPath) => {
+        const base = `${prefix}--${slug(relativeDirectory)}`;
+        const candidates = [base, `${base}--${slug(leaf)}`];
+        for (const candidate of candidates) {
+            if (!containerPathByKey.has(candidate)) {
+                return candidate;
+            }
+        }
+        let ordinal = 2;
+        while (containerPathByKey.has(`${candidates[1]}-${ordinal}`)) {
+            ordinal += 1;
+        }
+        return `${candidates[1]}-${ordinal}`;
+    };
+    const mask = (prefix, absoluteDirectory, leaf) => {
+        const absoluteMasked = path.resolve(absoluteDirectory, leaf);
+        const relativeMasked = path.relative(root, absoluteMasked);
+        if (relativeMasked.startsWith("..") || path.isAbsolute(relativeMasked)) {
+            warn(`Cannot mask ${absoluteMasked}: it is outside the walked root ${root}.`);
+            return;
+        }
+        const containerPath = path.posix.join(options.containerRoot, relativeMasked.replace(/\\/g, "/"));
+        if (seenContainerPaths.has(containerPath)) {
+            return;
+        }
+        seenContainerPaths.add(containerPath);
+        const key = uniqueKey(prefix, path.dirname(relativeMasked), path.basename(relativeMasked), containerPath);
+        containerPathByKey.set(key, containerPath);
+        volumes.push({ key, containerPath });
+    };
+    const walk = (absoluteDirectory) => {
+        // Children masked in THIS directory are not walked into; an unrelated
+        // directory elsewhere that shares the name still is.
+        const maskedChildren = new Set();
+        for (const rule of options.rules) {
+            const markerPath = firstExisting(absoluteDirectory, rule.markers);
+            if (markerPath === undefined) {
+                continue;
+            }
+            for (const leaf of rule.mask) {
+                mask(rule.prefix, absoluteDirectory, leaf);
+                const [firstSegment, ...restSegments] = leaf.split("/");
+                if (firstSegment !== undefined && restSegments.length === 0) {
+                    maskedChildren.add(firstSegment);
+                }
+            }
+            if (rule.expand) {
+                const content = fs.readFileSync(markerPath, "utf-8");
+                for (const expanded of rule.expand(markerPath, content)) {
+                    for (const leaf of rule.mask) {
+                        mask(rule.prefix, path.resolve(absoluteDirectory, expanded), leaf);
+                    }
+                }
+            }
+        }
+        for (const entry of fs.readdirSync(absoluteDirectory, { withFileTypes: true })) {
+            if (entry.isDirectory() &&
+                !maskedChildren.has(entry.name) &&
+                !prune.has(entry.name) &&
+                !entry.name.startsWith(".")) {
+                walk(path.join(absoluteDirectory, entry.name));
+            }
+        }
+    };
+    walk(root);
+    return volumes;
+}
+function slug(relativeDirectory) {
+    const normalized = relativeDirectory.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+    return normalized === "" || normalized === "." ? "root" : normalized.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase();
+}
+function firstExisting(directory, names) {
+    return names.map((name) => path.join(directory, name)).find((candidate) => fs.existsSync(candidate));
+}

package/dist/docker/shell.d.ts

@@ -0,0 +1,23 @@
+export interface AttachShellOptions {
+    /** Shell to start inside the container. Default: `/bin/bash`. */
+    shell?: string | undefined;
+}
+/**
+ * Attaches an interactive shell to a running container — the
+ * `docker exec -it <container> <shell>` a developer would type by hand.
+ * Returns the shell's exit code so the caller decides what to do with the
+ * process.
+ *
+ * Pairs naturally with a custom sandbox command:
+ *
+ * ```typescript
+ * commands: {
+ *   shell: {
+ *     description: "Open a shell inside the workspace container",
+ *     run: ({ physicalName, argv }) => attachShell(physicalName("workspace"), { shell: argv[0] }),
+ *   },
+ * }
+ * ```
+ */
+export declare function attachShell(containerName: string, options?: AttachShellOptions): number;
+//# sourceMappingURL=shell.d.ts.map

package/dist/docker/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/docker/shell.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAgB3F"}

package/dist/docker/shell.js

@@ -0,0 +1,34 @@
+import { spawnSync } from "node:child_process";
+import { fail } from "../terminal.js";
+/**
+ * Attaches an interactive shell to a running container — the
+ * `docker exec -it <container> <shell>` a developer would type by hand.
+ * Returns the shell's exit code so the caller decides what to do with the
+ * process.
+ *
+ * Pairs naturally with a custom sandbox command:
+ *
+ * ```typescript
+ * commands: {
+ *   shell: {
+ *     description: "Open a shell inside the workspace container",
+ *     run: ({ physicalName, argv }) => attachShell(physicalName("workspace"), { shell: argv[0] }),
+ *   },
+ * }
+ * ```
+ */
+export function attachShell(containerName, options = {}) {
+    const shell = options.shell ?? "/bin/bash";
+    process.stdout.write(`Attaching to ${containerName} (${shell})...\n`);
+    const result = spawnSync("docker", ["exec", "-it", containerName, shell], { stdio: "inherit" });
+    if (result.error) {
+        fail(`Failed to run docker: ${result.error.message}`);
+        return 1;
+    }
+    if (result.status !== 0) {
+        fail(`docker exec exited with ${result.status ?? "no status"}.`, [
+            `Is the container running? Start it with the "create" action.`,
+        ]);
+    }
+    return result.status ?? 0;
+}

package/dist/environment-file.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A value renderable into an environment file. Strings pass through,
+ * numbers and booleans are stringified, and plain objects or arrays are
+ * JSON-serialized — convenient for variables that carry structured
+ * configuration (service discovery maps, feature matrices).
+ */
+export type EnvironmentValue = string | number | boolean | object;
+/** A group of related variables, rendered together and separated from other groups by a blank line. */
+export type EnvironmentValues = Record<string, EnvironmentValue>;
+/**
+ * An ordered, incrementally-built `.env` file.
+ *
+ * Programs accumulate variables as the infrastructure comes together — static
+ * ports first, then connection strings, then values that only exist once
+ * Pulumi outputs resolve — and render the file at the end:
+ *
+ * ```typescript
+ * const env = new EnvironmentFile([{ APP_HTTP_PORT: 8080 }]);
+ * env.add({ DATABASE_URL: `postgresql://localhost:${db.hostPort}/app` });
+ * env.write("application/.env.local");
+ * ```
+ *
+ * Semantics:
+ * - Insertion order is preserved; each {@link add} call starts a new group
+ *   separated from the previous one by a blank line.
+ * - Re-adding an existing key overwrites its value in place, so the file
+ *   never contains duplicate keys and the layout stays stable.
+ * - An empty string renders as a commented-out `# KEY=` line — present for
+ *   discoverability, inactive for the loader.
+ * - `undefined` and `null` throw {@link EnvironmentFileError} immediately:
+ *   they are always a sign of an unresolved output or missing configuration,
+ *   and a loud failure beats a poisoned environment file.
+ */
+export declare class EnvironmentFile {
+    #private;
+    constructor(groups?: readonly EnvironmentValues[]);
+    /**
+     * Adds a group of variables, overwriting values for keys that already
+     * exist and appending the rest as a new blank-line-separated group.
+     */
+    add(values: EnvironmentValues): this;
+    /** Starts a new group; consecutive separators collapse into one blank line. */
+    addSeparator(): this;
+    /** Whether a variable has been declared. */
+    has(key: string): boolean;
+    /**
+     * The effective variables, each rendered to its final string form.
+     * Mirrors {@link render}: keys whose value is the empty string are
+     * commented out in the file and therefore omitted here, so both
+     * consumption paths observe the same environment.
+     */
+    values(): Record<string, string>;
+    /** Renders the file content, ending with a newline. */
+    render(): string;
+    /** Renders and writes the file, creating parent directories as needed. */
+    write(filePath: string): void;
+}
+//# sourceMappingURL=environment-file.d.ts.map

package/dist/environment-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-file.d.ts","sourceRoot":"","sources":["../src/environment-file.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAElE,uGAAuG;AACvG,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAMjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAe;;gBAId,MAAM,GAAE,SAAS,iBAAiB,EAAO;IAMrD;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAuBpC,+EAA+E;IAC/E,YAAY,IAAI,IAAI;IAOpB,4CAA4C;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;;;OAKG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAWhC,uDAAuD;IACvD,MAAM,IAAI,MAAM;IAWhB,0EAA0E;IAC1E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CA2B9B"}

package/dist/environment-file.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EnvironmentFileError } from "./errors.js";
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * An ordered, incrementally-built `.env` file.
+ *
+ * Programs accumulate variables as the infrastructure comes together — static
+ * ports first, then connection strings, then values that only exist once
+ * Pulumi outputs resolve — and render the file at the end:
+ *
+ * ```typescript
+ * const env = new EnvironmentFile([{ APP_HTTP_PORT: 8080 }]);
+ * env.add({ DATABASE_URL: `postgresql://localhost:${db.hostPort}/app` });
+ * env.write("application/.env.local");
+ * ```
+ *
+ * Semantics:
+ * - Insertion order is preserved; each {@link add} call starts a new group
+ *   separated from the previous one by a blank line.
+ * - Re-adding an existing key overwrites its value in place, so the file
+ *   never contains duplicate keys and the layout stays stable.
+ * - An empty string renders as a commented-out `# KEY=` line — present for
+ *   discoverability, inactive for the loader.
+ * - `undefined` and `null` throw {@link EnvironmentFileError} immediately:
+ *   they are always a sign of an unresolved output or missing configuration,
+ *   and a loud failure beats a poisoned environment file.
+ */
+export class EnvironmentFile {
+    #lines = [];
+    #entries = new Map();
+    constructor(groups = []) {
+        for (const group of groups) {
+            this.add(group);
+        }
+    }
+    /**
+     * Adds a group of variables, overwriting values for keys that already
+     * exist and appending the rest as a new blank-line-separated group.
+     */
+    add(values) {
+        const additions = [];
+        for (const [key, value] of Object.entries(values)) {
+            this.#validate(key, value);
+            const existing = this.#entries.get(key);
+            if (existing) {
+                existing.value = value;
+            }
+            else {
+                additions.push([key, value]);
+            }
+        }
+        if (additions.length > 0) {
+            this.addSeparator();
+            for (const [key, value] of additions) {
+                const entry = { kind: "entry", key, value };
+                this.#lines.push(entry);
+                this.#entries.set(key, entry);
+            }
+        }
+        return this;
+    }
+    /** Starts a new group; consecutive separators collapse into one blank line. */
+    addSeparator() {
+        if (this.#lines.length > 0 && this.#lines.at(-1)?.kind !== "separator") {
+            this.#lines.push({ kind: "separator" });
+        }
+        return this;
+    }
+    /** Whether a variable has been declared. */
+    has(key) {
+        return this.#entries.has(key);
+    }
+    /**
+     * The effective variables, each rendered to its final string form.
+     * Mirrors {@link render}: keys whose value is the empty string are
+     * commented out in the file and therefore omitted here, so both
+     * consumption paths observe the same environment.
+     */
+    values() {
+        const rendered = {};
+        for (const [key, entry] of this.#entries) {
+            const value = renderValue(entry.key, entry.value);
+            if (value !== "") {
+                rendered[key] = value;
+            }
+        }
+        return rendered;
+    }
+    /** Renders the file content, ending with a newline. */
+    render() {
+        const rendered = this.#lines.map((line) => {
+            if (line.kind === "separator") {
+                return "";
+            }
+            const value = renderValue(line.key, line.value);
+            return value === "" ? `# ${line.key}=` : `${line.key}=${value}`;
+        });
+        return `${rendered.join("\n")}\n`;
+    }
+    /** Renders and writes the file, creating parent directories as needed. */
+    write(filePath) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, this.render());
+    }
+    #validate(key, value) {
+        if (!KEY_PATTERN.test(key)) {
+            throw new EnvironmentFileError(`"${key}" is not a valid environment variable name (letters, digits, and underscores only).`);
+        }
+        if (value === undefined || value === null) {
+            throw new EnvironmentFileError(`The value for "${key}" is ${String(value)} — typically an unresolved Pulumi output or missing configuration.`);
+        }
+        // Duck-typed on the marker property so this module stays free of any
+        // @pulumi/pulumi import; pulumi.Output.isInstance checks the same key.
+        if (typeof value === "object" && "__pulumiOutput" in value) {
+            throw new EnvironmentFileError(`The value for "${key}" is an unresolved Pulumi output — resolve it first, e.g. with deepResolve(...).apply(...).`);
+        }
+        if (typeof value === "function") {
+            throw new EnvironmentFileError(`The value for "${key}" is a function, which cannot be rendered.`);
+        }
+    }
+}
+function renderValue(key, value) {
+    const rendered = typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value);
+    if (rendered.includes("\n")) {
+        throw new EnvironmentFileError(`The value for "${key}" contains a newline, which would corrupt the file.`);
+    }
+    return rendered;
+}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base class for every error raised by the sandbox harness. Library code
+ * throws typed errors and never calls `process.exit` itself; the command
+ * line dispatcher in `sandbox()` converts them into friendly output and an
+ * exit code, so the same functions stay usable from tests and custom tools.
+ */
+export declare class SandboxError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The sandbox cannot start because the developer machine or configuration is
+ * incomplete (missing developer id, Pulumi CLI not installed, invalid
+ * option values). Carries remediation lines that the dispatcher prints under
+ * the error message.
+ */
+export declare class SandboxConfigurationError extends SandboxError {
+    /** Remediation steps shown to the developer, one line each. */
+    readonly remediation: readonly string[];
+    constructor(message: string, remediation?: readonly string[], options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Another process holds the Pulumi state lock for this stack — usually a
+ * previous run that was interrupted. Surfaced as a hint to run the `cancel`
+ * action instead of a stack trace, and never swallowed, so a `reset` whose
+ * destroy half hits the lock does not silently proceed to create.
+ */
+export declare class SandboxLockError extends SandboxError {
+    readonly stackName: string;
+    constructor(stackName: string);
+}
+/**
+ * A value could not be rendered into an environment file — an `undefined` or
+ * `null` slipped into the declared values, typically an unresolved Pulumi
+ * output or a missing configuration entry. Failing loudly here keeps the
+ * poisoned value out of the generated file.
+ */
+export declare class EnvironmentFileError extends SandboxError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IACzD,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,SAAS,MAAM,EAAO,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhG;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAI9B;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG"}

package/dist/errors.js

@@ -0,0 +1,47 @@
+/**
+ * Base class for every error raised by the sandbox harness. Library code
+ * throws typed errors and never calls `process.exit` itself; the command
+ * line dispatcher in `sandbox()` converts them into friendly output and an
+ * exit code, so the same functions stay usable from tests and custom tools.
+ */
+export class SandboxError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The sandbox cannot start because the developer machine or configuration is
+ * incomplete (missing developer id, Pulumi CLI not installed, invalid
+ * option values). Carries remediation lines that the dispatcher prints under
+ * the error message.
+ */
+export class SandboxConfigurationError extends SandboxError {
+    /** Remediation steps shown to the developer, one line each. */
+    remediation;
+    constructor(message, remediation = [], options) {
+        super(message, options);
+        this.remediation = remediation;
+    }
+}
+/**
+ * Another process holds the Pulumi state lock for this stack — usually a
+ * previous run that was interrupted. Surfaced as a hint to run the `cancel`
+ * action instead of a stack trace, and never swallowed, so a `reset` whose
+ * destroy half hits the lock does not silently proceed to create.
+ */
+export class SandboxLockError extends SandboxError {
+    stackName;
+    constructor(stackName) {
+        super(`The stack "${stackName}" is locked by another update.`);
+        this.stackName = stackName;
+    }
+}
+/**
+ * A value could not be rendered into an environment file — an `undefined` or
+ * `null` slipped into the declared values, typically an unresolved Pulumi
+ * output or a missing configuration entry. Failing loudly here keeps the
+ * poisoned value out of the generated file.
+ */
+export class EnvironmentFileError extends SandboxError {
+}

package/dist/git.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Finds the root of the git repository containing `startDirectory` (default:
+ * the current working directory) by walking up until a `.git` entry appears.
+ * Returns `undefined` outside a repository.
+ *
+ * Both a `.git` directory (regular checkout) and a `.git` file (worktrees
+ * and submodules store a pointer file instead) count, so sandboxes work from
+ * any kind of checkout.
+ */
+export declare function findGitRoot(startDirectory?: string): string | undefined;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,cAAc,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAYtF"}

package/dist/git.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+import fs from "node:fs";
+/**
+ * Finds the root of the git repository containing `startDirectory` (default:
+ * the current working directory) by walking up until a `.git` entry appears.
+ * Returns `undefined` outside a repository.
+ *
+ * Both a `.git` directory (regular checkout) and a `.git` file (worktrees
+ * and submodules store a pointer file instead) count, so sandboxes work from
+ * any kind of checkout.
+ */
+export function findGitRoot(startDirectory = process.cwd()) {
+    let current = path.resolve(startDirectory);
+    while (true) {
+        if (fs.existsSync(path.join(current, ".git"))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,55 @@
+/** Environment variable that carries the developer identity. */
+export declare const DEV_ID_VARIABLE = "SANDBOX_DEV_ID";
+/**
+ * Default developer identity when none is configured. A single-developer
+ * machine works out of the box; teams opt into explicit ids with
+ * `require: true`.
+ */
+export declare const DEFAULT_DEV_ID = "local";
+export interface DevIdOptions {
+    /** Explicit developer id; takes precedence over every other source. */
+    devId?: string | undefined;
+    /**
+     * Optional `KEY=value` file consulted when the environment variable is not
+     * set — typically a git-ignored `.env` next to the infrastructure entry
+     * point, so each developer configures their identity once per checkout.
+     */
+    envFile?: string | undefined;
+    /**
+     * Fail instead of falling back to {@link DEFAULT_DEV_ID}. Teams sharing a
+     * remote backend set this so two developers can never collide on the
+     * default stack.
+     */
+    require?: boolean | undefined;
+    /** Environment to read from; defaults to `process.env`. */
+    environment?: Record<string, string | undefined> | undefined;
+}
+/**
+ * Resolves the developer identity that isolates stacks, containers, and
+ * volumes per developer. Resolution order: the explicit `devId` option, the
+ * `SANDBOX_DEV_ID` environment variable, the optional `envFile`, then
+ * {@link DEFAULT_DEV_ID}.
+ *
+ * The id becomes part of stack names, container names, and volume names, so
+ * it is restricted to lowercase letters, digits, and dashes.
+ */
+export declare function resolveDevId(options?: DevIdOptions): string;
+/**
+ * Parses `KEY=value` content in the dotenv style: blank lines and lines
+ * starting with `#` are skipped, the first `=` separates key from value, and
+ * both sides are trimmed. No quoting or interpolation — sandbox
+ * configuration files stay trivially predictable.
+ */
+export declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * Reads and parses a `KEY=value` file, returning `undefined` when the file
+ * does not exist so callers can distinguish "not configured" from "empty".
+ */
+export declare function readEnvFile(filePath: string): Record<string, string> | undefined;
+/**
+ * Interprets a configuration value as a boolean flag. Accepts `true`,
+ * `false`, `1`, `0`, `yes`, `no`, `on`, and `off` case-insensitively;
+ * anything else — including a missing value — yields `defaultValue`.
+ */
+export declare function booleanFlag(value: string | undefined, defaultValue: boolean): boolean;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAGA,gEAAgE;AAChE,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAItC,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE9B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,YAAiB,GAAG,MAAM,CA8B/D;AAYD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAapE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAKhF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CASrF"}

package/dist/identity.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import { SandboxConfigurationError } from "./errors.js";
+/** Environment variable that carries the developer identity. */
+export const DEV_ID_VARIABLE = "SANDBOX_DEV_ID";
+/**
+ * Default developer identity when none is configured. A single-developer
+ * machine works out of the box; teams opt into explicit ids with
+ * `require: true`.
+ */
+export const DEFAULT_DEV_ID = "local";
+const DEV_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Resolves the developer identity that isolates stacks, containers, and
+ * volumes per developer. Resolution order: the explicit `devId` option, the
+ * `SANDBOX_DEV_ID` environment variable, the optional `envFile`, then
+ * {@link DEFAULT_DEV_ID}.
+ *
+ * The id becomes part of stack names, container names, and volume names, so
+ * it is restricted to lowercase letters, digits, and dashes.
+ */
+export function resolveDevId(options = {}) {
+    const environment = options.environment ?? process.env;
+    if (options.devId !== undefined) {
+        return validateDevId(options.devId.trim());
+    }
+    const fromEnvironment = environment[DEV_ID_VARIABLE]?.trim();
+    if (fromEnvironment) {
+        return validateDevId(fromEnvironment);
+    }
+    if (options.envFile !== undefined) {
+        const fromFile = readEnvFile(options.envFile)?.[DEV_ID_VARIABLE]?.trim();
+        if (fromFile) {
+            return validateDevId(fromFile);
+        }
+    }
+    if (options.require) {
+        throw new SandboxConfigurationError("No developer id is configured, and this sandbox requires one.", [
+            `Set the ${DEV_ID_VARIABLE} environment variable to a short personal id (for example: jdoe),`,
+            ...(options.envFile !== undefined ? [`or add "${DEV_ID_VARIABLE}=jdoe" to ${options.envFile}.`] : []),
+        ]);
+    }
+    return DEFAULT_DEV_ID;
+}
+function validateDevId(devId) {
+    if (!DEV_ID_PATTERN.test(devId)) {
+        throw new SandboxConfigurationError(`The developer id "${devId}" is not usable in stack and container names.`, ["Use lowercase letters, digits, and dashes, starting with a letter or digit (for example: jdoe)."]);
+    }
+    return devId;
+}
+/**
+ * Parses `KEY=value` content in the dotenv style: blank lines and lines
+ * starting with `#` are skipped, the first `=` separates key from value, and
+ * both sides are trimmed. No quoting or interpolation — sandbox
+ * configuration files stay trivially predictable.
+ */
+export function parseEnvFile(content) {
+    const values = {};
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            continue;
+        }
+        const separator = trimmed.indexOf("=");
+        if (separator > 0) {
+            values[trimmed.slice(0, separator).trim()] = trimmed.slice(separator + 1).trim();
+        }
+    }
+    return values;
+}
+/**
+ * Reads and parses a `KEY=value` file, returning `undefined` when the file
+ * does not exist so callers can distinguish "not configured" from "empty".
+ */
+export function readEnvFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return undefined;
+    }
+    return parseEnvFile(fs.readFileSync(filePath, "utf-8"));
+}
+/**
+ * Interprets a configuration value as a boolean flag. Accepts `true`,
+ * `false`, `1`, `0`, `yes`, `no`, `on`, and `off` case-insensitively;
+ * anything else — including a missing value — yields `defaultValue`.
+ */
+export function booleanFlag(value, defaultValue) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+        return true;
+    }
+    if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+        return false;
+    }
+    return defaultValue;
+}