@serverkgg/bridge 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.11",
+	"version": "0.1.13",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/rules/package.md

@@ -7,6 +7,7 @@ Generated by `serverk-bridge rules` from the pinned `@serverkgg/bridge`. Do not
 One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pipeline: validated with `serverk-bridge validate`, released only from `../serverk`, the monorepo beside it.
 
 - When `../serverk` exists, read `../serverk/CLAUDE.md` first; its instructions apply here.
+- `README.md` is generated by `serverk-bridge readme` from `serverk.yml`, `package.json` and `.githooks/pre-commit`, and never edited by hand; `serverk-bridge validate` fails while it is out of date.
 - Before matching work, read its skill in `../serverk/.claude/skills/`: `serverk-copy` (every string a customer reads), `serverk-game-package` (a new game, its manifest, image or control channel), `serverk-game-art` (logo and banner), `serverk-deploy` (publishing to dev in `dev.md`, releasing in `bridge.md`).
 
 ## The driver
@@ -26,7 +27,7 @@ One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pi
 
 - Functions are `const` arrows. No classes, `function` declarations, default exports or comments.
 - Touch the server only through `Bridge.Context` (`files`, `exec`, `net`, `codec`, `rcon`, `variable`, `secret`), never `node:fs`, `fetch`, `Bun.spawn` or `process.env`.
-- Log through `context.log`: a lowercase message, details second. Never `console` in `src/`.
+- Log through `context.log`: a lowercase message, details second. `context.print` writes a raw console line, redacted, for output the console shows as the process's own, such as a console command's. Never `console` in `src/`.
 - Refuse a customer's request with `new BridgeUserError({ ar, en })`; a plain lowercase English `Error` is for faults the customer cannot fix.
 - A timeout, limit, pattern or file name is a `SCREAMING_SNAKE_CASE` constant (`STOP_TIMEOUT_SECONDS`), exported when a test or another folder needs it.
 

package/src/bot/botDeploy.test.ts

@@ -10,6 +10,7 @@ import {
 	DEPLOYMENT_LINE,
 	DEPLOYMENT_STAGE_LINE,
 	type DeployMarker,
+	deploymentFailedEvent,
 	deploymentLine,
 	deploymentStageLine,
 	deployPending,
@@ -191,6 +192,52 @@ describe("deploymentLine", () => {
 		});
 	});
 
+	it("reads a failure at the pre-deploy stage, hyphen included", () => {
+		const line = deploymentLine({
+			deployment: "dep_a1b2c3d4",
+			outcome: BotDeploymentOutcome.Failed,
+			stage: BotDeploymentStage.PreDeploy,
+			detail: "prisma migrate deploy exited with code 1",
+		});
+
+		expect(line).toBe("serverk: deployment dep_a1b2c3d4 failed: pre-deploy: prisma migrate deploy exited with code 1");
+		expect(DEPLOYMENT_LINE.exec(line)?.groups).toMatchObject({
+			deployment: "dep_a1b2c3d4",
+			outcome: "failed",
+			stage: "pre-deploy",
+			detail: "prisma migrate deploy exited with code 1",
+		});
+		expect(DEPLOYMENT_EVENT_PATTERN.match.test(line)).toBe(true);
+		expect(
+			deploymentFailedEvent("dep_a1b2c3d4", BotDeploymentStage.PreDeploy, "prisma migrate deploy exited with code 1"),
+		).toEqual({
+			kind: "deployment",
+			deployment: "dep_a1b2c3d4",
+			outcome: BotDeploymentOutcome.Failed,
+			stage: "pre-deploy",
+			detail: "prisma migrate deploy exited with code 1",
+		});
+	});
+
+	it("round-trips a failure through the line pattern for every stage", () => {
+		for (const stage of Object.values(BotDeploymentStage)) {
+			expect(
+				DEPLOYMENT_LINE.exec(
+					deploymentLine({
+						deployment: "dep_a1b2c3d4",
+						outcome: BotDeploymentOutcome.Failed,
+						stage,
+						detail: "it broke",
+					}),
+				)?.groups,
+				stage,
+			).toMatchObject({
+				stage,
+				detail: "it broke",
+			});
+		}
+	});
+
 	it("cuts the detail at 200 characters, counting an emoji as one the way the Python launcher does", () => {
 		const line = deploymentLine({
 			deployment: "dep_a1b2c3d4",
@@ -225,6 +272,16 @@ describe("deploymentStageLine", () => {
 		);
 	});
 
+	it("names the pre-deploy stage with its hyphen", () => {
+		const line = deploymentStageLine("dep_a1b2c3d4", BotDeploymentStage.PreDeploy);
+
+		expect(line).toBe("serverk: deployment dep_a1b2c3d4 stage pre-deploy");
+		expect(DEPLOYMENT_STAGE_LINE.exec(line)?.groups).toEqual({
+			deployment: "dep_a1b2c3d4",
+			stage: "pre-deploy",
+		});
+	});
+
 	it("round-trips through the stage pattern for every stage", () => {
 		for (const stage of Object.values(BotDeploymentStage)) {
 			expect(DEPLOYMENT_STAGE_LINE.exec(deploymentStageLine("dep_a1b2c3d4", stage))?.groups).toEqual({

package/src/bot/botEnvironment.test.ts

@@ -9,10 +9,12 @@ import {
 	LAUNCHER_GIT_TOKEN,
 	LAUNCHER_INSTALL_COMMAND,
 	LAUNCHER_KEYS,
+	LAUNCHER_PRE_DEPLOY_COMMAND,
 	LAUNCHER_REPO_BRANCH,
 	LAUNCHER_REPO_REF,
 	LAUNCHER_REPO_URL,
 	LAUNCHER_ROOT_DIRECTORY,
+	LAUNCHER_RUN_COMMAND,
 	LAUNCHER_SNAPSHOT_ID,
 	LAUNCHER_START_COMMAND,
 	LAUNCHER_STATE_DIR,
@@ -25,6 +27,7 @@ import {
 	BOT_PORT_2_KEY,
 	BOT_WEB_PORT_KEY,
 	BotPlatform,
+	isReservedBotKey,
 	PORT,
 	SERVERK_PORT_1,
 	SERVERK_PORT_2,
@@ -41,6 +44,7 @@ const config = (overrides: Partial<BotConfig> = {}): BotConfig => ({
 	branch: DEFAULT_REPO_BRANCH,
 	startCommand: null,
 	installCommand: null,
+	preDeployCommand: null,
 	rootDirectory: null,
 	deployment: null,
 	snapshot: null,
@@ -84,6 +88,7 @@ describe("customerEnvironment", () => {
 					REPO_REF: SHA,
 					START_COMMAND: "node .",
 					INSTALL_COMMAND: "npm i",
+					PRE_DEPLOY_COMMAND: "npx prisma migrate deploy",
 					DEPLOYMENT_ID: "dep_1",
 					SNAPSHOT_ID: "snap_1",
 					BOT_PLATFORM: "discord",
@@ -122,6 +127,18 @@ describe("customerEnvironment", () => {
 			API_KEY: "sealed",
 		});
 	});
+
+	it("reserves the console command key so a customer variable never reaches the launcher as one", () => {
+		expect(isReservedBotKey(LAUNCHER_RUN_COMMAND)).toBe(true);
+		expect(
+			customerEnvironment(
+				{
+					[LAUNCHER_RUN_COMMAND]: "rm -rf .",
+				},
+				{},
+			),
+		).toEqual({});
+	});
 });
 
 describe("launcherEnvironment", () => {
@@ -135,6 +152,7 @@ describe("launcherEnvironment", () => {
 					gitToken: "ghs_installation",
 					startCommand: "node .",
 					installCommand: "npm install --legacy-peer-deps",
+					preDeployCommand: "npx prisma migrate deploy",
 					rootDirectory: "apps/bot",
 					deployment: "dep_a1b2c3d4",
 				}),
@@ -148,6 +166,7 @@ describe("launcherEnvironment", () => {
 			[LAUNCHER_GIT_TOKEN]: "ghs_installation",
 			[LAUNCHER_START_COMMAND]: "node .",
 			[LAUNCHER_INSTALL_COMMAND]: "npm install --legacy-peer-deps",
+			[LAUNCHER_PRE_DEPLOY_COMMAND]: "npx prisma migrate deploy",
 			[LAUNCHER_ROOT_DIRECTORY]: "apps/bot",
 			[LAUNCHER_DEPLOYMENT_ID]: "dep_a1b2c3d4",
 		});
@@ -173,7 +192,9 @@ describe("launcherEnvironment", () => {
 		expect(LAUNCHER_KEYS.every((key) => key.startsWith("SERVERK_"))).toBe(true);
 		expect(LAUNCHER_KEYS).toContain(LAUNCHER_REPO_REF);
 		expect(LAUNCHER_KEYS).toContain(LAUNCHER_INSTALL_COMMAND);
+		expect(LAUNCHER_KEYS).toContain(LAUNCHER_PRE_DEPLOY_COMMAND);
 		expect(LAUNCHER_KEYS).toContain(LAUNCHER_ROOT_DIRECTORY);
+		expect(LAUNCHER_KEYS).toContain(LAUNCHER_RUN_COMMAND);
 	});
 });
 

package/src/bot/botEnvironment.ts

@@ -28,6 +28,8 @@ export const LAUNCHER_START_COMMAND = "SERVERK_START_COMMAND";
 
 export const LAUNCHER_INSTALL_COMMAND = "SERVERK_INSTALL_COMMAND";
 
+export const LAUNCHER_PRE_DEPLOY_COMMAND = "SERVERK_PRE_DEPLOY_COMMAND";
+
 export const LAUNCHER_ROOT_DIRECTORY = "SERVERK_ROOT_DIRECTORY";
 
 export const LAUNCHER_DEPLOYMENT_ID = "SERVERK_DEPLOYMENT_ID";
@@ -38,6 +40,8 @@ export const LAUNCHER_STATE_DIR = "SERVERK_STATE_DIR";
 
 export const LAUNCHER_DETECT_TABLE = "SERVERK_DETECT_TABLE";
 
+export const LAUNCHER_RUN_COMMAND = "SERVERK_RUN_COMMAND";
+
 export const LAUNCHER_KEYS: readonly string[] = [
 	LAUNCHER_REPO_URL,
 	LAUNCHER_REPO_REF,
@@ -45,11 +49,13 @@ export const LAUNCHER_KEYS: readonly string[] = [
 	LAUNCHER_GIT_TOKEN,
 	LAUNCHER_START_COMMAND,
 	LAUNCHER_INSTALL_COMMAND,
+	LAUNCHER_PRE_DEPLOY_COMMAND,
 	LAUNCHER_ROOT_DIRECTORY,
 	LAUNCHER_DEPLOYMENT_ID,
 	LAUNCHER_SNAPSHOT_ID,
 	LAUNCHER_STATE_DIR,
 	LAUNCHER_DETECT_TABLE,
+	LAUNCHER_RUN_COMMAND,
 ];
 
 export const customerEnvironment = (
@@ -103,6 +109,10 @@ export const launcherEnvironment = (config: BotConfig, stateDir: string): Record
 			LAUNCHER_INSTALL_COMMAND,
 			config.installCommand,
 		],
+		[
+			LAUNCHER_PRE_DEPLOY_COMMAND,
+			config.preDeployCommand,
+		],
 		[
 			LAUNCHER_ROOT_DIRECTORY,
 			config.rootDirectory,

package/src/bot/botRun.test.ts

@@ -0,0 +1,296 @@
+import { describe, expect, it } from "bun:test";
+import type { BridgeContext, BridgeExecOptions, BridgeExecResult } from "../context";
+import { BridgeStream } from "../core";
+import { LAUNCHER_RUN_COMMAND } from "./botEnvironment";
+import { BOT_RUN_MODE, BOT_RUN_OUTPUT_LIMIT, BOT_RUN_TIMEOUT_MS, botRunEndLineOf, createBotRun } from "./botRun";
+
+const LAUNCHER = [
+	"node",
+	"/opt/serverk/launcher.mjs",
+	BOT_RUN_MODE,
+];
+
+const ENVIRONMENT = {
+	DISCORD_TOKEN: "sealed",
+	SERVERK_STATE_DIR: "/home/container/.serverk",
+};
+
+interface ExecCall {
+	command: string[];
+	options: BridgeExecOptions;
+}
+
+interface PrintedLine {
+	line: string;
+	stream: BridgeStream | null;
+}
+
+const runContextOf = () => {
+	const calls: ExecCall[] = [];
+	const printed: PrintedLine[] = [];
+	const settles: ((outcome: BridgeExecResult | Error) => void)[] = [];
+
+	const context = {
+		exec(command: string[], options: BridgeExecOptions = {}) {
+			calls.push({
+				command,
+				options,
+			});
+
+			return new Promise<BridgeExecResult>((resolve, reject) => {
+				settles.push((outcome) => {
+					if (outcome instanceof Error) {
+						reject(outcome);
+
+						return;
+					}
+
+					resolve(outcome);
+				});
+			});
+		},
+		print(line: string, stream?: BridgeStream) {
+			printed.push({
+				line,
+				stream: stream ?? null,
+			});
+		},
+	} as unknown as BridgeContext;
+
+	const settle = async (outcome: BridgeExecResult | Error) => {
+		settles.shift()?.(outcome);
+
+		await Bun.sleep(0);
+	};
+
+	return {
+		context,
+		calls,
+		printed,
+		settle,
+	};
+};
+
+const resultOf = (code: number): BridgeExecResult => ({
+	stdout: "",
+	stderr: "",
+	code,
+});
+
+const runOf = () => {
+	return createBotRun({
+		launcherCommand: () => LAUNCHER,
+		environment: () => ENVIRONMENT,
+	});
+};
+
+describe("createBotRun", () => {
+	it("starts the launcher in run mode and answers at once with the command sent", async () => {
+		const harness = runContextOf();
+
+		const reply = await runOf()(harness.context, "npx prisma migrate deploy");
+
+		expect(reply).toEqual({
+			sent: "npx prisma migrate deploy",
+			line: null,
+			groups: {},
+		});
+		expect(harness.calls.map((call) => call.command)).toEqual([
+			LAUNCHER,
+		]);
+		expect(harness.calls[0]?.options.timeoutMs).toBe(BOT_RUN_TIMEOUT_MS);
+		expect(harness.printed).toEqual([]);
+	});
+
+	it("hands the launcher the bot's environment and exactly the trimmed command", async () => {
+		const harness = runContextOf();
+
+		await runOf()(harness.context, "  ls -la dist  ");
+
+		expect(harness.calls[0]?.options.environment).toEqual({
+			...ENVIRONMENT,
+			[LAUNCHER_RUN_COMMAND]: "ls -la dist",
+		});
+	});
+
+	it("answers a blank input without running anything", async () => {
+		const harness = runContextOf();
+
+		const reply = await runOf()(harness.context, "   ");
+
+		expect(reply).toEqual({
+			sent: "",
+			line: "serverk: nothing to run",
+			groups: {},
+		});
+		expect(harness.calls).toEqual([]);
+	});
+
+	it("refuses a second command while the first one runs", async () => {
+		const harness = runContextOf();
+		const run = runOf();
+
+		await run(harness.context, "sleep 60");
+
+		const reply = await run(harness.context, "ls");
+
+		expect(reply).toEqual({
+			sent: "ls",
+			line: "serverk: a command is already running",
+			groups: {},
+		});
+		expect(harness.calls).toHaveLength(1);
+	});
+
+	it("prints the command's output on its stream, then that it finished, and takes the next command", async () => {
+		const harness = runContextOf();
+		const run = runOf();
+
+		await run(harness.context, "npm run seed");
+
+		const onOutput = harness.calls[0]?.options.onOutput;
+
+		onOutput?.("seeded 3 rows", BridgeStream.Stdout);
+		onOutput?.("warning: no .env", BridgeStream.Stderr);
+
+		await harness.settle(resultOf(0));
+
+		const next = await run(harness.context, "ls");
+
+		expect(harness.printed).toEqual([
+			{
+				line: "seeded 3 rows",
+				stream: BridgeStream.Stdout,
+			},
+			{
+				line: "warning: no .env",
+				stream: BridgeStream.Stderr,
+			},
+			{
+				line: "serverk: command finished",
+				stream: null,
+			},
+		]);
+		expect(next?.line).toBeNull();
+		expect(harness.calls).toHaveLength(2);
+	});
+
+	it("stops printing at the output limit, says so once, and still prints how the command ended", async () => {
+		const harness = runContextOf();
+		const line = "y".repeat(1023);
+		const fitting = BOT_RUN_OUTPUT_LIMIT / (line.length + 1);
+
+		await runOf()(harness.context, "yes");
+
+		const onOutput = harness.calls[0]?.options.onOutput;
+
+		for (let index = 0; index < fitting + 5; index += 1) {
+			onOutput?.(line, BridgeStream.Stdout);
+		}
+
+		await harness.settle(resultOf(0));
+
+		expect(harness.printed.filter((entry) => entry.line === line)).toHaveLength(fitting);
+		expect(harness.printed.slice(fitting)).toEqual([
+			{
+				line: "serverk: output cut at 256 KiB",
+				stream: null,
+			},
+			{
+				line: "serverk: command finished",
+				stream: null,
+			},
+		]);
+	});
+
+	it("reports a failed command with its exit code and frees the console", async () => {
+		const harness = runContextOf();
+		const run = runOf();
+
+		await run(harness.context, "false");
+		await harness.settle(resultOf(2));
+
+		const next = await run(harness.context, "ls");
+
+		expect(harness.printed).toEqual([
+			{
+				line: "serverk: command failed (exit 2)",
+				stream: null,
+			},
+		]);
+		expect(next?.line).toBeNull();
+	});
+
+	it("reports a command the exec refused to start and frees the console", async () => {
+		const harness = runContextOf();
+		const run = runOf();
+
+		await run(harness.context, "ls");
+		await harness.settle(new Error("the exec process runs as uid 0, expected uid 1000 — refusing to run it"));
+
+		const next = await run(harness.context, "ls");
+
+		expect(harness.printed).toEqual([
+			{
+				line: "serverk: command failed: the exec process runs as uid 0, expected uid 1000 — refusing to run it",
+				stream: null,
+			},
+		]);
+		expect(next?.line).toBeNull();
+	});
+
+	it("keeps answering when the launcher environment cannot be built", async () => {
+		const harness = runContextOf();
+		const run = createBotRun({
+			launcherCommand: () => LAUNCHER,
+			environment: () => {
+				throw new Error("no state directory");
+			},
+		});
+
+		const reply = await run(harness.context, "ls");
+
+		await Bun.sleep(0);
+
+		const next = await run(harness.context, "ls");
+
+		expect(reply?.line).toBeNull();
+		expect(harness.calls).toEqual([]);
+		expect(harness.printed.map((entry) => entry.line)).toEqual([
+			"serverk: command failed: no state directory",
+			"serverk: command failed: no state directory",
+		]);
+		expect(next?.line).toBeNull();
+	});
+});
+
+const END_LINES = [
+	{
+		code: 0,
+		elapsedMs: 1200,
+		line: "serverk: command finished",
+	},
+	{
+		code: 1,
+		elapsedMs: 1200,
+		line: "serverk: command failed (exit 1)",
+	},
+	{
+		code: 137,
+		elapsedMs: 4000,
+		line: "serverk: command failed (exit 137)",
+	},
+	{
+		code: 137,
+		elapsedMs: BOT_RUN_TIMEOUT_MS,
+		line: "serverk: command stopped after 10 minutes",
+	},
+];
+
+describe("botRunEndLineOf", () => {
+	for (const item of END_LINES) {
+		it(`ends a command that exited ${item.code} after ${item.elapsedMs} ms with "${item.line}"`, () => {
+			expect(botRunEndLineOf(item.code, item.elapsedMs)).toBe(item.line);
+		});
+	}
+});

package/src/bot/botRun.ts

@@ -0,0 +1,109 @@
+import type { BridgeContext, BridgeReply } from "../context";
+import { LAUNCHER_RUN_COMMAND } from "./botEnvironment";
+
+export const BOT_RUN_MODE = "run";
+
+export const BOT_RUN_TIMEOUT_MS = 600_000;
+
+export const BOT_RUN_OUTPUT_LIMIT = 256 * 1024;
+
+const EMPTY_LINE = "serverk: nothing to run";
+
+const BUSY_LINE = "serverk: a command is already running";
+
+const FINISHED_LINE = "serverk: command finished";
+
+const STOPPED_LINE = "serverk: command stopped after 10 minutes";
+
+const CUT_LINE = "serverk: output cut at 256 KiB";
+
+export interface BotRunOptions {
+	launcherCommand: () => string[];
+	environment: (context: BridgeContext) => Record<string, string>;
+}
+
+export type BotRun = (context: BridgeContext, input: string) => Promise<BridgeReply | null>;
+
+const replyOf = (sent: string, line: string | null): BridgeReply => {
+	return {
+		sent,
+		line,
+		groups: {},
+	};
+};
+
+export const botRunEndLineOf = (code: number, elapsedMs: number): string => {
+	if (code === 0) {
+		return FINISHED_LINE;
+	}
+
+	if (elapsedMs >= BOT_RUN_TIMEOUT_MS) {
+		return STOPPED_LINE;
+	}
+
+	return `serverk: command failed (exit ${code})`;
+};
+
+export const createBotRun = (options: BotRunOptions): BotRun => {
+	let running = false;
+
+	const execute = async (context: BridgeContext, command: string) => {
+		const startedAt = performance.now();
+
+		let printed = 0;
+		let cut = false;
+
+		try {
+			const result = await context.exec(options.launcherCommand(), {
+				timeoutMs: BOT_RUN_TIMEOUT_MS,
+				environment: {
+					...options.environment(context),
+					[LAUNCHER_RUN_COMMAND]: command,
+				},
+				onOutput(line, stream) {
+					if (cut) {
+						return;
+					}
+
+					const size = Buffer.byteLength(line) + 1;
+
+					if (printed + size > BOT_RUN_OUTPUT_LIMIT) {
+						cut = true;
+
+						context.print(CUT_LINE);
+
+						return;
+					}
+
+					printed += size;
+
+					context.print(line, stream);
+				},
+			});
+
+			context.print(botRunEndLineOf(result.code, performance.now() - startedAt));
+		} catch (error) {
+			context.print(`serverk: command failed: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			running = false;
+		}
+	};
+
+	return async (context, input) => {
+		const command = input.trim();
+
+		if (command.length === 0) {
+			return replyOf(command, EMPTY_LINE);
+		}
+
+		if (running) {
+			return replyOf(command, BUSY_LINE);
+		}
+
+		running = true;
+
+		void execute(context, command).catch(() => undefined);
+
+		return replyOf(command, null);
+	};
+};

package/src/bot/botState.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "bun:test";
-import { BotDeploymentOutcome, BotDeploymentSource, DEPLOYMENT_STATE_FILE, readDeploymentState } from "./botState";
+import {
+	BotDeploymentOutcome,
+	BotDeploymentSource,
+	BotDeploymentStage,
+	DEPLOYMENT_STATE_FILE,
+	readDeploymentState,
+} from "./botState";
 
 const filesWith = (content: string | null) => {
 	return {
@@ -29,6 +35,33 @@ describe("readDeploymentState", () => {
 		expect(await readDeploymentState(filesWith(JSON.stringify(state)))).toEqual(state);
 	});
 
+	it("reads a deployment that failed at the pre-deploy stage", async () => {
+		const state = {
+			deployment: "dep_a1b2c3d4",
+			source: BotDeploymentSource.Git,
+			ref: null,
+			commit: "abc1234abc1234abc1234abc1234abc1234abc12",
+			snapshot: null,
+			outcome: BotDeploymentOutcome.Failed,
+			stage: "pre-deploy",
+			detail: "alembic upgrade head exited with code 1",
+			finishedAt: "2026-10-20T10:00:00.000Z",
+		};
+
+		expect((await readDeploymentState(filesWith(JSON.stringify(state))))?.stage).toBe(BotDeploymentStage.PreDeploy);
+	});
+
+	it("runs the pre-deploy stage after the build and before the start", () => {
+		expect(Object.values(BotDeploymentStage)).toEqual([
+			BotDeploymentStage.Sync,
+			BotDeploymentStage.Snapshot,
+			BotDeploymentStage.Install,
+			BotDeploymentStage.Build,
+			BotDeploymentStage.PreDeploy,
+			BotDeploymentStage.Start,
+		]);
+	});
+
 	it("answers null for a missing, broken or foreign file", async () => {
 		expect(await readDeploymentState(filesWith(null))).toBeNull();
 		expect(await readDeploymentState(filesWith("{"))).toBeNull();

package/src/bot/botState.ts

@@ -21,6 +21,7 @@ export enum BotDeploymentStage {
 	Snapshot = "snapshot",
 	Install = "install",
 	Build = "build",
+	PreDeploy = "pre-deploy",
 	Start = "start",
 }