Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Fail fast when frontend deps are missing (#404)

Graham Neubig5ccc8e627ccf
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index 10a92568e1..bc1fb7d84c 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -13,6 +13,9 @@ import {
buildNpmScriptCommand,
buildAgentServerCommand,
formatMissingUvxGuidance,
+ formatMissingFrontendDependenciesGuidance,
+ getMissingFrontendDependencyBins,
+ validateFrontendDependencies,
validateLocalAgentServerPath,
findFreePort,
findFreePorts,
@@ -218,6 +221,66 @@ describe("buildSafeDevConfigAsync", () => {
});
});
+describe("frontend dependency preflight", () => {
+ let tempRoot: string | null = null;
+
+ afterEach(() => {
+ if (tempRoot) {
+ rmSync(tempRoot, { recursive: true, force: true });
+ tempRoot = null;
+ }
+ });
+
+ function makeTempRoot(): string {
+ tempRoot = mkdtempSync(path.join(tmpdir(), "frontend-deps-"));
+ return tempRoot;
+ }
+
+ function writeBin(root: string, name: string): void {
+ const binDir = path.join(root, "node_modules", ".bin");
+ mkdirSync(binDir, { recursive: true });
+ writeFileSync(path.join(binDir, name), "#!/bin/sh\n");
+ }
+
+ it("reports required npm binaries when node_modules has not been installed", () => {
+ const root = makeTempRoot();
+
+ expect(getMissingFrontendDependencyBins(root, "linux")).toEqual([
+ "cross-env",
+ "react-router",
+ ]);
+ });
+
+ it("passes when required npm binary shims exist", () => {
+ const root = makeTempRoot();
+ writeBin(root, "cross-env");
+ writeBin(root, "react-router");
+
+ expect(getMissingFrontendDependencyBins(root, "linux")).toEqual([]);
+ expect(() => validateFrontendDependencies(root, "linux")).not.toThrow();
+ });
+
+ it("accepts Windows command shims", () => {
+ const root = makeTempRoot();
+ writeBin(root, "cross-env.cmd");
+ writeBin(root, "react-router.cmd");
+
+ expect(getMissingFrontendDependencyBins(root, "win32")).toEqual([]);
+ });
+
+ it("formats an actionable npm ci message", () => {
+ const guidance = formatMissingFrontendDependenciesGuidance(
+ ["cross-env"],
+ "/workspace/project/agent-canvas",
+ );
+
+ expect(guidance).toContain("Frontend dependencies are not installed");
+ expect(guidance).toContain("Missing npm binaries: cross-env");
+ expect(guidance).toContain("npm ci");
+ expect(guidance).toContain("/workspace/project/agent-canvas");
+ });
+});
+
describe("formatMissingUvxGuidance", () => {
it("includes install, PATH, README, and fallback workflow hints", () => {
const guidance = formatMissingUvxGuidance(
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index 27b2a4d666..c19cf09c79 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -33,6 +33,7 @@ const DEFAULT_SECRET_KEY = "openhands-dev-secret-key-change-in-prod";
// Default agent-server version (released PyPI version)
// Set OH_AGENT_SERVER_GIT_REF to use a git branch/SHA instead
const DEFAULT_AGENT_SERVER_VERSION = "1.22.0";
+const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];
/**
* Generate a cryptographically secure random API key.
@@ -250,6 +251,56 @@ export function formatMissingUvxGuidance(cwd = process.cwd()) {
].join("\n");
}
+function npmBinCandidates(binName, platform = process.platform) {
+ const candidates = [binName];
+ if (platform === "win32") {
+ candidates.push(`${binName}.cmd`, `${binName}.ps1`);
+ }
+ return candidates;
+}
+
+export function getMissingFrontendDependencyBins(
+ cwd = process.cwd(),
+ platform = process.platform,
+) {
+ const binDir = path.join(cwd, "node_modules", ".bin");
+ return FRONTEND_REQUIRED_BINS.filter(
+ (binName) =>
+ !npmBinCandidates(binName, platform).some((candidate) =>
+ existsSync(path.join(binDir, candidate)),
+ ),
+ );
+}
+
+export function formatMissingFrontendDependenciesGuidance(
+ missingBins,
+ cwd = process.cwd(),
+) {
+ const missingList = missingBins.join(", ");
+ return [
+ "Frontend dependencies are not installed or are incomplete.",
+ "",
+ `Missing npm binaries: ${missingList}`,
+ "",
+ "Run this from the repository root:",
+ " npm ci",
+ "",
+ `Repository root: ${cwd}`,
+ ].join("\n");
+}
+
+export function validateFrontendDependencies(
+ cwd = process.cwd(),
+ platform = process.platform,
+) {
+ const missingBins = getMissingFrontendDependencyBins(cwd, platform);
+ if (missingBins.length > 0) {
+ throw new Error(
+ formatMissingFrontendDependenciesGuidance(missingBins, cwd),
+ );
+ }
+}
+
/**
* Build the uvx command and arguments for running agent-server.
*
@@ -616,6 +667,8 @@ function spawnProcess(command, args, options) {
async function main() {
console.log("Starting isolated agent-server + frontend dev stack...");
+ validateFrontendDependencies();
+ console.log("Frontend dependencies found.");
console.log("Allocating ports...");
// Use async config builder with dynamic port allocation
diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjs
index a26cf1fe99..7a1e454e68 100644
--- a/scripts/dev-with-automation.mjs
+++ b/scripts/dev-with-automation.mjs
@@ -53,6 +53,7 @@ import {
formatMissingUvxGuidance,
generateRandomApiKey,
findFreePorts,
+ validateFrontendDependencies,
} from "./dev-safe.mjs";
const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -321,7 +322,7 @@ function commandExists(cmd) {
return result.status === 0;
}
-function checkPrerequisites() {
+function checkPrerequisites({ checkFrontendDependencies = true } = {}) {
logStep("1/2", "Checking prerequisites...");
if (!commandExists("uvx")) {
@@ -335,6 +336,16 @@ function checkPrerequisites() {
process.exit(1);
}
logSuccess("npm found");
+
+ if (checkFrontendDependencies) {
+ try {
+ validateFrontendDependencies(projectRoot);
+ } catch (error) {
+ logError(error instanceof Error ? error.message : String(error));
+ process.exit(1);
+ }
+ logSuccess("frontend dependencies found");
+ }
}
function ensureDirectories(config) {
@@ -718,7 +729,7 @@ async function main(options = {}) {
// Setup phase
// (uvx is still required even in docker mode because the automation
// backend runs via uvx; only the agent-server is dockerized.)
- checkPrerequisites();
+ checkPrerequisites({ checkFrontendDependencies: !useStaticMode });
// In static mode, verify build exists
if (useStaticMode && !existsSync(staticDir)) {