pulumi-sandbox 0.1.0

package/dist/sandbox.d.ts

@@ -0,0 +1,172 @@
+import { automation } from "@pulumi/pulumi";
+import { type LifecycleAction } from "./actions.js";
+/** Default passphrase for the local secrets provider — see {@link SandboxOptions.passphrase}. */
+export declare const DEFAULT_PASSPHRASE = "sandbox";
+export interface SandboxOptions {
+    /**
+     * Project name. It becomes the Pulumi project, prefixes the stack name,
+     * and seeds {@link SandboxContext.physicalName} — lowercase letters,
+     * digits, and dashes.
+     */
+    name: string;
+    /** Explicit developer id; usually left unset and resolved from the environment. */
+    devId?: string | undefined;
+    /**
+     * Refuse to fall back to the `local` developer id. Set this when the team
+     * shares a remote backend and accidental stack collisions must be
+     * impossible.
+     */
+    requireDevId?: boolean | undefined;
+    /**
+     * Optional `KEY=value` file (typically a git-ignored `.env`) consulted for
+     * `SANDBOX_DEV_ID` when the environment variable is not set.
+     */
+    envFile?: string | undefined;
+    /**
+     * Pulumi backend URL. Defaults to a self-contained `file://` backend under
+     * {@link SandboxOptions.homeDir} — no cloud account, no login. Point it at
+     * `s3://...` (or any other DIY backend) to share state remotely.
+     */
+    backendUrl?: string | undefined;
+    /**
+     * Directory holding sandbox state and the Pulumi work directory. Defaults
+     * to `.sandbox` in the package containing the entry script (the nearest
+     * directory with a `package.json`, falling back to the entry script's
+     * directory) — anchored there rather than to the working directory, so
+     * invoking the sandbox from anywhere targets the same state. Add it to
+     * `.gitignore`.
+     */
+    homeDir?: string | undefined;
+    /**
+     * Passphrase for Pulumi's secrets provider. Local sandboxes hold
+     * throwaway development credentials, so a well-known default keeps the
+     * zero-configuration promise; override it (or set
+     * `PULUMI_CONFIG_PASSPHRASE`) when the backend is shared.
+     */
+    passphrase?: string | undefined;
+    /**
+     * Names of provider resources whose backing service lives in a container
+     * this sandbox manages — for example `"identity"` when the program
+     * declares `new keycloak.Provider("identity", ...)` against a Keycloak
+     * container it also creates. These providers get state surgery during
+     * destroy (and on create retries), so tearing down or recreating the
+     * container never requires talking to the service it hosted.
+     */
+    containerHostedProviders?: readonly string[] | undefined;
+    /**
+     * Additional command line verbs, dispatched before any Pulumi machinery
+     * is initialized — ideal for fast utilities like opening a shell inside a
+     * running container.
+     */
+    commands?: Record<string, SandboxCommand> | undefined;
+    /** Command line arguments; defaults to `process.argv.slice(2)`. */
+    argv?: readonly string[] | undefined;
+}
+/**
+ * The program's view of the sandbox while resources are being declared.
+ *
+ * The program runs for operations that need the resource graph — `create`,
+ * `preview`, and the create half of `reset`. A `destroy` works from the
+ * recorded state and does not execute the program, so no destroy-time
+ * guards are needed in it.
+ */
+export interface SandboxContext {
+    readonly projectName: string;
+    readonly devId: string;
+    readonly stackName: string;
+    /**
+     * The lifecycle operation currently executing the program — `create` or
+     * `preview`. Use it to confine side effects like writing generated
+     * artifacts to real create runs:
+     *
+     * ```typescript
+     * if (context.action === "create") {
+     *   environment.write("generated/application.env");
+     * }
+     * ```
+     */
+    readonly action: LifecycleAction;
+    /**
+     * Builds a developer-scoped physical resource name:
+     * `physicalName("postgres")` → `myproject-postgres-jdoe`. Use it for
+     * container names, volume prefixes, and anything else that must not
+     * collide between developers on one machine.
+     */
+    physicalName(...parts: string[]): string;
+}
+/** The context handed to custom commands; no Pulumi machinery is involved. */
+export interface SandboxCommandContext {
+    readonly projectName: string;
+    readonly devId: string;
+    readonly stackName: string;
+    /** Arguments after the command verb. */
+    readonly argv: readonly string[];
+    physicalName(...parts: string[]): string;
+}
+/** A custom command line verb registered through {@link SandboxOptions.commands}. */
+export interface SandboxCommand {
+    /** One-line description shown by `help`. */
+    description: string;
+    /** Runs the command; a returned number becomes the process exit code. */
+    run(context: SandboxCommandContext): number | void | Promise<number | void>;
+}
+/** Values returned by the program; they become the stack outputs. */
+export type SandboxOutputs = Record<string, unknown>;
+/** The infrastructure program: a plain Pulumi inline program with a sandbox context. */
+export type SandboxProgram = (context: SandboxContext) => SandboxOutputs | void | Promise<SandboxOutputs | void>;
+/**
+ * A fully wired sandbox: the Pulumi stack (file backend, work directory,
+ * passphrase) plus the lifecycle operations. Most programs never construct
+ * one directly — {@link sandbox} builds it and dispatches the command line —
+ * but it is the entry point for programmatic control and tests.
+ */
+export declare class Sandbox {
+    #private;
+    readonly projectName: string;
+    readonly devId: string;
+    readonly stackName: string;
+    /** The underlying automation stack, for operations the lifecycle does not cover. */
+    readonly stack: automation.Stack;
+    /** @internal Use {@link createSandbox}. */
+    constructor(identity: SandboxIdentity, stack: automation.Stack, state: {
+        action: LifecycleAction;
+    }, containerHostedProviders: readonly string[]);
+    /** Runs one lifecycle action against the stack. */
+    run(action: LifecycleAction): Promise<void>;
+    create(): Promise<void>;
+    destroy(): Promise<void>;
+    reset(): Promise<void>;
+    preview(): Promise<void>;
+    cancel(): Promise<void>;
+}
+interface SandboxIdentity {
+    projectName: string;
+    devId: string;
+    stackName: string;
+    physicalName(...parts: string[]): string;
+}
+/**
+ * Builds a {@link Sandbox} without dispatching any action: resolves the
+ * developer identity, prepares the local backend and work directory, and
+ * creates or selects the stack with the inline program wired in.
+ */
+export declare function createSandbox(options: SandboxOptions, program: SandboxProgram): Promise<Sandbox>;
+/**
+ * The complete sandbox entry point: resolves the action from the command
+ * line, runs custom commands without touching Pulumi, drives the lifecycle
+ * for the rest, and renders every failure as a friendly message plus a
+ * non-zero exit code.
+ *
+ * ```typescript
+ * await sandbox({ name: "acme-shop" }, (context) => {
+ *   // plain Pulumi resources — containers, databases, providers
+ * });
+ * ```
+ *
+ * Invoked as `node infra.ts <action>` with `create | destroy | reset |
+ * preview | cancel | outputs`, any custom command, `help`, or no action at
+ * all for the interactive menu.
+ */
+export declare function sandbox(options: SandboxOptions, program: SandboxProgram): Promise<void>;
+export {};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

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

package/dist/sandbox.js

@@ -0,0 +1,260 @@
+import path from "node:path";
+import fs from "node:fs";
+import { automation } from "@pulumi/pulumi";
+import { ACTION_DESCRIPTIONS, LIFECYCLE_ACTIONS, isLifecycleAction } from "./actions.js";
+import { ensureDirectories, fileBackendUrl, resolveDirectories } from "./backend.js";
+import { SandboxConfigurationError, SandboxLockError } from "./errors.js";
+import { resolveDevId } from "./identity.js";
+import { runInteractiveMenu } from "./interactive.js";
+import { cancelStack, createStack, destroyStack, previewStack, printOutputs } from "./lifecycle.js";
+import { bold, cyan, dim, exitQuietlyOnClosedPipe, fail, heading, succeed } from "./terminal.js";
+const PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+/** Default passphrase for the local secrets provider — see {@link SandboxOptions.passphrase}. */
+export const DEFAULT_PASSPHRASE = "sandbox";
+/**
+ * A fully wired sandbox: the Pulumi stack (file backend, work directory,
+ * passphrase) plus the lifecycle operations. Most programs never construct
+ * one directly — {@link sandbox} builds it and dispatches the command line —
+ * but it is the entry point for programmatic control and tests.
+ */
+export class Sandbox {
+    projectName;
+    devId;
+    stackName;
+    /** The underlying automation stack, for operations the lifecycle does not cover. */
+    stack;
+    #host;
+    #state;
+    /** @internal Use {@link createSandbox}. */
+    constructor(identity, stack, state, containerHostedProviders) {
+        this.projectName = identity.projectName;
+        this.devId = identity.devId;
+        this.stackName = identity.stackName;
+        this.stack = stack;
+        this.#state = state;
+        this.#host = { stack, stackName: identity.stackName, containerHostedProviders };
+    }
+    /** Runs one lifecycle action against the stack. */
+    async run(action) {
+        switch (action) {
+            case "create":
+                this.#state.action = "create";
+                await createStack(this.#host);
+                succeed(`Sandbox ${this.stackName} is ready.`);
+                return;
+            case "destroy":
+                this.#state.action = "destroy";
+                await destroyStack(this.#host);
+                succeed(`Sandbox ${this.stackName} is gone.`);
+                return;
+            case "reset":
+                await this.run("destroy");
+                await this.run("create");
+                return;
+            case "preview":
+                this.#state.action = "preview";
+                await previewStack(this.#host);
+                return;
+            case "cancel":
+                await cancelStack(this.#host);
+                succeed("State lock released.");
+                return;
+            case "outputs":
+                await printOutputs(this.#host);
+                return;
+        }
+    }
+    create() {
+        return this.run("create");
+    }
+    destroy() {
+        return this.run("destroy");
+    }
+    reset() {
+        return this.run("reset");
+    }
+    preview() {
+        return this.run("preview");
+    }
+    cancel() {
+        return this.run("cancel");
+    }
+}
+function resolveIdentity(options) {
+    if (!PROJECT_NAME_PATTERN.test(options.name)) {
+        throw new SandboxConfigurationError(`The sandbox name "${options.name}" is not usable in stack and container names.`, ["Use lowercase letters, digits, and dashes, starting with a letter or digit (for example: acme-shop)."]);
+    }
+    const devId = resolveDevId({
+        devId: options.devId,
+        envFile: options.envFile,
+        require: options.requireDevId,
+    });
+    return {
+        projectName: options.name,
+        devId,
+        stackName: `${options.name}-${devId}`,
+        physicalName: (...parts) => [options.name, ...parts, devId].join("-"),
+    };
+}
+/**
+ * The default sandbox home: `.sandbox` in the package containing the entry
+ * script. Anchoring to the entry script rather than the working directory
+ * means `node tool/sandbox.ts destroy` targets the same state from any
+ * directory — a sandbox invoked from the wrong place must never conclude
+ * there is nothing to destroy.
+ */
+function defaultHomeDirectory() {
+    const entry = process.argv[1];
+    let directory = entry !== undefined ? path.dirname(path.resolve(entry)) : process.cwd();
+    let current = directory;
+    while (true) {
+        if (fs.existsSync(path.join(current, "package.json"))) {
+            directory = current;
+            break;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return path.join(directory, ".sandbox");
+}
+/**
+ * Builds a {@link Sandbox} without dispatching any action: resolves the
+ * developer identity, prepares the local backend and work directory, and
+ * creates or selects the stack with the inline program wired in.
+ */
+export async function createSandbox(options, program) {
+    const identity = resolveIdentity(options);
+    const directories = resolveDirectories(options.homeDir ?? defaultHomeDirectory(), identity.projectName);
+    ensureDirectories(directories);
+    const backendUrl = options.backendUrl ?? fileBackendUrl(directories.state);
+    const passphrase = options.passphrase ?? process.env.PULUMI_CONFIG_PASSPHRASE ?? DEFAULT_PASSPHRASE;
+    const state = { action: "preview" };
+    const context = {
+        projectName: identity.projectName,
+        devId: identity.devId,
+        stackName: identity.stackName,
+        get action() {
+            return state.action;
+        },
+        physicalName: identity.physicalName,
+    };
+    try {
+        const stack = await automation.LocalWorkspace.createOrSelectStack({
+            stackName: identity.stackName,
+            projectName: identity.projectName,
+            program: async () => (await program(context)) ?? undefined,
+        }, {
+            workDir: directories.work,
+            projectSettings: {
+                name: identity.projectName,
+                runtime: "nodejs",
+                backend: { url: backendUrl },
+            },
+            envVars: { PULUMI_CONFIG_PASSPHRASE: passphrase },
+        });
+        return new Sandbox(identity, stack, state, options.containerHostedProviders ?? []);
+    }
+    catch (error) {
+        throw translateWorkspaceError(error);
+    }
+}
+/**
+ * The complete sandbox entry point: resolves the action from the command
+ * line, runs custom commands without touching Pulumi, drives the lifecycle
+ * for the rest, and renders every failure as a friendly message plus a
+ * non-zero exit code.
+ *
+ * ```typescript
+ * await sandbox({ name: "acme-shop" }, (context) => {
+ *   // plain Pulumi resources — containers, databases, providers
+ * });
+ * ```
+ *
+ * Invoked as `node infra.ts <action>` with `create | destroy | reset |
+ * preview | cancel | outputs`, any custom command, `help`, or no action at
+ * all for the interactive menu.
+ */
+export async function sandbox(options, program) {
+    exitQuietlyOnClosedPipe();
+    const argv = [...(options.argv ?? process.argv.slice(2))];
+    const verb = argv[0] ?? "interactive";
+    try {
+        if (verb === "help" || verb === "--help" || verb === "-h") {
+            printHelp(options);
+            return;
+        }
+        const command = options.commands !== undefined && Object.hasOwn(options.commands, verb) ? options.commands[verb] : undefined;
+        if (command !== undefined) {
+            const exitCode = await command.run({ ...resolveIdentity(options), argv: argv.slice(1) });
+            if (typeof exitCode === "number" && exitCode !== 0) {
+                process.exitCode = exitCode;
+            }
+            return;
+        }
+        if (verb !== "interactive" && !isLifecycleAction(verb)) {
+            throw new SandboxConfigurationError(`Unknown action "${verb}".`, [
+                `Available actions: ${[...LIFECYCLE_ACTIONS, ...Object.keys(options.commands ?? {})].join(", ")} — or "help".`,
+            ]);
+        }
+        const instance = await createSandbox(options, program);
+        // The `outputs` verb keeps stdout machine-readable: nothing but JSON.
+        if (verb !== "outputs") {
+            heading(instance.projectName, instance.stackName, verb);
+        }
+        if (verb === "interactive") {
+            await runInteractiveMenu({
+                run: (action) => instance.run(action),
+                reportFailure,
+            });
+            return;
+        }
+        await instance.run(verb);
+    }
+    catch (error) {
+        reportFailure(error);
+        process.exitCode = 1;
+    }
+}
+function printHelp(options) {
+    process.stdout.write(`\n${bold(options.name)} — local development sandbox\n\n`);
+    process.stdout.write(`Usage: node <entry-file> ${cyan("<action>")}\n\n`);
+    for (const action of LIFECYCLE_ACTIONS) {
+        process.stdout.write(`  ${bold(action.padEnd(10))} ${dim(ACTION_DESCRIPTIONS[action])}\n`);
+    }
+    for (const [verb, command] of Object.entries(options.commands ?? {})) {
+        process.stdout.write(`  ${bold(verb.padEnd(10))} ${dim(command.description)}\n`);
+    }
+    process.stdout.write(`\nWithout an action, an interactive menu opens.\n`);
+}
+function reportFailure(error) {
+    if (error instanceof SandboxConfigurationError) {
+        fail(error.message, error.remediation);
+        return;
+    }
+    if (error instanceof SandboxLockError) {
+        fail(error.message, ['Release it with the "cancel" action once you are sure no other update is running.']);
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    // Failures of Pulumi operations arrive as a dump that repeats everything
+    // already streamed live; the only new information is the error lines.
+    const errorLines = [...new Set(message.split("\n").filter((line) => line.trimStart().startsWith("error:")))];
+    if (errorLines.length > 0) {
+        fail("The Pulumi operation failed.", errorLines);
+        return;
+    }
+    fail(message);
+}
+function translateWorkspaceError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("ENOENT") && message.toLowerCase().includes("pulumi")) {
+        return new SandboxConfigurationError("The Pulumi CLI is not installed (or not on the PATH).", [
+            "Install it from https://www.pulumi.com/docs/install/ — no Pulumi account is needed,",
+            "the sandbox keeps its state in a local file backend.",
+        ]);
+    }
+    return error;
+}

package/dist/state-surgery.d.ts

@@ -0,0 +1,34 @@
+import type { automation } from "@pulumi/pulumi";
+/** What a purge removed from the checkpoint. */
+export interface ProviderPurge {
+    /** URNs of the matched provider resources. */
+    providerUrns: string[];
+    /** Resources removed, providers included. */
+    removedResources: number;
+    /** Pending operations removed alongside them. */
+    removedPendingOperations: number;
+}
+/**
+ * Removes the named provider — and every resource that references it — from
+ * a deployment body, in place. Returns what was removed so callers can log
+ * it or skip the state write when nothing matched.
+ *
+ * Surviving resources are sanitized as well: any `dependencies`,
+ * `propertyDependencies`, `parent`, or `deletedWith` reference to a purged
+ * resource is dropped, because the engine refuses to import a deployment
+ * that mentions missing resources.
+ *
+ * Provider resources live at URNs whose type segment ends in
+ * `pulumi:providers:<type>` — `parentType$pulumi:providers:<type>` when the
+ * provider is declared inside a component resource — followed by the
+ * resource name. The match is on that type and the name, never on the stack
+ * or project, so the same purge works against any backend layout.
+ */
+export declare function removeProviderFromDeployment(deployment: unknown, providerName: string): ProviderPurge;
+/**
+ * Exports the stack's state, removes the named provider and its dependents,
+ * and imports the filtered state back — only when something actually
+ * matched, so healthy stacks never see a state write.
+ */
+export declare function purgeProviderFromState(stack: automation.Stack, providerName: string): Promise<ProviderPurge>;
+//# sourceMappingURL=state-surgery.d.ts.map

package/dist/state-surgery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-surgery.d.ts","sourceRoot":"","sources":["../src/state-surgery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAsCjD,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa,CA6CrG;AAiCD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAOlH"}

package/dist/state-surgery.js

@@ -0,0 +1,94 @@
+/**
+ * Removes the named provider — and every resource that references it — from
+ * a deployment body, in place. Returns what was removed so callers can log
+ * it or skip the state write when nothing matched.
+ *
+ * Surviving resources are sanitized as well: any `dependencies`,
+ * `propertyDependencies`, `parent`, or `deletedWith` reference to a purged
+ * resource is dropped, because the engine refuses to import a deployment
+ * that mentions missing resources.
+ *
+ * Provider resources live at URNs whose type segment ends in
+ * `pulumi:providers:<type>` — `parentType$pulumi:providers:<type>` when the
+ * provider is declared inside a component resource — followed by the
+ * resource name. The match is on that type and the name, never on the stack
+ * or project, so the same purge works against any backend layout.
+ */
+export function removeProviderFromDeployment(deployment, providerName) {
+    const body = deployment;
+    const providerUrns = new Set((body.resources ?? [])
+        .filter((resource) => isProviderUrn(resource.urn, providerName))
+        .map((resource) => resource.urn));
+    const purge = {
+        providerUrns: [...providerUrns],
+        removedResources: 0,
+        removedPendingOperations: 0,
+    };
+    if (providerUrns.size === 0) {
+        return purge;
+    }
+    const managedByPurgedProvider = (resource) => {
+        if (providerUrns.has(resource.urn)) {
+            return true;
+        }
+        const reference = resource.provider;
+        return reference !== undefined && [...providerUrns].some((urn) => reference.startsWith(`${urn}::`));
+    };
+    const purgedUrns = new Set((body.resources ?? []).filter((resource) => managedByPurgedProvider(resource)).map((resource) => resource.urn));
+    if (body.resources) {
+        const before = body.resources.length;
+        body.resources = body.resources.filter((resource) => !purgedUrns.has(resource.urn));
+        purge.removedResources = before - body.resources.length;
+        for (const survivor of body.resources) {
+            dropReferencesTo(survivor, purgedUrns);
+        }
+    }
+    if (body.pendingOperations) {
+        const before = body.pendingOperations.length;
+        body.pendingOperations = body.pendingOperations.filter((operation) => !purgedUrns.has(operation.resource.urn) && !managedByPurgedProvider(operation.resource));
+        purge.removedPendingOperations = before - body.pendingOperations.length;
+    }
+    return purge;
+}
+/** Removes every reference a surviving resource holds to the purged URNs. */
+function dropReferencesTo(resource, purgedUrns) {
+    if (resource.dependencies) {
+        resource.dependencies = resource.dependencies.filter((urn) => !purgedUrns.has(urn));
+    }
+    if (resource.propertyDependencies) {
+        for (const [property, urns] of Object.entries(resource.propertyDependencies)) {
+            if (urns) {
+                resource.propertyDependencies[property] = urns.filter((urn) => !purgedUrns.has(urn));
+            }
+        }
+    }
+    if (resource.parent !== undefined && purgedUrns.has(resource.parent)) {
+        delete resource.parent;
+    }
+    if (resource.deletedWith !== undefined && purgedUrns.has(resource.deletedWith)) {
+        delete resource.deletedWith;
+    }
+}
+function isProviderUrn(urn, providerName) {
+    const segments = urn.split("::");
+    if (segments[3] !== providerName) {
+        return false;
+    }
+    // The type segment is `$`-joined with the parent's qualified type when the
+    // provider is declared inside a component resource; the provider's own
+    // type is always the last element.
+    return segments[2]?.split("$").pop()?.startsWith("pulumi:providers:") === true;
+}
+/**
+ * Exports the stack's state, removes the named provider and its dependents,
+ * and imports the filtered state back — only when something actually
+ * matched, so healthy stacks never see a state write.
+ */
+export async function purgeProviderFromState(stack, providerName) {
+    const exported = await stack.exportStack();
+    const purge = removeProviderFromDeployment(exported.deployment, providerName);
+    if (purge.removedResources + purge.removedPendingOperations > 0) {
+        await stack.importStack(exported);
+    }
+    return purge;
+}

package/dist/terminal.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Minimal terminal presentation layer for the lifecycle dispatcher. Colors
+ * are applied only when standard output is an interactive terminal and the
+ * `NO_COLOR` convention is respected, so logs captured in files or CI stay
+ * clean. This module is internal to the library on purpose: programs should
+ * not depend on its exact output.
+ */
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare const red: (text: string) => string;
+export declare const green: (text: string) => string;
+export declare const yellow: (text: string) => string;
+export declare const cyan: (text: string) => string;
+/** Whether the Pulumi CLI should be asked for colored output. */
+export declare function colorMode(): "always" | "never";
+/**
+ * Makes a closed pipe end the process quietly, the way Unix tools behave
+ * under `| head`: without this, Node raises a noisy unhandled EPIPE error.
+ * Installed by the command line entry point only — a library consumer's
+ * process is not touched.
+ */
+export declare function exitQuietlyOnClosedPipe(): void;
+/** Opening line of every run: project, stack, and the action about to run. */
+export declare function heading(project: string, stackName: string, action: string): void;
+/** A lifecycle step about to start, e.g. "refreshing and updating the stack". */
+export declare function step(message: string): void;
+/** A successfully completed lifecycle action. */
+export declare function succeed(message: string): void;
+/** A non-fatal problem the run recovered from or chose to ignore. */
+export declare function warn(message: string): void;
+/** A fatal problem, followed by optional remediation lines. */
+export declare function fail(message: string, remediation?: readonly string[]): void;
+/** Secondary detail under a heading or step. */
+export declare function detail(message: string): void;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,eAAO,MAAM,IAAI,SAJmC,MAAM,KAAK,MAI/B,CAAC;AACjC,eAAO,MAAM,GAAG,SALoC,MAAM,KAAK,MAKhC,CAAC;AAChC,eAAO,MAAM,GAAG,SANoC,MAAM,KAAK,MAM/B,CAAC;AACjC,eAAO,MAAM,KAAK,SAPkC,MAAM,KAAK,MAO7B,CAAC;AACnC,eAAO,MAAM,MAAM,SARiC,MAAM,KAAK,MAQ5B,CAAC;AACpC,eAAO,MAAM,IAAI,SATmC,MAAM,KAAK,MAS9B,CAAC;AAElC,iEAAiE;AACjE,wBAAgB,SAAS,IAAI,QAAQ,GAAG,OAAO,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAS9C;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEhF;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,iDAAiD;AACjD,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,qEAAqE;AACrE,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,+DAA+D;AAC/D,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,CAQ/E;AAED,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE5C"}