bun-workspaces 1.0.0-alpha.3 → 1.0.0-alpha.30

package/src/project/project.d.ts

@@ -0,0 +1,64 @@
+import type { ScriptCommand, WorkspaceScriptCommandMethod } from "../runScript";
+import type { Workspace } from "../workspaces";
+/** Metadata about a {@link Project}'s script, including the workspaces that have it in their package.json */
+export type WorkspaceScriptMetadata = {
+  name: string;
+  workspaces: Workspace[];
+};
+/** Arguments for {@link Project.createScriptCommand} */
+export type CreateProjectScriptCommandOptions = {
+  /** The workspace to run the script in */
+  workspaceNameOrAlias: string;
+  /** The name of the script to run */
+  scriptName: string;
+  /**
+   * The method to use to run the script.
+   * Either run in the workspace directory or use bun's --filter option.
+   * Defaults to "cd".
+   */
+  method?: WorkspaceScriptCommandMethod;
+  /** The arguments to append to the command */
+  args?: string;
+};
+/** Result of {@link Project.createScriptCommand}. Includes a command string that will run a workspace's script. */
+export type CreateProjectScriptCommandResult = {
+  /** Data including a command string using the `bun`
+   * CLI that will run a workspace's script and the
+   * directory to run it in. */
+  commandDetails: ScriptCommand;
+  /** The name of the script to run */
+  scriptName: string;
+  /** The workspace that the script belongs to */
+  workspace: Workspace;
+};
+/**
+ * A project contains a collection of workspaces and is the core of `bun-workspaces`'s functionality.
+ *
+ * Typically based on a root package.json file's `"workspaces"` field and any matching nested package.json files that are found.
+ */
+export interface Project {
+  /** The name of the project. This is typically the name of the root package.json unless otherwise provided. */
+  name: string;
+  /** The root directory of the project */
+  rootDirectory: string;
+  /** The list of all workspaces in the project */
+  workspaces: Workspace[];
+  /** The means by which the project was created */
+  sourceType: "fileSystem" | "memory";
+  /** Find a workspace by its package.json name */
+  findWorkspaceByName(workspaceName: string): Workspace | null;
+  /** Find a workspace by a workspace alias */
+  findWorkspaceByAlias(alias: string): Workspace | null;
+  /** Find a workspace that matches a workspace's name or an alias if no name matches. */
+  findWorkspaceByNameOrAlias(nameOrAlias: string): Workspace | null;
+  /** Accepts a wildcard pattern for finding a list of workspaces by their name*/
+  findWorkspacesByPattern(workspacePattern: string): Workspace[];
+  /** Get an array of all workspaces that have a given script in their package.json */
+  listWorkspacesWithScript(scriptName: string): Workspace[];
+  /** Get a mapping of all scripts to the workspaces that have them in their package.json */
+  mapScriptsToWorkspaces(): Record<string, WorkspaceScriptMetadata>;
+  /** Create metadata that can be used to run a workspace's script */
+  createScriptCommand(
+    options: CreateProjectScriptCommandOptions,
+  ): CreateProjectScriptCommandResult;
+}

package/src/project/project.mjs

@@ -0,0 +1,6 @@
+// CONCATENATED MODULE: ./src/project/project.ts
+/**
+ * A project contains a collection of workspaces and is the core of `bun-workspaces`'s functionality.
+ *
+ * Typically based on a root package.json file's `"workspaces"` field and any matching nested package.json files that are found.
+ */

package/src/runScript/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./runScript";
+export * from "./runScripts";
+export * from "./scriptCommand";
+export * from "./outputChunk";
+export * from "./parallel";
+export * from "./scriptRuntimeMetadata";
+export * from "./scriptShellOption";

package/src/runScript/index.mjs

@@ -0,0 +1,7 @@
+export * from "./runScript.mjs";
+export * from "./runScripts.mjs";
+export * from "./scriptCommand.mjs";
+export * from "./outputChunk.mjs";
+export * from "./parallel.mjs";
+export * from "./scriptRuntimeMetadata.mjs";
+export * from "./scriptShellOption.mjs"; // CONCATENATED MODULE: ./src/runScript/index.ts

package/src/runScript/outputChunk.d.ts

@@ -0,0 +1,22 @@
+export type OutputStreamName = "stdout" | "stderr";
+export interface DecodeOptions {
+  /** Whether to strip ANSI escape codes */
+  stripAnsi?: boolean;
+}
+/** Output captured from a script subprocess */
+export interface OutputChunk {
+  /** The source of the output, `"stdout"` or `"stderr"` */
+  streamName: OutputStreamName;
+  /** Raw output text. Pass `true` to strip ANSI escape codes. */
+  decode(options?: DecodeOptions): string;
+  /** The raw output content */
+  raw: Uint8Array<ArrayBuffer>;
+  /** @deprecated Use `decode()` instead */
+  text: string;
+  /** @deprecated Use `decode({ stripAnsi: true })` instead */
+  textNoAnsi: string;
+}
+export declare const createOutputChunk: (
+  streamName: OutputStreamName,
+  raw: Uint8Array<ArrayBuffer>,
+) => OutputChunk;

package/src/runScript/outputChunk.mjs

@@ -0,0 +1,30 @@
+import { sanitizeAnsi } from "../internal/core/index.mjs"; // CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: ./src/runScript/outputChunk.ts
+
+class _OutputChunk {
+  streamName;
+  raw;
+  constructor(streamName, raw) {
+    this.streamName = streamName;
+    this.raw = raw;
+  }
+  decode(options) {
+    const { stripAnsi = false } = options ?? {};
+    const text = new TextDecoder().decode(this.raw);
+    return stripAnsi ? sanitizeAnsi(text) : text;
+  }
+  /** @deprecated Use `decode()` instead */ get text() {
+    // TODO remove in future major release
+    return this.decode();
+  }
+  /** @deprecated Use `decode({ stripAnsi: true })` instead */ get textNoAnsi() {
+    // TODO remove in future major release
+    return this.decode({
+      stripAnsi: true,
+    });
+  }
+}
+const createOutputChunk = (streamName, raw) =>
+  new _OutputChunk(streamName, raw);
+
+export { createOutputChunk };

package/src/runScript/parallel.d.ts

@@ -0,0 +1,12 @@
+export type PercentageValue = `${number}%`;
+export type ParallelMaxValue =
+  | number
+  | "auto"
+  | "default"
+  | "unbounded"
+  | PercentageValue;
+/** Should always return at least 1 */
+export declare const determineParallelMax: (
+  value: ParallelMaxValue,
+  fromEnvVar?: boolean,
+) => number;

package/src/runScript/parallel.mjs

@@ -0,0 +1,52 @@
+import { availableParallelism } from "node:os";
+import { getUserEnvVar, getUserEnvVarName } from "../config/userEnvVars.mjs";
+import { BunWorkspacesError } from "../internal/core/index.mjs"; // CONCATENATED MODULE: external "node:os"
+// CONCATENATED MODULE: external "../config/userEnvVars.mjs"
+// CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: ./src/runScript/parallel.ts
+
+/** Should always return at least 1 */ const determineParallelMax = (
+  value,
+  fromEnvVar = false,
+) => {
+  const errorMessageSuffix = fromEnvVar
+    ? ` (set by env var ${getUserEnvVarName("parallelMaxDefault")})`
+    : "";
+  if (!isNaN(Number(value))) {
+    value = Math.floor(Number(value));
+  }
+  if (typeof value === "number") {
+    if (value < 1 || isNaN(value)) {
+      throw new BunWorkspacesError(
+        `Parallel max value must be at least 1${errorMessageSuffix}`,
+      );
+    }
+    return Math.floor(value);
+  }
+  if (value === "default") {
+    const defaultMax = getUserEnvVar("parallelMaxDefault")?.trim();
+    if (defaultMax === "default") return determineParallelMax("auto");
+    return determineParallelMax(defaultMax ?? "auto", true);
+  }
+  if (value === "unbounded") {
+    return Infinity;
+  }
+  const cpuCount = Math.max(1, availableParallelism());
+  if (value === "auto") {
+    return cpuCount;
+  }
+  if (value.endsWith("%")) {
+    const percentage = parseFloat(value.slice(0, -1));
+    if (isNaN(percentage) || percentage <= 0 || percentage > 100) {
+      throw new BunWorkspacesError(
+        `Parallel max value must be a number greater than 0 and less than or equal to 100${errorMessageSuffix}`,
+      );
+    }
+    return Math.max(1, Math.floor((cpuCount * percentage) / 100));
+  }
+  throw new BunWorkspacesError(
+    `Invalid parallel max value: ${JSON.stringify(value)}${errorMessageSuffix}`,
+  );
+};
+
+export { determineParallelMax };

package/src/runScript/runScript.d.ts

@@ -0,0 +1,37 @@
+import { type SimpleAsyncIterable } from "../internal/core";
+import { type OutputChunk } from "./outputChunk";
+import type { ScriptCommand } from "./scriptCommand";
+import type { ScriptShellOption } from "./scriptShellOption";
+export type RunScriptExit<ScriptMetadata extends object = object> = {
+  exitCode: number;
+  signal: NodeJS.Signals | null;
+  success: boolean;
+  startTimeISO: string;
+  endTimeISO: string;
+  durationMs: number;
+  metadata: ScriptMetadata;
+};
+export type RunScriptResult<ScriptMetadata extends object = object> = {
+  output: SimpleAsyncIterable<OutputChunk>;
+  exit: Promise<RunScriptExit<ScriptMetadata>>;
+  metadata: ScriptMetadata;
+  kill: (exit?: number | NodeJS.Signals) => void;
+};
+export type RunScriptOptions<ScriptMetadata extends object = object> = {
+  scriptCommand: ScriptCommand;
+  metadata: ScriptMetadata;
+  env: Record<string, string>;
+  /** The shell to use to run the script. Defaults to "system". */
+  shell?: ScriptShellOption;
+};
+/**
+ * Run some script and get an async output stream of
+ * stdout and stderr chunks and a result object
+ * containing exit details.
+ */
+export declare const runScript: <ScriptMetadata extends object = object>({
+  scriptCommand,
+  metadata,
+  env,
+  shell,
+}: RunScriptOptions<ScriptMetadata>) => RunScriptResult<ScriptMetadata>;

package/src/runScript/runScript.mjs

@@ -0,0 +1,60 @@
+import { mergeAsyncIterables } from "../internal/core/index.mjs";
+import { createOutputChunk } from "./outputChunk.mjs";
+import { createScriptExecutor } from "./scriptExecution.mjs"; // CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: external "./outputChunk.mjs"
+// CONCATENATED MODULE: external "./scriptExecution.mjs"
+// CONCATENATED MODULE: ./src/runScript/runScript.ts
+
+/**
+ * Run some script and get an async output stream of
+ * stdout and stderr chunks and a result object
+ * containing exit details.
+ */ const runScript = ({ scriptCommand, metadata, env, shell = "system" }) => {
+  const startTime = new Date();
+  const { argv, cleanup } = createScriptExecutor(scriptCommand.command, shell);
+  const proc = Bun.spawn(argv, {
+    cwd: scriptCommand.workingDirectory || process.cwd(),
+    env: {
+      ...process.env,
+      ...env,
+      _BW_SCRIPT_SHELL_OPTION: shell,
+      FORCE_COLOR: "1",
+    },
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+  proc.exited.finally(cleanup);
+  async function* pipeOutput(streamName) {
+    const stream = proc[streamName];
+    if (stream) {
+      for await (const chunk of stream) {
+        yield createOutputChunk(streamName, chunk);
+      }
+    }
+  }
+  const output = mergeAsyncIterables([
+    pipeOutput("stdout"),
+    pipeOutput("stderr"),
+  ]);
+  const exit = proc.exited.then((exitCode) => {
+    const endTime = new Date();
+    return {
+      exitCode,
+      signal: proc.signalCode,
+      success: exitCode === 0,
+      startTimeISO: startTime.toISOString(),
+      endTimeISO: endTime.toISOString(),
+      durationMs: endTime.getTime() - startTime.getTime(),
+      metadata,
+    };
+  });
+  return {
+    output,
+    exit,
+    metadata,
+    kill: (exit) => proc.kill(exit),
+  };
+};
+
+export { runScript };

package/src/runScript/runScripts.d.ts

@@ -0,0 +1,48 @@
+import { type SimpleAsyncIterable } from "../internal/core";
+import type { OutputChunk } from "./outputChunk";
+import { type ParallelMaxValue } from "./parallel";
+import { type RunScriptExit, type RunScriptResult } from "./runScript";
+import { type ScriptCommand } from "./scriptCommand";
+export type RunScriptsScript<ScriptMetadata extends object = object> = {
+  scriptCommand: ScriptCommand;
+  metadata: ScriptMetadata;
+  env: Record<string, string>;
+};
+export type RunScriptsScriptResult<ScriptMetadata extends object = object> = {
+  /** The result of running the script */
+  result: RunScriptResult<ScriptMetadata>;
+};
+export type RunScriptsSummary<ScriptMetadata extends object = object> = {
+  totalCount: number;
+  successCount: number;
+  failureCount: number;
+  allSuccess: boolean;
+  startTimeISO: string;
+  endTimeISO: string;
+  durationMs: number;
+  scriptResults: RunScriptExit<ScriptMetadata>[];
+};
+export type RunScriptsOutput<ScriptMetadata extends object = object> = {
+  /** The output chunk from a script execution */
+  outputChunk: OutputChunk;
+  /** The metadata for the script that produced the output chunk */
+  scriptMetadata: ScriptMetadata;
+};
+export type RunScriptsResult<ScriptMetadata extends object = object> = {
+  /** Allows async iteration of output chunks from all script executions */
+  output: SimpleAsyncIterable<RunScriptsOutput<ScriptMetadata>>;
+  /** Resolves with a results summary after all scripts have exited */
+  summary: Promise<RunScriptsSummary<ScriptMetadata>>;
+};
+export type RunScriptsParallelOptions = {
+  max: ParallelMaxValue;
+};
+export type RunScriptsOptions<ScriptMetadata extends object = object> = {
+  scripts: RunScriptsScript<ScriptMetadata>[];
+  parallel: boolean | RunScriptsParallelOptions;
+};
+/** Run a list of scripts */
+export declare const runScripts: <ScriptMetadata extends object = object>({
+  scripts,
+  parallel,
+}: RunScriptsOptions<ScriptMetadata>) => RunScriptsResult<ScriptMetadata>;

package/src/runScript/runScripts.mjs

@@ -0,0 +1,124 @@
+import { createAsyncIterableQueue } from "../internal/core/index.mjs";
+import { logger } from "../internal/logger/index.mjs";
+import { determineParallelMax } from "./parallel.mjs";
+import { runScript } from "./runScript.mjs"; // CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: external "../internal/logger/index.mjs"
+// CONCATENATED MODULE: external "./parallel.mjs"
+// CONCATENATED MODULE: external "./runScript.mjs"
+// CONCATENATED MODULE: ./src/runScript/runScripts.ts
+
+/** Run a list of scripts */ const runScripts = ({ scripts, parallel }) => {
+  const startTime = new Date();
+  const scriptTriggers = scripts.map((_, index) => {
+    let trigger = () => {
+      void 0;
+    };
+    const promise = new Promise((res) => {
+      trigger = () => res(result);
+    });
+    const result = {
+      promise,
+      trigger,
+      index,
+    };
+    return result;
+  });
+  const outputQueue = createAsyncIterableQueue();
+  const scriptResults = scripts.map(() => null);
+  const parallelMax =
+    parallel === false
+      ? 1
+      : determineParallelMax(
+          typeof parallel === "boolean" ? "default" : parallel.max,
+        );
+  const parallelBatchSize = Math.min(parallelMax, scripts.length);
+  const recommendedParallelMax = determineParallelMax("auto");
+  if (
+    parallel &&
+    parallelBatchSize > recommendedParallelMax &&
+    process.env._BW_IS_INTERNAL_TEST !== "true"
+  ) {
+    logger.warn(
+      `Number of scripts to run in parallel (${parallelBatchSize}) is greater than the available CPUs (${recommendedParallelMax})`,
+    );
+  }
+  let runningScriptCount = 0;
+  let nextScriptIndex = 0;
+  const queueScript = (index) => {
+    if (runningScriptCount >= parallelMax) {
+      return;
+    }
+    const scriptResult = {
+      ...scripts[index],
+      result: runScript({
+        ...scripts[index],
+        env: {
+          ...scripts[index].env,
+          _BW_PARALLEL_MAX: parallelMax.toString(),
+        },
+      }),
+    };
+    scriptResults[index] = scriptResult;
+    scriptTriggers[index].trigger();
+    runningScriptCount++;
+    nextScriptIndex++;
+    scriptResults[index].result.exit.then(() => {
+      runningScriptCount--;
+      if (nextScriptIndex < scripts.length) {
+        queueScript(nextScriptIndex);
+      }
+    });
+    return scriptResult;
+  };
+  const handleScriptProcesses = async () => {
+    const outputReaders = [];
+    const scriptExits = [];
+    let pendingScriptCount = scripts.length;
+    while (pendingScriptCount > 0) {
+      const { index } = await Promise.race(
+        scriptTriggers.map((trigger) => trigger.promise),
+      );
+      pendingScriptCount--;
+      scriptTriggers[index].promise = new Promise(() => {
+        void 0;
+      });
+      outputReaders.push(
+        (async () => {
+          for await (const chunk of scriptResults[index].result.output) {
+            outputQueue.push({
+              outputChunk: chunk,
+              scriptMetadata: scripts[index].metadata,
+            });
+          }
+        })(),
+      );
+    }
+    await Promise.all(outputReaders);
+    await Promise.all(scriptExits);
+    outputQueue.close();
+  };
+  const awaitSummary = async () => {
+    scripts.forEach((_, index) => queueScript(index));
+    await handleScriptProcesses();
+    const scriptExitResults = await Promise.all(
+      scripts.map((_, index) => scriptResults[index].result.exit),
+    );
+    const endTime = new Date();
+    return {
+      totalCount: scriptExitResults.length,
+      successCount: scriptExitResults.filter((exit) => exit.success).length,
+      failureCount: scriptExitResults.filter((exit) => !exit.success).length,
+      allSuccess: scriptExitResults.every((exit) => exit.success),
+      startTimeISO: startTime.toISOString(),
+      endTimeISO: endTime.toISOString(),
+      durationMs: endTime.getTime() - startTime.getTime(),
+      scriptResults: scriptExitResults,
+    };
+  };
+  return {
+    output: outputQueue,
+    summary: awaitSummary(),
+  };
+};
+
+export { runScripts };

package/src/runScript/scriptCommand.d.ts

@@ -0,0 +1,33 @@
+import type { Workspace } from "../workspaces";
+export declare const WORKSPACE_SCRIPT_COMMAND_METHODS: readonly [
+  "cd",
+  "filter",
+];
+export type WorkspaceScriptCommandMethod =
+  (typeof WORKSPACE_SCRIPT_COMMAND_METHODS)[number];
+/** Basic metadata to run a script, the command string and the directory to run it in */
+export interface ScriptCommand {
+  /** The command string to run */
+  command: string;
+  /** The directory to run the command in */
+  workingDirectory: string;
+}
+export interface CreateWorkspaceScriptCommandOptions {
+  /**
+   * The method to use to run the script.
+   * Either run in the workspace directory or use bun's --filter option.
+   * Defaults to "cd".
+   */
+  method?: WorkspaceScriptCommandMethod;
+  /** The name of the script to run */
+  scriptName: string;
+  /** The arguments to append to the command */
+  args: string;
+  /** The workspace that the script belongs to */
+  workspace: Workspace;
+  /** The root directory of the project */
+  rootDirectory: string;
+}
+export declare const createWorkspaceScriptCommand: (
+  options: CreateWorkspaceScriptCommandOptions,
+) => ScriptCommand;

package/src/runScript/scriptCommand.mjs

@@ -0,0 +1,19 @@
+import path from "path"; // CONCATENATED MODULE: external "path"
+// CONCATENATED MODULE: ./src/runScript/scriptCommand.ts
+
+const WORKSPACE_SCRIPT_COMMAND_METHODS = ["cd", "filter"];
+const spaceArgs = (args) => (args ? ` ${args.trim()}` : "");
+const METHODS = {
+  cd: ({ scriptName, workspace, rootDirectory, args }) => ({
+    workingDirectory: path.resolve(rootDirectory, workspace.path),
+    command: `bun --silent run ${scriptName}${spaceArgs(args)}`,
+  }),
+  filter: ({ scriptName, workspace, args, rootDirectory }) => ({
+    workingDirectory: rootDirectory,
+    command: `bun --silent run --filter=${JSON.stringify(workspace.name)} ${scriptName}${spaceArgs(args)}`,
+  }),
+};
+const createWorkspaceScriptCommand = (options) =>
+  METHODS[options.method ?? "cd"](options);
+
+export { WORKSPACE_SCRIPT_COMMAND_METHODS, createWorkspaceScriptCommand };

package/src/runScript/scriptExecution.d.ts

@@ -0,0 +1,9 @@
+import { type ScriptShellOption } from "./scriptShellOption";
+export type ScriptExecutor = {
+  argv: string[];
+  cleanup: () => void;
+};
+export declare const createScriptExecutor: (
+  command: string,
+  shell: ScriptShellOption,
+) => ScriptExecutor;

package/src/runScript/scriptExecution.mjs

@@ -0,0 +1,51 @@
+import node_crypto from "node:crypto";
+import { BunWorkspacesError } from "../internal/core/index.mjs";
+import { IS_WINDOWS } from "../internal/runtime/index.mjs";
+import { createTempFile } from "../internal/runtime/tempFile.mjs";
+import { resolveScriptShell } from "./scriptShellOption.mjs"; // CONCATENATED MODULE: external "node:crypto"
+// CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: external "../internal/runtime/index.mjs"
+// CONCATENATED MODULE: external "../internal/runtime/tempFile.mjs"
+// CONCATENATED MODULE: external "./scriptShellOption.mjs"
+// CONCATENATED MODULE: ./src/runScript/scriptExecution.ts
+
+const createWindowsBatchFile = (command) => {
+  const fileName = `${node_crypto.randomUUID()}.cmd`;
+  const fileContent = `@echo off\r\n${command}\r\n`;
+  return createTempFile({
+    fileName,
+    fileContent,
+  });
+};
+const createShellScript = (command) => {
+  const fileName = `${node_crypto.randomUUID()}.sh`;
+  return createTempFile({
+    fileName,
+    fileContent: command,
+    mode: 493,
+  });
+};
+const createScriptExecutor = (command, shell) => {
+  shell = resolveScriptShell(shell);
+  if (shell === "bun") {
+    const { filePath, cleanup } = createShellScript(command);
+    return {
+      argv: ["bun", filePath],
+      cleanup,
+    };
+  }
+  if (shell === "system") {
+    const { filePath, cleanup } = IS_WINDOWS
+      ? createWindowsBatchFile(command)
+      : createShellScript(command);
+    return {
+      argv: IS_WINDOWS
+        ? ["cmd", "/d", "/s", "/c", "call", filePath]
+        : ["sh", "-c", filePath],
+      cleanup,
+    };
+  }
+  throw new BunWorkspacesError(`Invalid shell option: ${shell}`);
+};
+
+export { createScriptExecutor };

package/src/runScript/scriptRuntimeMetadata.d.ts

@@ -0,0 +1,75 @@
+import type { ScriptShellOption } from "./scriptShellOption";
+export interface ScriptRuntimeMetadata {
+  projectPath: string;
+  projectName: string;
+  workspacePath: string;
+  workspaceRelativePath: string;
+  workspaceName: string;
+  scriptName: string;
+}
+declare const SCRIPT_RUNTIME_METADATA_CONFIG: {
+  readonly projectPath: {
+    readonly inlineName: readonly ["<projectPath>"];
+    readonly envVarName: "BW_PROJECT_PATH";
+  };
+  readonly projectName: {
+    readonly inlineName: readonly ["<projectName>"];
+    readonly envVarName: "BW_PROJECT_NAME";
+  };
+  readonly workspacePath: {
+    readonly inlineName: readonly ["<workspacePath>"];
+    readonly envVarName: "BW_WORKSPACE_PATH";
+  };
+  readonly workspaceRelativePath: {
+    readonly inlineName: readonly ["<workspaceRelativePath>"];
+    readonly envVarName: "BW_WORKSPACE_RELATIVE_PATH";
+  };
+  readonly scriptName: {
+    readonly inlineName: readonly ["<scriptName>"];
+    readonly envVarName: "BW_SCRIPT_NAME";
+  };
+  readonly workspaceName: {
+    /** @todo  @deprecated Deprecate <workspace> in favor of <workspaceName> in major release */
+    readonly inlineName: readonly ["<workspaceName>", "<workspace>"];
+    readonly envVarName: "BW_WORKSPACE_NAME";
+  };
+};
+export type ScriptRuntimeMetadataKey =
+  keyof typeof SCRIPT_RUNTIME_METADATA_CONFIG;
+export declare const getScriptRuntimeMetadataConfig: (
+  key: ScriptRuntimeMetadataKey,
+) =>
+  | {
+      readonly inlineName: readonly ["<projectPath>"];
+      readonly envVarName: "BW_PROJECT_PATH";
+    }
+  | {
+      readonly inlineName: readonly ["<projectName>"];
+      readonly envVarName: "BW_PROJECT_NAME";
+    }
+  | {
+      readonly inlineName: readonly ["<workspacePath>"];
+      readonly envVarName: "BW_WORKSPACE_PATH";
+    }
+  | {
+      readonly inlineName: readonly ["<workspaceRelativePath>"];
+      readonly envVarName: "BW_WORKSPACE_RELATIVE_PATH";
+    }
+  | {
+      readonly inlineName: readonly ["<scriptName>"];
+      readonly envVarName: "BW_SCRIPT_NAME";
+    }
+  | {
+      /** @todo  @deprecated Deprecate <workspace> in favor of <workspaceName> in major release */
+      readonly inlineName: readonly ["<workspaceName>", "<workspace>"];
+      readonly envVarName: "BW_WORKSPACE_NAME";
+    };
+export declare const createScriptRuntimeEnvVars: (
+  metadata: ScriptRuntimeMetadata,
+) => Record<string, string>;
+export declare const interpolateScriptRuntimeMetadata: (
+  text: string,
+  metadata: ScriptRuntimeMetadata,
+  shell: ScriptShellOption,
+) => string;
+export {};