pulumi-sandbox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The pulumi-sandbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# Pulumi Sandbox
+
+[![ci](https://github.com/cgardev/pulumi-sandbox/actions/workflows/ci.yml/badge.svg)](https://github.com/cgardev/pulumi-sandbox/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pulumi-sandbox)](https://www.npmjs.com/package/pulumi-sandbox)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Local development sandboxes as code.**
+
+Write a plain [Pulumi](https://www.pulumi.com) program describing the local
+infrastructure your application needs — containers, databases, message
+brokers, identity servers — and get a complete, per-developer sandbox
+lifecycle around it. No backend account, no YAML, no glue scripts.
+
+```typescript
+// src/sandbox.ts
+import * as docker from "@pulumi/docker";
+import { sandbox } from "pulumi-sandbox";
+
+await sandbox({ name: "shop" }, (context) => {
+  const image = new docker.RemoteImage("postgres", { name: "postgres:18", keepLocally: true });
+
+  new docker.Container("database", {
+    image: image.imageId,
+    name: context.physicalName("database"),
+    ports: [{ internal: 5432, external: 25432 }],
+    envs: ["POSTGRES_USER=dev", "POSTGRES_PASSWORD=dev", "POSTGRES_DB=shop"],
+    mustRun: true,
+  }, { deleteBeforeReplace: true });
+});
+```
+
+```bash
+node src/sandbox.ts create     # provision (or update) the sandbox
+node src/sandbox.ts destroy    # tear it down
+node src/sandbox.ts            # interactive menu
+```
+
+That is the entire setup. State lives in a git-ignored `.sandbox/` directory
+on the local `file://` backend; with Node.js 24+ the TypeScript entry point
+runs directly, no build step involved.
+
+## Why not docker-compose?
+
+A compose file describes containers. A sandbox program describes an
+*environment*: it can wait for a server to boot before configuring realms
+inside it, generate credentials and render them into the `.env` files your
+applications load, derive a container per module of your repository, and
+reuse every Pulumi provider in existence. With the full expressiveness of
+TypeScript — loops, functions, composition — complex topologies (one database
+per service, port plans, cross-service wiring) stay readable.
+
+This library supplies everything *around* that program, so a project's
+infrastructure entry point contains nothing but infrastructure.
+
+## What you get
+
+- **Zero-configuration state.** A self-contained `file://` backend under
+  `.sandbox/` — no Pulumi account, no cloud bucket, nothing to log into.
+  Point `backendUrl` at `s3://...` later if the team wants shared state.
+- **Per-developer isolation.** A developer id (from `SANDBOX_DEV_ID`, an
+  optional `.env` file, or the `local` default) suffixes the stack and every
+  physical resource name, so two developers on one machine — or two checkouts
+  given distinct `SANDBOX_DEV_ID` values — never collide.
+- **A complete lifecycle.** `create`, `destroy`, `reset`, `preview`,
+  `cancel`, `outputs`, `help`, an interactive menu, and your own custom
+  commands — with readable output and honest exit codes.
+- **A lifecycle that survives reality.** Refresh is folded into `create` and
+  `destroy`, so containers killed by hand drop out of state instead of
+  failing the run. Providers hosted *inside* sandbox-managed containers
+  (Keycloak realms, database schemas) get state surgery on destroy and a
+  purge-and-retry on create — see below.
+- **Developer-experience helpers.** `EnvironmentFile` renders ordered,
+  grouped `.env` files; `deepResolve` turns a tree of Pulumi outputs into one
+  concrete value; `readyWhenHttp` gates providers on a service actually
+  booting; `findGitRoot` anchors paths; `pulumi-sandbox/docker` adds
+  `attachShell`, `dockerExec`, and rule-driven mask-volume discovery.
+- **A tiny, generic core.** ESM, fully typed, zero runtime dependencies, and
+  `@pulumi/pulumi` as the only peer dependency. The library has no knowledge
+  of any particular database, build tool, or identity server — your program
+  and your rules carry the specifics.
+
+## Requirements
+
+- Node.js >= 24
+- The [Pulumi CLI](https://www.pulumi.com/docs/install/) on the PATH (no account needed)
+- Docker, when the program manages containers
+
+```bash
+pnpm add pulumi-sandbox @pulumi/pulumi
+# plus the providers your program uses, e.g. for containers:
+pnpm add @pulumi/docker
+```
+
+## The lifecycle
+
+| Action     | What happens                                                                                  |
+|:-----------|:----------------------------------------------------------------------------------------------|
+| `create`   | `up` with refresh folded in; on failure, purge container-hosted provider state and retry once |
+| `destroy`  | Purge container-hosted provider state, then `destroy` with refresh folded in                  |
+| `reset`    | `destroy` followed by `create`, in one process                                                |
+| `preview`  | Diffed preview of what `create` would change                                                  |
+| `cancel`   | Release a stuck state lock left by an interrupted run                                         |
+| `outputs`  | Print the stack outputs as JSON                                                               |
+| *(none)*   | Interactive menu over all of the above                                                        |
+
+A concurrent-update collision is reported as a hint to run `cancel`, never as
+a stack trace — and a `reset` whose destroy half hits the lock stops instead
+of silently proceeding.
+
+## The context
+
+The program receives a context describing the run:
+
+```typescript
+await sandbox({ name: "shop" }, (context) => {
+  context.devId;                       // "jdoe" — the resolved developer id
+  context.stackName;                   // "shop-jdoe"
+  context.physicalName("orders-db");   // "shop-orders-db-jdoe"
+  context.action;                      // the lifecycle operation executing the program
+});
+```
+
+`physicalName` keeps container, network, and volume names collision-free per
+developer. `action` is the operation currently executing the program —
+`create` or `preview` — and gates side effects like writing generated
+artifacts. The program only runs for operations that need the resource
+graph; a `destroy` works from the recorded state and never executes it, so
+programs need no destroy-time guards.
+
+Returning a record from the program publishes it as stack outputs:
+
+```typescript
+await sandbox({ name: "shop" }, () => {
+  return { adminUrl: "http://localhost:25080" };
+});
+```
+
+## Container-hosted providers
+
+Some providers manage resources *inside* a container the sandbox itself
+runs — realms inside a Keycloak container, schemas inside a database
+container. Pulumi treats those resources as independent of the container, so
+when the container disappears (a destroy, or a developer's `docker rm`), any
+refresh, update, or destroy aborts while initializing a provider whose
+service no longer exists.
+
+Declare such providers and the lifecycle handles the rest:
+
+```typescript
+await sandbox(
+  { name: "shop", containerHostedProviders: ["identity"] },
+  () => {
+    const identity = new IdentityServer(/* keycloak container + sidecar */);
+
+    const provider = new keycloak.Provider("identity", {
+      url: identity.readyUrl,  // configures itself only after boot
+      // ...
+    });
+    new keycloak.Realm("shop", { realm: "shop" }, {
+      provider,
+      retainOnDelete: true,            // safety net for partial destroys
+      deletedWith: identity.container, // documents the dependency
+    });
+  },
+);
+```
+
+On `destroy`, the provider and everything it manages are removed from state
+before the plan runs — the container teardown wipes them physically, so
+nothing needs to talk to the doomed service. On `create`, a failed update
+triggers the same purge and a single retry, which recovers sandboxes whose
+containers were removed out-of-band. The mechanism is generic: any provider
+resource name can be listed, and `purgeProviderFromState` is exported for
+custom flows.
+
+## Rendering configuration for applications
+
+Sandboxes exist so applications can run against them. `EnvironmentFile`
+accumulates variables in ordered, blank-line-separated groups; `deepResolve`
+collapses any tree of Pulumi outputs into one concrete value, so generated
+credentials land in the same file as static ports:
+
+```typescript
+import { EnvironmentFile, deepResolve } from "pulumi-sandbox";
+
+const environment = new EnvironmentFile([
+  { ORDERS_DATABASE_URL: ordersDatabase.connectionUri },
+  { SMTP_HOST: "localhost", SMTP_PORT: 25025 },
+]);
+
+if (context.action === "create") {
+  deepResolve({ secret: ordersApi.clientSecret }).apply(({ secret }) => {
+    environment.add({ OIDC_CLIENT_SECRET: secret });
+    environment.write("generated/orders.env");
+  });
+}
+```
+
+An `undefined` or `null` value throws immediately with the offending key —
+a loud failure beats a poisoned environment file.
+
+## Custom commands
+
+Verbs beyond the lifecycle dispatch before any Pulumi machinery starts, so
+they stay instant:
+
+```typescript
+import { attachShell } from "pulumi-sandbox/docker";
+
+await sandbox(
+  {
+    name: "workspace",
+    commands: {
+      shell: {
+        description: "Open a shell inside the workspace container",
+        run: ({ physicalName, argv }) => attachShell(physicalName("dev"), { shell: argv[0] }),
+      },
+    },
+  },
+  program,
+);
+```
+
+## Examples
+
+| Example                                        | Shows                                                                                   |
+|:-----------------------------------------------|:----------------------------------------------------------------------------------------|
+| [`getting-started`](examples/getting-started)  | One database, one generated `.env` — the minimal loop                                   |
+| [`multi-service`](examples/multi-service)      | Databases per service, mail catcher, Keycloak realm via a container-hosted provider     |
+| [`dev-workspace`](examples/dev-workspace)      | A containerized development environment with rule-discovered mask volumes and a `shell` command |
+
+## State layout and portability
+
+```
+.sandbox/             # add to .gitignore
+├── state/            # the file:// backend: checkpoints, history, backups
+└── work/<project>/   # the generated Pulumi project and per-stack settings
+```
+
+By default `.sandbox/` lives in the package containing the entry script —
+anchored there rather than to the working directory, so invoking the sandbox
+from anywhere targets the same state. Override the location with `homeDir`.
+
+Secrets on the local backend are encrypted with a well-known default
+passphrase (`sandbox`) to keep the zero-configuration promise — local
+sandboxes hold throwaway development credentials. Override `passphrase` or
+set `PULUMI_CONFIG_PASSPHRASE` when pointing at a shared backend.
+
+The `file://` URL is built in the one form Pulumi's DIY backend accepts on
+both Windows and POSIX (`fileBackendUrl`), so the same entry point works for
+the whole team.
+
+## API overview
+
+Core (`pulumi-sandbox`):
+
+- `sandbox(options, program)` — the complete entry point: dispatch, lifecycle, error rendering
+- `createSandbox(options, program)` / `Sandbox` — programmatic control, the underlying `automation.Stack` included
+- `EnvironmentFile`, `deepResolve`, `waitForHttp`, `readyWhenHttp`, `findGitRoot`
+- `resolveDevId`, `parseEnvFile`, `readEnvFile`, `booleanFlag`
+- `purgeProviderFromState`, `removeProviderFromDeployment`
+- `fileBackendUrl`, `resolveDirectories`, `ensureDirectories`
+- `SandboxError`, `SandboxConfigurationError`, `SandboxLockError`, `EnvironmentFileError`
+
+Docker utilities (`pulumi-sandbox/docker`, host-side, no `@pulumi/docker` required):
+
+- `attachShell(containerName, options)` — interactive `docker exec`
+- `dockerExec(containerName, command, options)` — idempotent post-boot configuration
+- `discoverMaskVolumes(root, { containerRoot, rules })` — rule-driven discovery of directories to mask with container-local volumes
+
+## Development
+
+```bash
+pnpm install
+pnpm build      # compile to dist/
+pnpm check      # type-check sources and tests
+pnpm test       # vitest
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/actions.d.ts

@@ -0,0 +1,7 @@
+/** Lifecycle verbs understood by every sandbox. */
+export declare const LIFECYCLE_ACTIONS: readonly ["create", "destroy", "reset", "preview", "cancel", "outputs"];
+export type LifecycleAction = (typeof LIFECYCLE_ACTIONS)[number];
+/** One-line description per lifecycle verb, shared by `help` and the interactive menu. */
+export declare const ACTION_DESCRIPTIONS: Record<LifecycleAction, string>;
+export declare function isLifecycleAction(verb: string): verb is LifecycleAction;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,yEAA0E,CAAC;AAEzG,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,0FAA0F;AAC1F,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAO/D,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE"}

package/dist/actions.js

@@ -0,0 +1,14 @@
+/** Lifecycle verbs understood by every sandbox. */
+export const LIFECYCLE_ACTIONS = ["create", "destroy", "reset", "preview", "cancel", "outputs"];
+/** One-line description per lifecycle verb, shared by `help` and the interactive menu. */
+export const ACTION_DESCRIPTIONS = {
+    create: "Provision the sandbox, or update it to match the program",
+    destroy: "Tear down every resource the sandbox manages",
+    reset: "Destroy, then create — a clean slate in one command",
+    preview: "Show what create would change, without changing it",
+    cancel: "Release a stuck state lock left by an interrupted run",
+    outputs: "Print the stack outputs as JSON",
+};
+export function isLifecycleAction(verb) {
+    return LIFECYCLE_ACTIONS.includes(verb);
+}

package/dist/backend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Builds the `file://` URL for Pulumi's DIY (self-managed) backend from an
+ * absolute directory path.
+ *
+ * Node's `pathToFileURL` produces a triple-slash URL (`file:///D:/...`) that
+ * the DIY backend mis-parses on Windows — it re-prepends the drive, yielding
+ * `file:///D:/D:/...` and a "filename ... syntax is incorrect" error. The
+ * form Pulumi accepts on Windows is `file://D:/forward/slash/path`.
+ * Prefixing the absolute path (with forward slashes) with `file://` gives
+ * exactly that on Windows and the correct `file:///absolute/path` on POSIX,
+ * where the path already starts with `/`.
+ */
+export declare function fileBackendUrl(absoluteDirectory: string): string;
+/**
+ * On-disk layout of a local sandbox. Everything lives under a single home
+ * directory (default `.sandbox/`, git-ignored) so a checkout can be cleaned
+ * with one deletion and nothing machine-specific is ever committed.
+ */
+export interface SandboxDirectories {
+    /** Root of the sandbox-managed files. */
+    home: string;
+    /** Pulumi DIY backend storage — checkpoints, history, backups, locks. */
+    state: string;
+    /** Pulumi work directory — the generated project and per-stack settings. */
+    work: string;
+}
+/**
+ * Resolves the directory layout under the given sandbox home directory. The
+ * work directory is scoped per project so two sandboxes sharing a home never
+ * fight over the generated project file; the state directory is shared, as
+ * the DIY backend already namespaces checkpoints by project.
+ */
+export declare function resolveDirectories(homeDirectory: string, projectName: string): SandboxDirectories;
+/**
+ * Creates the sandbox directories. Both must exist before the Pulumi
+ * workspace is constructed: the file backend needs somewhere to write its
+ * checkpoint, and the work directory receives the generated project file.
+ */
+export declare function ensureDirectories(directories: SandboxDirectories): void;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAOjG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,kBAAkB,GAAG,IAAI,CAGvE"}

package/dist/backend.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import fs from "node:fs";
+/**
+ * Builds the `file://` URL for Pulumi's DIY (self-managed) backend from an
+ * absolute directory path.
+ *
+ * Node's `pathToFileURL` produces a triple-slash URL (`file:///D:/...`) that
+ * the DIY backend mis-parses on Windows — it re-prepends the drive, yielding
+ * `file:///D:/D:/...` and a "filename ... syntax is incorrect" error. The
+ * form Pulumi accepts on Windows is `file://D:/forward/slash/path`.
+ * Prefixing the absolute path (with forward slashes) with `file://` gives
+ * exactly that on Windows and the correct `file:///absolute/path` on POSIX,
+ * where the path already starts with `/`.
+ */
+export function fileBackendUrl(absoluteDirectory) {
+    return `file://${absoluteDirectory.replace(/\\/g, "/")}`;
+}
+/**
+ * Resolves the directory layout under the given sandbox home directory. The
+ * work directory is scoped per project so two sandboxes sharing a home never
+ * fight over the generated project file; the state directory is shared, as
+ * the DIY backend already namespaces checkpoints by project.
+ */
+export function resolveDirectories(homeDirectory, projectName) {
+    const home = path.resolve(homeDirectory);
+    return {
+        home,
+        state: path.join(home, "state"),
+        work: path.join(home, "work", projectName),
+    };
+}
+/**
+ * Creates the sandbox directories. Both must exist before the Pulumi
+ * workspace is constructed: the file backend needs somewhere to write its
+ * checkpoint, and the work directory receives the generated project file.
+ */
+export function ensureDirectories(directories) {
+    fs.mkdirSync(directories.state, { recursive: true });
+    fs.mkdirSync(directories.work, { recursive: true });
+}

package/dist/docker/exec.d.ts

@@ -0,0 +1,22 @@
+export interface DockerExecOptions {
+    /**
+     * Warn and return `false` instead of throwing when the command fails.
+     * This is the right mode for post-boot configuration hooks: the service
+     * that actually needs the configuration will surface a clear error at its
+     * own layer, while a throw here would wedge destroy and refresh flows.
+     * Default: `true`.
+     */
+    warnOnly?: boolean | undefined;
+}
+/**
+ * Runs a command inside a running container via `docker exec`, for
+ * imperative post-boot configuration that no provider covers — unlocking an
+ * admin API, creating a seed user, flipping a development-only setting.
+ * Returns whether the command succeeded.
+ *
+ * Commands must be idempotent: readiness chains re-execute on every Pulumi
+ * operation, so the same configuration may run against an already-configured
+ * container.
+ */
+export declare function dockerExec(containerName: string, command: readonly string[], options?: DockerExecOptions): boolean;
+//# sourceMappingURL=exec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/docker/exec.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAatH"}

package/dist/docker/exec.js

@@ -0,0 +1,26 @@
+import { execFileSync } from "node:child_process";
+import { warn } from "../terminal.js";
+/**
+ * Runs a command inside a running container via `docker exec`, for
+ * imperative post-boot configuration that no provider covers — unlocking an
+ * admin API, creating a seed user, flipping a development-only setting.
+ * Returns whether the command succeeded.
+ *
+ * Commands must be idempotent: readiness chains re-execute on every Pulumi
+ * operation, so the same configuration may run against an already-configured
+ * container.
+ */
+export function dockerExec(containerName, command, options = {}) {
+    try {
+        execFileSync("docker", ["exec", containerName, ...command], { stdio: "pipe" });
+        return true;
+    }
+    catch (error) {
+        const detail = error.stderr?.toString().trim() || error.message;
+        if (options.warnOnly ?? true) {
+            warn(`docker exec in ${containerName} failed: ${detail}`);
+            return false;
+        }
+        throw error;
+    }
+}

package/dist/docker/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Host-side docker utilities — attaching shells, executing post-boot
+ * configuration, and discovering mask volumes. Nothing in this module
+ * touches Pulumi; it complements the resources a program declares.
+ */
+export { attachShell } from "./shell.js";
+export type { AttachShellOptions } from "./shell.js";
+export { dockerExec } from "./exec.js";
+export type { DockerExecOptions } from "./exec.js";
+export { discoverMaskVolumes } from "./mask-volumes.js";
+export type { MaskVolume, MaskRule, DiscoverMaskVolumesOptions } from "./mask-volumes.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docker/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/docker/index.js

@@ -0,0 +1,8 @@
+/**
+ * Host-side docker utilities — attaching shells, executing post-boot
+ * configuration, and discovering mask volumes. Nothing in this module
+ * touches Pulumi; it complements the resources a program declares.
+ */
+export { attachShell } from "./shell.js";
+export { dockerExec } from "./exec.js";
+export { discoverMaskVolumes } from "./mask-volumes.js";

package/dist/docker/mask-volumes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A named volume layered over a bind mount, identified by a stable key. The
+ * key is meant to be combined with a per-developer volume prefix into the
+ * physical volume name.
+ */
+export interface MaskVolume {
+    /** Stable, human-readable identifier derived from the rule and the repository path. */
+    key: string;
+    /** Where the volume mounts inside the container. */
+    containerPath: string;
+}
+/**
+ * Declares which directories a project tree generates locally and must
+ * therefore be masked. A rule fires in every walked directory containing one
+ * of its marker files; the rule's `mask` entries (and whatever `expand`
+ * derives from the marker's content) become container-local volumes.
+ *
+ * The library has no knowledge of any build tool — rules carry all of it.
+ * A JVM-and-Node repository, for example, is fully described by:
+ *
+ * ```typescript
+ * const rules: MaskRule[] = [
+ *   { prefix: "build", markers: ["build.gradle.kts", "settings.gradle.kts"], mask: ["build"] },
+ *   { prefix: "gradle", markers: ["settings.gradle.kts"], mask: [".gradle"] },
+ *   { prefix: "node-modules", markers: ["package.json"], mask: ["node_modules"] },
+ * ];
+ * ```
+ */
+export interface MaskRule {
+    /** Prefix for the volume keys this rule produces. */
+    prefix: string;
+    /** File names whose presence marks a directory as governed by this rule. */
+    markers: readonly string[];
+    /** Directories to mask, relative to the marked directory. */
+    mask: readonly string[];
+    /**
+     * Optional expansion hook: derives additional directories to mask from the
+     * content of the matched marker file — for build systems whose
+     * configuration references sibling project roots. Returned paths are
+     * resolved against the marker's directory and must stay inside the walked
+     * root; anything outside the bind mount cannot be masked and is skipped
+     * with a warning.
+     */
+    expand?: ((markerPath: string, content: string) => readonly string[]) | undefined;
+}
+export interface DiscoverMaskVolumesOptions {
+    /** Where the repository is bind-mounted inside the container, e.g. `/workspace`. */
+    containerRoot: string;
+    /** The rules describing which directories to mask. */
+    rules: readonly MaskRule[];
+    /**
+     * Directory names never descended into, on top of the directories actually
+     * masked and dot-directories (always skipped). Masking already prevents
+     * descending into a masked directory, but only where its rule fired — an
+     * unrelated directory that merely shares the name is still walked.
+     */
+    prune?: readonly string[] | undefined;
+}
+/**
+ * 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 declare function discoverMaskVolumes(rootDirectory: string, options: DiscoverMaskVolumesOptions): MaskVolume[];
+//# sourceMappingURL=mask-volumes.d.ts.map

package/dist/docker/mask-volumes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask-volumes.d.ts","sourceRoot":"","sources":["../../src/docker/mask-volumes.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IAEf,4EAA4E;IAC5E,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAE3B,6DAA6D;IAC7D,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAExB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;CACnF;AAED,MAAM,WAAW,0BAA0B;IACzC,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IAEtB,sDAAsD;IACtD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAE3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,UAAU,EAAE,CAgF5G"}