@serverkgg/bridge 0.1.12 → 0.1.13

package/src/bot/botVariables.test.ts

@@ -17,6 +17,7 @@ import {
 	DEPLOYMENT_ID,
 	GIT_TOKEN,
 	INSTALL_COMMAND,
+	PRE_DEPLOY_COMMAND,
 	REPO_BRANCH,
 	REPO_REF,
 	REPO_URL,
@@ -47,6 +48,7 @@ describe("readBotConfig", () => {
 						[REPO_BRANCH]: "dev",
 						[START_COMMAND]: "node src/bot.js",
 						[INSTALL_COMMAND]: "npm install --legacy-peer-deps",
+						[PRE_DEPLOY_COMMAND]: " npx prisma migrate deploy ",
 						[ROOT_DIRECTORY]: " apps/bot ",
 						[DEPLOYMENT_ID]: "dep_a1b2c3d4",
 						[SNAPSHOT_ID]: "snap_1",
@@ -65,6 +67,7 @@ describe("readBotConfig", () => {
 			branch: "dev",
 			startCommand: "node src/bot.js",
 			installCommand: "npm install --legacy-peer-deps",
+			preDeployCommand: "npx prisma migrate deploy",
 			rootDirectory: "apps/bot",
 			deployment: "dep_a1b2c3d4",
 			snapshot: "snap_1",
@@ -88,6 +91,7 @@ describe("readBotConfig", () => {
 			branch: DEFAULT_REPO_BRANCH,
 			startCommand: null,
 			installCommand: null,
+			preDeployCommand: null,
 			rootDirectory: null,
 			deployment: null,
 			snapshot: null,
@@ -96,6 +100,24 @@ describe("readBotConfig", () => {
 		});
 	});
 
+	it("reads no pre-deploy command from a server an older platform configured without the key", () => {
+		expect(
+			readBotConfig(
+				contextWith({
+					[START_COMMAND]: "node .",
+					[INSTALL_COMMAND]: "npm ci",
+				}),
+			).preDeployCommand,
+		).toBeNull();
+		expect(
+			readBotConfig(
+				contextWith({
+					[PRE_DEPLOY_COMMAND]: "   ",
+				}),
+			).preDeployCommand,
+		).toBeNull();
+	});
+
 	it("drops a web address that is not a bare https host", () => {
 		for (const value of [
 			"http://my-bot.srvk.gg",

package/src/bot/botVariables.ts

@@ -6,6 +6,7 @@ import {
 	GIT_TOKEN,
 	INSTALL_COMMAND,
 	isBotPlatform,
+	PRE_DEPLOY_COMMAND,
 	REPO_BRANCH,
 	REPO_REF,
 	REPO_URL,
@@ -46,6 +47,7 @@ export interface BotConfig {
 	branch: string;
 	startCommand: string | null;
 	installCommand: string | null;
+	preDeployCommand: string | null;
 	rootDirectory: string | null;
 	deployment: string | null;
 	snapshot: string | null;
@@ -73,6 +75,7 @@ export const readBotConfig = (context: Pick<BridgeContext, "variable" | "secret"
 		branch: present(context.variable(REPO_BRANCH)) ?? DEFAULT_REPO_BRANCH,
 		startCommand: present(context.variable(START_COMMAND)),
 		installCommand: present(context.variable(INSTALL_COMMAND)),
+		preDeployCommand: present(context.variable(PRE_DEPLOY_COMMAND)),
 		rootDirectory: present(context.variable(ROOT_DIRECTORY)),
 		deployment: present(context.variable(DEPLOYMENT_ID)),
 		snapshot: present(context.variable(SNAPSHOT_ID)),

package/src/bot/detect/detect.test.ts

@@ -79,6 +79,7 @@ describe("detect on the templates", () => {
 				source: "package-lock.json",
 			},
 			build: null,
+			preDeploy: null,
 			start: {
 				command: "node index.js",
 				source: "package.json",
@@ -110,6 +111,7 @@ describe("detect on the templates", () => {
 				source: "requirements.txt",
 			},
 			build: null,
+			preDeploy: null,
 			start: {
 				command: "python main.py",
 				source: "main.py",
@@ -1045,6 +1047,176 @@ describe("detect with serverk.json", () => {
 	});
 });
 
+describe("detect pre-deploy commands", () => {
+	const PRISMA_NODE = {
+		...DISCORD_NODE,
+		"package.json": JSON.stringify({
+			name: "discord-bot",
+			main: "index.js",
+			scripts: {
+				start: "node index.js",
+				migrate: "prisma migrate deploy",
+			},
+			dependencies: {
+				"discord.js": "^14.27.0",
+				"@prisma/client": "^6.0.0",
+			},
+			devDependencies: {
+				prisma: "^6.0.0",
+			},
+		}),
+	};
+
+	it("migrates a Prisma project that ships its migrations", () => {
+		expect(
+			project(PRISMA_NODE, [
+				"package-lock.json",
+				"prisma/schema.prisma",
+				"prisma/migrations/migration_lock.toml",
+				"prisma/migrations/20260101000000_init/migration.sql",
+			]).preDeploy,
+		).toEqual({
+			command: "prisma migrate deploy",
+			source: "prisma/migrations/migration_lock.toml",
+		});
+	});
+
+	it("runs nothing for a Prisma project with no migrations folder, the db push workflow", () => {
+		expect(
+			project(PRISMA_NODE, [
+				"package-lock.json",
+				"prisma/schema.prisma",
+			]).preDeploy,
+		).toBeNull();
+	});
+
+	it("never reads a migrate script in package.json as a pre-deploy command", () => {
+		expect(
+			project(
+				{
+					...DISCORD_NODE,
+					"package.json": JSON.stringify({
+						main: "index.js",
+						scripts: {
+							start: "node index.js",
+							migrate: "knex migrate:latest",
+						},
+						dependencies: {
+							"discord.js": "^14.27.0",
+							knex: "^3.1.0",
+						},
+					}),
+				},
+				[
+					"package-lock.json",
+					"knexfile.js",
+					"migrations/20260101_init.js",
+					"drizzle.config.ts",
+				],
+			).preDeploy,
+		).toBeNull();
+	});
+
+	it("upgrades an Alembic project to its head", () => {
+		expect(
+			project(TELEGRAM_PYTHON, [
+				"alembic.ini",
+				"alembic/env.py",
+			]).preDeploy,
+		).toEqual({
+			command: "alembic upgrade head",
+			source: "alembic.ini",
+		});
+	});
+
+	it("migrates a Django project without asking", () => {
+		expect(
+			project(TELEGRAM_PYTHON, [
+				"manage.py",
+			]).preDeploy,
+		).toEqual({
+			command: "python manage.py migrate --noinput",
+			source: "manage.py",
+		});
+	});
+
+	it("prefers Alembic when a project ships both alembic.ini and manage.py", () => {
+		expect(
+			project(TELEGRAM_PYTHON, [
+				"manage.py",
+				"alembic.ini",
+			]).preDeploy,
+		).toEqual({
+			command: "alembic upgrade head",
+			source: "alembic.ini",
+		});
+	});
+
+	it("reads each rule only for its own runtime", () => {
+		expect(
+			project(DISCORD_NODE, [
+				"package-lock.json",
+				"alembic.ini",
+				"manage.py",
+			]).preDeploy,
+		).toBeNull();
+		expect(
+			project(TELEGRAM_PYTHON, [
+				"prisma/migrations/migration_lock.toml",
+			]).preDeploy,
+		).toBeNull();
+	});
+
+	it("runs nothing for a bot with no migration tool", () => {
+		expect(project(DISCORD_NODE).preDeploy).toBeNull();
+		expect(project(TELEGRAM_PYTHON).preDeploy).toBeNull();
+	});
+
+	it("lets serverk.json name the pre-deploy command over the detected one", () => {
+		expect(
+			project(
+				{
+					...TELEGRAM_PYTHON,
+					"serverk.json": JSON.stringify({
+						preDeploy: "python -m bot.migrate",
+					}),
+				},
+				[
+					"alembic.ini",
+				],
+			).preDeploy,
+		).toEqual({
+			command: "python -m bot.migrate",
+			source: "serverk.json",
+		});
+	});
+
+	it("falls back to the detected command when serverk.json names none or is broken", () => {
+		for (const text of [
+			JSON.stringify({
+				start: "python main.py",
+			}),
+			'{"preDeploy": ""}',
+		]) {
+			expect(
+				project(
+					{
+						...TELEGRAM_PYTHON,
+						"serverk.json": text,
+					},
+					[
+						"manage.py",
+					],
+				).preDeploy,
+				text,
+			).toEqual({
+				command: "python manage.py migrate --noinput",
+				source: "manage.py",
+			});
+		}
+	});
+});
+
 describe("compareCodePoints", () => {
 	it("orders by code point, the way Python sorts strings, whatever the locale", () => {
 		expect(

package/src/bot/detect/detect.ts

@@ -592,6 +592,34 @@ const nodeBuildOf = (packageJson: PackageJson | null, manager: string): Detected
 	};
 };
 
+const preDeployOf = (
+	serverk: ServerkJson | null,
+	runtime: BotRuntime | null,
+	has: (path: string) => boolean,
+): DetectedCommand | null => {
+	if (serverk?.preDeploy) {
+		return {
+			command: serverk.preDeploy,
+			source: SERVERK_JSON,
+		};
+	}
+
+	const rules =
+		runtime === BotRuntime.Node
+			? DETECT_TABLE.node.preDeployCommands
+			: runtime === BotRuntime.Python
+				? DETECT_TABLE.python.preDeployCommands
+				: [];
+	const rule = rules.find((entry) => has(entry.file));
+
+	return rule
+		? {
+				command: rule.command,
+				source: rule.file,
+			}
+		: null;
+};
+
 const versionFromFile = (
 	text: string,
 	spec: DetectVersionFile,
@@ -1117,6 +1145,8 @@ export const detect = (input: DetectInput): DetectResult => {
 		};
 	}
 
+	const preDeploy = preDeployOf(serverk, runtime, has);
+
 	const procfile = procfileCommand(read(DETECT_TABLE.procfile.file));
 	const detectedStart =
 		runtime === BotRuntime.Node
@@ -1198,6 +1228,7 @@ export const detect = (input: DetectInput): DetectResult => {
 		platform,
 		install,
 		build,
+		preDeploy,
 		start,
 		nodeVersion,
 		pythonVersion,

package/src/bot/detect/detectResult.ts

@@ -35,6 +35,7 @@ export interface DetectResult {
 	platform: BotPlatform | null;
 	install: DetectedCommand | null;
 	build: DetectedCommand | null;
+	preDeploy: DetectedCommand | null;
 	start: DetectedCommand | null;
 	nodeVersion: string | null;
 	pythonVersion: string | null;

package/src/bot/detect/detectTable.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import { BotFramework } from "./botFramework";
-import { DETECT_TABLE, renderDetectTable } from "./detectTable";
+import { DETECT_TABLE, DETECT_TABLE_VERSION, renderDetectTable } from "./detectTable";
 import { isEnvKey } from "./envKey";
 import { parseServerkJson } from "./serverkJson";
 
@@ -9,8 +9,31 @@ describe("renderDetectTable", () => {
 		const rendered = renderDetectTable();
 
 		expect(rendered.endsWith("}\n")).toBe(true);
-		expect(rendered).toContain('\t"version": 2,');
+		expect(DETECT_TABLE.version).toBe(DETECT_TABLE_VERSION);
+		expect(rendered).toContain('\t"version": 3,');
 		expect(JSON.parse(rendered)).toEqual(DETECT_TABLE);
+		expect(renderDetectTable()).toBe(rendered);
+	});
+
+	it("renders the pre-deploy rules in order, each with the file that triggers it and its command", () => {
+		const rendered = JSON.parse(renderDetectTable());
+
+		expect(rendered.node.preDeployCommands).toEqual([
+			{
+				file: "prisma/migrations/migration_lock.toml",
+				command: "prisma migrate deploy",
+			},
+		]);
+		expect(rendered.python.preDeployCommands).toEqual([
+			{
+				file: "alembic.ini",
+				command: "alembic upgrade head",
+			},
+			{
+				file: "manage.py",
+				command: "python manage.py migrate --noinput",
+			},
+		]);
 	});
 
 	it("names a locked and an unlocked install and a run command for every Node manager", () => {

package/src/bot/detect/detectTable.ts

@@ -9,7 +9,7 @@ import {
 	SERVERK_JSON_EXAMPLE_LENGTH_LIMIT,
 } from "./serverkJson";
 
-export const DETECT_TABLE_VERSION = 2;
+export const DETECT_TABLE_VERSION = 3;
 
 export const DETECT_TABLE_FILE = "image/detect.json";
 
@@ -25,6 +25,11 @@ export interface DetectVersionFile {
 	key?: string;
 }
 
+export interface DetectPreDeployCommand {
+	file: string;
+	command: string;
+}
+
 export interface DetectProcfile {
 	file: string;
 	line: string;
@@ -56,6 +61,7 @@ export interface NodeDetectTable {
 		unlocked: Record<string, string[]>;
 	};
 	runCommands: Record<string, string[]>;
+	preDeployCommands: readonly DetectPreDeployCommand[];
 	versionFiles: DetectVersionFile[];
 	defaultVersion: string;
 }
@@ -65,6 +71,7 @@ export interface PythonDetectTable {
 	manifests: DetectLockfile[];
 	installCommands: Record<string, string[]>;
 	unhonouredManagers: string[];
+	preDeployCommands: readonly DetectPreDeployCommand[];
 	versionFiles: DetectVersionFile[];
 	defaultVersion: string;
 }
@@ -219,6 +226,12 @@ export const DETECT_TABLE: DetectTable = {
 				"run",
 			],
 		},
+		preDeployCommands: [
+			{
+				file: "prisma/migrations/migration_lock.toml",
+				command: "prisma migrate deploy",
+			},
+		],
 		versionFiles: [
 			{
 				file: ".nvmrc",
@@ -312,6 +325,16 @@ export const DETECT_TABLE: DetectTable = {
 			"poetry",
 			"pdm",
 		],
+		preDeployCommands: [
+			{
+				file: "alembic.ini",
+				command: "alembic upgrade head",
+			},
+			{
+				file: "manage.py",
+				command: "python manage.py migrate --noinput",
+			},
+		],
 		versionFiles: [
 			{
 				file: ".python-version",

package/src/bot/detect/keys.test.ts

@@ -12,8 +12,10 @@ import {
 	BOT_RAW_PORT_KEYS,
 	BOT_WEB,
 	BOT_WEB_PORT_KEY,
+	INSTALL_COMMAND,
 	isReservedBotKey,
 	PORT,
+	PRE_DEPLOY_COMMAND,
 	SERVERK_PORT_1,
 	SERVERK_PORT_2,
 	SERVERK_WEB_HOST,
@@ -44,6 +46,11 @@ describe("isReservedBotKey", () => {
 		}
 	});
 
+	it("reserves the pre-deploy command right after the install command, so a customer cannot set it as a variable", () => {
+		expect(BOT_PLATFORM_KEYS.indexOf(PRE_DEPLOY_COMMAND)).toBe(BOT_PLATFORM_KEYS.indexOf(INSTALL_COMMAND) + 1);
+		expect(isReservedBotKey(PRE_DEPLOY_COMMAND)).toBe(true);
+	});
+
 	it("leaves PORT to the customer, so a bot without the web port keeps its own", () => {
 		expect(isReservedBotKey(PORT)).toBe(false);
 	});

package/src/bot/detect/keys.ts

@@ -10,6 +10,8 @@ export const START_COMMAND = "START_COMMAND";
 
 export const INSTALL_COMMAND = "INSTALL_COMMAND";
 
+export const PRE_DEPLOY_COMMAND = "PRE_DEPLOY_COMMAND";
+
 export const ROOT_DIRECTORY = "ROOT_DIRECTORY";
 
 export const DEPLOYMENT_ID = "DEPLOYMENT_ID";
@@ -67,6 +69,7 @@ export const BOT_PLATFORM_KEYS: readonly string[] = [
 	REPO_BRANCH,
 	START_COMMAND,
 	INSTALL_COMMAND,
+	PRE_DEPLOY_COMMAND,
 	ROOT_DIRECTORY,
 	DEPLOYMENT_ID,
 	SNAPSHOT_ID,

package/src/bot/detect/serverkJson.test.ts

@@ -15,6 +15,7 @@ describe("parseServerkJson", () => {
 					framework: "discord-py",
 					start: " python -m bot ",
 					install: "pip install -r requirements/prod.txt",
+					preDeploy: " alembic upgrade head ",
 					env: [
 						"GUILD_ID",
 						{
@@ -31,6 +32,7 @@ describe("parseServerkJson", () => {
 			start: "python -m bot",
 			install: "pip install -r requirements/prod.txt",
 			build: null,
+			preDeploy: "alembic upgrade head",
 			env: [
 				{
 					key: "GUILD_ID",
@@ -54,10 +56,23 @@ describe("parseServerkJson", () => {
 			start: null,
 			install: null,
 			build: null,
+			preDeploy: null,
 			env: [],
 		});
 	});
 
+	it("reads a file written before the pre-deploy field existed, with no preDeploy", () => {
+		expect(
+			parseServerkJson(
+				JSON.stringify({
+					start: "node index.js",
+					install: "npm ci",
+					build: "npm run build",
+				}),
+			)?.preDeploy,
+		).toBeNull();
+	});
+
 	it("refuses a file with any field it cannot trust", () => {
 		for (const text of [
 			"[]",
@@ -68,6 +83,12 @@ describe("parseServerkJson", () => {
 			'{"start":"a\\nb"}',
 			'{"install":""}',
 			'{"install":["npm","ci"]}',
+			'{"preDeploy":""}',
+			'{"preDeploy":"   "}',
+			'{"preDeploy":"a\\nb"}',
+			'{"preDeploy":["prisma","migrate","deploy"]}',
+			'{"preDeploy":true}',
+			`{"preDeploy":"${"x".repeat(1025)}"}`,
 			`{"start":"${"x".repeat(1025)}"}`,
 			'{"env":["1BAD"]}',
 			'{"env":[{"key":"A","sensitive":"yes"}]}',

package/src/bot/detect/serverkJson.ts

@@ -18,6 +18,7 @@ export interface ServerkJson {
 	start: string | null;
 	install: string | null;
 	build: string | null;
+	preDeploy: string | null;
 	env: ServerkJsonEnv[];
 }
 
@@ -159,9 +160,19 @@ export const parseServerkJson = (text: string): ServerkJson | null => {
 	const start = commandOf(document.start);
 	const install = commandOf(document.install);
 	const build = commandOf(document.build);
+	const preDeploy = commandOf(document.preDeploy);
 	const env = envOf(document.env);
 
-	if (!runtime.ok || !platform.ok || !framework.ok || !start.ok || !install.ok || !build.ok || !env.ok) {
+	if (
+		!runtime.ok
+		|| !platform.ok
+		|| !framework.ok
+		|| !start.ok
+		|| !install.ok
+		|| !build.ok
+		|| !preDeploy.ok
+		|| !env.ok
+	) {
 		return null;
 	}
 
@@ -172,6 +183,7 @@ export const parseServerkJson = (text: string): ServerkJson | null => {
 		start: start.value,
 		install: install.value,
 		build: build.value,
+		preDeploy: preDeploy.value,
 		env: env.value,
 	};
 };

package/src/bot/index.ts

@@ -3,6 +3,7 @@ export * from "./botDeploy";
 export * from "./botEnvironment";
 export * from "./botIdentity";
 export * from "./botPanel";
+export * from "./botRun";
 export * from "./botState";
 export * from "./botTerminal";
 export * from "./botVariables";

package/src/cli/link.ts

@@ -4,7 +4,7 @@ import { parseArgs } from "node:util";
 
 const PACKAGE_NAME = "@serverkgg/bridge";
 
-const DEFAULT_SOURCE = "../serverk/modules/bridge";
+export const LINK_SOURCE = "../serverk/modules/bridge";
 
 const INSTALL_PATH = `node_modules/${PACKAGE_NAME}`;
 
@@ -14,7 +14,7 @@ point ${INSTALL_PATH} at a local bridge checkout without touching package.json o
 does nothing when CI is set or the checkout is absent, so the registry package is used everywhere else.
 
 options:
-  --source <dir>   local bridge checkout (default: ${DEFAULT_SOURCE})
+  --source <dir>   local bridge checkout (default: ${LINK_SOURCE})
   --check          print which bridge is installed, change nothing
   --unlink         drop the link so the next install restores the registry package
   --help           show this help`;
@@ -268,7 +268,7 @@ export const runLink = async (args: string[]) => {
 		options: {
 			source: {
 				type: "string",
-				default: DEFAULT_SOURCE,
+				default: LINK_SOURCE,
 			},
 			check: {
 				type: "boolean",

package/src/cli/main.ts

@@ -4,6 +4,7 @@ import { errorText } from "../runtime/bridgeLog";
 import { runCompile } from "./compile";
 import { runDetectTable } from "./detectTable";
 import { runLink } from "./link";
+import { runReadme } from "./readme";
 import { runRules } from "./rules";
 import { runSchema } from "./schema";
 import { runValidate } from "./validate";
@@ -17,6 +18,7 @@ commands:
   compile        compile the bridge binary for amd64
   link           use a local bridge checkout while developing
   rules          write the conventions for package code into .claude/rules
+  readme         write README.md from serverk.yml
 
 run "serverk-bridge <command> --help" for options`;
 
@@ -60,6 +62,12 @@ try {
 			break;
 		}
 
+		case "readme": {
+			await runReadme(args);
+
+			break;
+		}
+
 		case undefined:
 		case "--help": {
 			console.log(USAGE);