Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(renderer-service): dependency install step (phase 3)

okanasl605d1da333d3
diff --git a/apps/renderer-service/package.json b/apps/renderer-service/package.json
index ff7d7700..f80818ca 100644
--- a/apps/renderer-service/package.json
+++ b/apps/renderer-service/package.json
@@ -22,14 +22,17 @@
"@framefields/server-utils": "workspace:*",
"@hono/node-server": "^1.19.11",
"dotenv": "^17.0.1",
+ "framefields": "workspace:*",
"hono": "^4.13.7",
+ "semver": "^7.8.5",
"zod": "^4.3.6"
},
"devDependencies": {
+ "@framefields/tsconfig": "workspace:*",
"@types/node": "^24.1.0",
+ "@types/semver": "^7.8.0",
"tsx": "^4.20.3",
"typescript": "^5.8.3",
- "vitest": "^4.1.5",
- "@framefields/tsconfig": "workspace:*"
+ "vitest": "^4.1.5"
}
}
diff --git a/apps/renderer-service/src/index.ts b/apps/renderer-service/src/index.ts
index 40430ca7..3eb1d9a3 100644
--- a/apps/renderer-service/src/index.ts
+++ b/apps/renderer-service/src/index.ts
@@ -7,6 +7,7 @@ import { describeConfig, loadConfig, scrubSecretEnv } from "./config/index.js";
import { RenderError } from "./errors.js";
import { checkout } from "./git/checkout.js";
import { createApp } from "./http/app.js";
+import { install } from "./install/installer.js";
import type { Pipeline } from "./jobs/pipeline.js";
import { JobRunner } from "./jobs/runner.js";
import { ReadinessTracker } from "./readiness.js";
@@ -30,7 +31,7 @@ const notYet = (step: string): never => {
// Steps land phase by phase (PLAN.md §13).
const pipeline: Pipeline = {
checkout,
- install: async () => notYet("install"),
+ install,
render: async () => notYet("render"),
deliver: async () => notYet("deliver"),
};
diff --git a/apps/renderer-service/src/install/installer.test.ts b/apps/renderer-service/src/install/installer.test.ts
new file mode 100644
index 00000000..3b806aba
--- /dev/null
+++ b/apps/renderer-service/src/install/installer.test.ts
@@ -0,0 +1,259 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { RenderError } from "../errors.js";
+import { CommandError } from "../git/exec.js";
+import type { CheckoutResult, StepContext } from "../jobs/pipeline.js";
+import { testConfig } from "../test-helpers.js";
+import {
+ bundledEngineVersion,
+ classifyInstallError,
+ install,
+ STAMP_FILE,
+} from "./installer.js";
+import { inspectProject, needsNoInstall } from "./project.js";
+
+let tmp: string;
+
+beforeAll(async () => {
+ tmp = await fs.realpath(
+ await fs.mkdtemp(path.join(os.tmpdir(), "ff-install-test-")),
+ );
+});
+afterAll(async () => {
+ await fs.rm(tmp, { recursive: true, force: true });
+});
+
+async function project(name: string, files: Record<string, unknown>) {
+ const root = path.join(tmp, name);
+ for (const [rel, content] of Object.entries(files)) {
+ const file = path.join(root, rel);
+ await fs.mkdir(path.dirname(file), { recursive: true });
+ await fs.writeFile(
+ file,
+ typeof content === "string" ? content : JSON.stringify(content, null, 2),
+ );
+ }
+ return root;
+}
+
+function context(env: Record<string, string> = {}) {
+ const warnings: string[] = [];
+ const ctx: StepContext = {
+ jobId: "t",
+ config: testConfig({
+ FF_CACHE_DIR: path.join(tmp, "cache"),
+ FF_WORK_DIR: path.join(tmp, "work"),
+ ...env,
+ }),
+ signal: new AbortController().signal,
+ jobDir: tmp,
+ progress: () => {},
+ warn: (code) => warnings.push(code),
+ };
+ return { ctx, warnings };
+}
+
+const checkoutOf = (root: string, workdir = root): CheckoutResult => ({
+ root,
+ workdir,
+ sha: "x",
+ cache: {},
+ release: async () => {},
+});
+
+async function codeOf(promise: Promise<unknown>) {
+ try {
+ await promise;
+ return "no error";
+ } catch (err) {
+ return err instanceof RenderError ? err.code : String(err);
+ }
+}
+
+describe("project inspection", () => {
+ it("finds the workspace root and package manager above the workdir", async () => {
+ const root = await project("mono", {
+ "package.json": {
+ name: "root",
+ packageManager: "[email protected]+sha512.abc",
+ },
+ "pnpm-workspace.yaml": "packages:\n - videos/*\n",
+ "pnpm-lock.yaml": "lockfileVersion: '9.0'\n",
+ "videos/launch/package.json": { name: "launch" },
+ });
+ const info = await inspectProject(root, path.join(root, "videos/launch"));
+ expect(info).toMatchObject({
+ installRoot: root,
+ manager: "pnpm",
+ managerSpec: "[email protected]",
+ inWorkspace: true,
+ });
+ });
+
+ it("detects yarn berry from the lockfile", async () => {
+ const root = await project("berry", {
+ "package.json": { name: "b" },
+ "yarn.lock": "__metadata:\n version: 8\n",
+ });
+ expect((await inspectProject(root, root))?.yarnBerry).toBe(true);
+ });
+
+ it("rejects bun lockfiles", async () => {
+ const root = await project("bun", {
+ "package.json": { name: "b" },
+ "bun.lockb": "",
+ });
+ expect(await codeOf(inspectProject(root, root))).toBe("INSTALL_FAILED");
+ });
+
+ it("needs no install when only framefields and tooling are used", () => {
+ expect(
+ needsNoInstall({
+ dependencies: {
+ framefields: "^2.1.0",
+ "@framefields/compositions": "workspace:*",
+ },
+ devDependencies: { typescript: "^5", tsx: "^4", "@types/node": "^24" },
+ }),
+ ).toBe(true);
+ expect(
+ needsNoInstall({ dependencies: { framefields: "^2", mediabunny: "^1" } }),
+ ).toBe(false);
+ });
+});
+
+describe("install step", () => {
+ it("skips projects that only need framefields, warning on a version mismatch", async () => {
+ const root = await project("plain", {
+ "package.json": { name: "p", dependencies: { framefields: "^0.1.0" } },
+ });
+ const { ctx, warnings } = context();
+ const result = await install(checkoutOf(root), ctx);
+ expect(result).toMatchObject({ skipped: true, declaredEngine: "^0.1.0" });
+ expect(warnings).toContain("ENGINE_MISMATCH");
+ });
+
+ it("fails on an engine mismatch when the policy says so", async () => {
+ const root = await project("strict", {
+ "package.json": { name: "p", dependencies: { framefields: "^0.1.0" } },
+ });
+ const { ctx } = context({ FF_ENGINE_POLICY: "fail" });
+ expect(await codeOf(install(checkoutOf(root), ctx))).toBe(
+ "ENGINE_INCOMPATIBLE",
+ );
+ });
+
+ it("accepts the bundled version and workspace ranges", async () => {
+ const root = await project("ok", {
+ "package.json": {
+ name: "p",
+ dependencies: { framefields: `^${bundledEngineVersion()}` },
+ devDependencies: { "@framefields/x": "workspace:*" },
+ },
+ });
+ const { ctx, warnings } = context();
+ await install(checkoutOf(root), ctx);
+ expect(warnings).toEqual([]);
+ });
+
+ it("requires a lockfile when dependencies must be installed", async () => {
+ const root = await project("nolock", {
+ "package.json": { name: "p", dependencies: { "left-pad": "1.3.0" } },
+ });
+ expect(await codeOf(install(checkoutOf(root), context().ctx))).toBe(
+ "LOCKFILE_MISSING",
+ );
+ });
+
+ it("runs npm ci once, then reuses node_modules until the lockfile changes", async () => {
+ const root = await project("npm-project", {
+ "package.json": {
+ name: "film",
+ version: "1.0.0",
+ dependencies: { helper: "file:./helper" },
+ },
+ "helper/package.json": { name: "helper", version: "1.0.0" },
+ "helper/index.js": "module.exports = 1;\n",
+ });
+ // Generate a real lockfile offline (file: deps need no registry).
+ execFileSync(
+ "npm",
+ [
+ "install",
+ "--package-lock-only",
+ "--offline",
+ "--no-audit",
+ "--no-fund",
+ ],
+ {
+ cwd: root,
+ stdio: "ignore",
+ },
+ );
+
+ const first = await install(checkoutOf(root), context().ctx);
+ expect(first.cache.install).toBe("miss");
+ expect(existsSync(path.join(root, "node_modules/helper/index.js"))).toBe(
+ true,
+ );
+ expect(existsSync(path.join(root, STAMP_FILE))).toBe(true);
+
+ const second = await install(checkoutOf(root), context().ctx);
+ expect(second.cache.install).toBe("hit");
+
+ const pkg = JSON.parse(
+ await fs.readFile(path.join(root, "package.json"), "utf8"),
+ );
+ pkg.description = "changed";
+ await fs.writeFile(path.join(root, "package.json"), JSON.stringify(pkg));
+ const third = await install(checkoutOf(root), context().ctx);
+ expect(third.cache.install).toBe("miss");
+ }, 120_000);
+});
+
+describe("install error classification", () => {
+ const failure = (stderr: string, timedOut = false) =>
+ new CommandError("pnpm install", {
+ stdout: "",
+ stderr,
+ code: 1,
+ timedOut,
+ aborted: false,
+ });
+
+ it.each([
+ [
+ "ERR_PNPM_OUTDATED_LOCKFILE Cannot install with frozen-lockfile",
+ "INSTALL_FAILED",
+ /lockfile/,
+ ],
+ ["npm ERR! code E401 Unable to authenticate", "INSTALL_FAILED", /FF_NPMRC/],
+ ["gyp ERR! build error", "INSTALL_FAILED", /-full image/],
+ ["ENOSPC: no space left on device", "DISK_FULL", undefined],
+ ])("%s → %s", (stderr, code, hint) => {
+ const err = classifyInstallError(failure(stderr), "/repo");
+ expect(err.code).toBe(code);
+ if (hint) expect(err.hint).toMatch(hint);
+ });
+
+ it("marks registry outages transient and timeouts as INSTALL_TIMEOUT", () => {
+ expect(
+ classifyInstallError(failure("ECONNRESET"), "/r").details?.transient,
+ ).toBe(true);
+ expect(classifyInstallError(failure("", true), "/r").code).toBe(
+ "INSTALL_TIMEOUT",
+ );
+ });
+
+ it("keeps the repo path out of messages", () => {
+ const err = classifyInstallError(
+ failure("failed in /work/ws/abc/0/videos"),
+ "/work/ws/abc/0",
+ );
+ expect(JSON.stringify(err.toJSON())).not.toContain("/work/ws/abc/0");
+ });
+});
diff --git a/apps/renderer-service/src/install/installer.ts b/apps/renderer-service/src/install/installer.ts
new file mode 100644
index 00000000..3e8c8c5a
--- /dev/null
+++ b/apps/renderer-service/src/install/installer.ts
@@ -0,0 +1,399 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import semver from "semver";
+import type { RendererConfig } from "../config/index.js";
+import { RenderError } from "../errors.js";
+import { CommandError, exec } from "../git/exec.js";
+import type { Pipeline, StepContext } from "../jobs/pipeline.js";
+import { redact } from "../redact.js";
+import {
+ declaredEngineRange,
+ inspectProject,
+ needsNoInstall,
+ type ProjectInfo,
+} from "./project.js";
+
+export const STAMP_FILE = ".ff-install-stamp";
+
+let engineVersion: string | undefined;
+
+/** Version of the framefields copy this worker renders with. */
+export function bundledEngineVersion(): string {
+ if (engineVersion) return engineVersion;
+ // The package doesn't export ./package.json; walk up from its entry.
+ let dir = path.dirname(fileURLToPath(import.meta.resolve("framefields")));
+ for (;;) {
+ const file = path.join(dir, "package.json");
+ if (existsSync(file)) {
+ const pkg = JSON.parse(readFileSync(file, "utf8")) as {
+ name?: string;
+ version: string;
+ };
+ if (pkg.name === "framefields") {
+ engineVersion = pkg.version;
+ return engineVersion;
+ }
+ }
+ if (path.dirname(dir) === dir)
+ throw new Error("framefields package.json not found");
+ dir = path.dirname(dir);
+ }
+}
+
+/**
+ * Pipeline step: installs the project's dependencies (PLAN.md §7). Skipped
+ * when the project only needs framefields, or when the lockfile hasn't
+ * changed since the last install in this workspace slot.
+ */
+export const install: Pipeline["install"] = async (checkout, ctx) => {
+ const project = await inspectProject(checkout.root, checkout.workdir);
+ if (!project) {
+ ctx.warn(
+ "NO_PACKAGE_JSON",
+ "The workdir has no package.json; rendering without installing dependencies.",
+ );
+ return { skipped: true, cache: { install: "skipped" } };
+ }
+
+ const declaredEngine = declaredEngineRange(project.pkg);
+ checkEngine(declaredEngine, ctx);
+ checkNodeEngine(project, ctx);
+
+ if (needsNoInstall(project.pkg)) {
+ return {
+ skipped: true,
+ packageManager: project.manager,
+ declaredEngine,
+ cache: { install: "skipped" },
+ };
+ }
+
+ if (!project.lockfile && !ctx.config.install.allowUnlocked) {
+ throw new RenderError(
+ "LOCKFILE_MISSING",
+ "The project has no lockfile, so the install wouldn't be reproducible.",
+ {
+ phase: "install",
+ hint: "Commit pnpm-lock.yaml / package-lock.json / yarn.lock (or set FF_ALLOW_UNLOCKED_INSTALL=true).",
+ },
+ );
+ }
+
+ const stampPath = path.join(project.installRoot, STAMP_FILE);
+ const stamp = await installStamp(project, ctx.config, checkout.root);
+ const previous = await fs.readFile(stampPath, "utf8").catch(() => "");
+ if (
+ previous === stamp &&
+ existsSync(path.join(project.installRoot, "node_modules"))
+ ) {
+ return {
+ skipped: false,
+ packageManager: project.manager,
+ declaredEngine,
+ cache: { install: "hit" },
+ };
+ }
+
+ // A half-finished install must never be trusted by the next job.
+ await fs.rm(stampPath, { force: true });
+ await runInstall(project, ctx, checkout.root);
+ await fs.writeFile(stampPath, stamp);
+ return {
+ skipped: false,
+ packageManager: project.manager,
+ declaredEngine,
+ cache: { install: "miss" },
+ };
+};
+
+function checkEngine(declared: string | undefined, ctx: StepContext): void {
+ if (!declared) return;
+ const range = declared.replace(/^npm:framefields@/, "");
+ if (!semver.validRange(range)) return; // workspace:*, file:, git URLs, tags
+ const bundled = bundledEngineVersion();
+ if (semver.satisfies(bundled, range, { includePrerelease: true })) return;
+ const message = `The project asks for framefields ${range}; this worker renders with ${bundled}.`;
+ if (ctx.config.install.enginePolicy === "fail") {
+ throw new RenderError("ENGINE_INCOMPATIBLE", message, {
+ phase: "install",
+ hint: "Use a worker image whose framefields version matches, or update the project's dependency.",
+ });
+ }
+ ctx.warn("ENGINE_MISMATCH", message);
+}
+
+function checkNodeEngine(project: ProjectInfo, ctx: StepContext): void {
+ const range = project.pkg.engines?.node;
+ if (
+ range &&
+ semver.validRange(range) &&
+ !semver.satisfies(process.versions.node, range)
+ ) {
+ ctx.warn(
+ "NODE_ENGINE_MISMATCH",
+ `The project wants Node ${range}; the worker runs ${process.versions.node}.`,
+ );
+ }
+}
+
+/** Everything that changes what an install produces. */
+async function installStamp(
+ project: ProjectInfo,
+ config: RendererConfig,
+ repoRoot: string,
+): Promise<string> {
+ const hash = createHash("sha256");
+ hash.update(
+ project.lockfile ? await fs.readFile(project.lockfile) : "no-lockfile",
+ );
+ hash.update(
+ await fs.readFile(path.join(project.installRoot, "package.json")),
+ );
+ if (project.inWorkspace)
+ hash.update(
+ await fs.readFile(path.join(project.packageDir, "package.json")),
+ );
+ hash.update(
+ JSON.stringify({
+ manager: project.managerSpec ?? project.manager,
+ node: process.versions.modules,
+ platform: `${process.platform}-${process.arch}`,
+ scripts: config.install.scripts,
+ filter: path.relative(repoRoot, project.packageDir),
+ npmrc: config.install.npmrc
+ ? createHash("sha256").update(config.install.npmrc).digest("hex")
+ : "",
+ }),
+ );
+ return hash.digest("hex");
+}
+
+function installCommand(
+ project: ProjectInfo,
+ config: RendererConfig,
+): string[] {
+ const cache = config.paths.cacheDir;
+ const rel = path.relative(project.installRoot, project.packageDir) || ".";
+ const noScripts = !config.install.scripts;
+ switch (project.manager) {
+ case "pnpm":
+ return [
+ "pnpm",
+ "install",
+ project.lockfile ? "--frozen-lockfile" : "--no-frozen-lockfile",
+ "--prefer-offline",
+ "--reporter=append-only",
+ "--config.confirmModulesPurge=false",
+ `--store-dir=${path.join(cache, "pnpm-store")}`,
+ ...(project.inWorkspace ? [`--filter=./${rel}...`] : []),
+ ...(noScripts ? ["--ignore-scripts"] : []),
+ ];
+ case "npm":
+ return [
+ "npm",
+ project.lockfile ? "ci" : "install",
+ "--prefer-offline",
+ "--no-audit",
+ "--no-fund",
+ `--cache=${path.join(cache, "npm-cache")}`,
+ ...(project.inWorkspace
+ ? [`--workspace=${rel}`, "--include-workspace-root=false"]
+ : []),
+ ...(noScripts ? ["--ignore-scripts"] : []),
+ ];
+ case "yarn":
+ return project.yarnBerry
+ ? [
+ "yarn",
+ "install",
+ project.lockfile ? "--immutable" : "--no-immutable",
+ "--inline-builds",
+ ]
+ : [
+ "yarn",
+ "install",
+ project.lockfile ? "--frozen-lockfile" : "--no-lockfile",
+ "--prefer-offline",
+ "--non-interactive",
+ `--cache-folder=${path.join(cache, "yarn-cache")}`,
+ ...(noScripts ? ["--ignore-scripts"] : []),
+ ];
+ }
+}
+
+async function runInstall(
+ project: ProjectInfo,
+ ctx: StepContext,
+ repoRoot: string,
+): Promise<void> {
+ const config = ctx.config;
+ const home = await fs.mkdtemp(path.join(os.tmpdir(), "ff-install-"));
+ try {
+ const env: NodeJS.ProcessEnv = {
+ PATH: process.env.PATH,
+ HOME: home,
+ TMPDIR: home,
+ CI: "true",
+ LANG: "C.UTF-8",
+ TZ: "UTC",
+ COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+ COREPACK_ENABLE_STRICT: "0",
+ COREPACK_HOME: path.join(config.paths.cacheDir, "corepack"),
+ npm_config_update_notifier: "false",
+ YARN_ENABLE_TELEMETRY: "0",
+ YARN_ENABLE_GLOBAL_CACHE: "true",
+ YARN_GLOBAL_FOLDER: path.join(config.paths.cacheDir, "yarn-berry"),
+ ...(project.yarnBerry &&
+ !config.install.scripts && { YARN_ENABLE_SCRIPTS: "false" }),
+ };
+ if (config.install.npmrc) {
+ const npmrc = path.join(home, ".npmrc");
+ await fs.writeFile(npmrc, config.install.npmrc, { mode: 0o600 });
+ env.npm_config_userconfig = npmrc;
+ env.NPM_CONFIG_USERCONFIG = npmrc;
+ }
+
+ const [pm, ...args] = installCommand(project, config);
+ const useCorepack = await hasCorepack();
+ const file = useCorepack ? "corepack" : pm;
+ const argv = useCorepack ? [pm, ...args] : args;
+
+ ctx.progress({
+ phase: "installing",
+ message: `${project.managerSpec ?? pm} ${args[0]}`,
+ });
+ const attempt = () =>
+ exec(file, argv, {
+ cwd: project.installRoot,
+ env,
+ signal: ctx.signal,
+ timeoutMs: config.limits.timeouts.install * 1000,
+ maxStdoutBytes: 1024 * 1024,
+ });
+ try {
+ await attempt();
+ } catch (err) {
+ const classified = classifyInstallError(err, repoRoot);
+ // One retry for registry hiccups; everything else is deterministic.
+ if (classified.details?.transient && !ctx.signal.aborted) {
+ await attempt().catch((retryErr) => {
+ throw classifyInstallError(retryErr, repoRoot);
+ });
+ } else {
+ throw classified;
+ }
+ }
+ } finally {
+ await fs.rm(home, { recursive: true, force: true });
+ }
+}
+
+let corepackAvailable: Promise<boolean> | undefined;
+function hasCorepack(): Promise<boolean> {
+ corepackAvailable ??= exec("corepack", ["--version"], {
+ timeoutMs: 10_000,
+ }).then(
+ () => true,
+ () => false,
+ );
+ return corepackAvailable;
+}
+
+export function classifyInstallError(
+ err: unknown,
+ repoRoot: string,
+): RenderError {
+ if (err instanceof RenderError) return err;
+ if (!(err instanceof CommandError)) {
+ const message = err instanceof Error ? err.message : String(err);
+ if (/ENOENT/.test(message)) {
+ return new RenderError(
+ "TOOL_MISSING",
+ `Package manager not found: ${message}`,
+ { phase: "install" },
+ );
+ }
+ return new RenderError("INSTALL_FAILED", redact(message), {
+ phase: "install",
+ cause: err,
+ });
+ }
+ const output = `${err.result.stderr}\n${err.result.stdout}`;
+ const logTail = redact(
+ output.trim().split("\n").slice(-40).join("\n"),
+ ).replaceAll(repoRoot, "<repo>");
+ const fail = (hint?: string, transient = false) =>
+ new RenderError(
+ "INSTALL_FAILED",
+ err.message.replaceAll(repoRoot, "<repo>"),
+ {
+ phase: "install",
+ hint,
+ details: { log: logTail, ...(transient && { transient }) },
+ cause: err,
+ },
+ );
+
+ if (err.result.timedOut) {
+ return new RenderError(
+ "INSTALL_TIMEOUT",
+ "The dependency install timed out.",
+ {
+ phase: "install",
+ hint: "Raise FF_TIMEOUT_INSTALL_SEC, or keep a network volume so the package store stays warm.",
+ details: { log: logTail },
+ },
+ );
+ }
+ if (/ENOSPC|No space left on device/i.test(output)) {
+ return new RenderError("DISK_FULL", "Ran out of disk during the install.", {
+ phase: "install",
+ });
+ }
+ if (
+ /ERR_PNPM_OUTDATED_LOCKFILE|ERR_PNPM_LOCKFILE|frozen-lockfile|can only install packages when your package\.json and package-lock\.json|lockfile would have been modified|YN0028/i.test(
+ output,
+ )
+ ) {
+ return fail(
+ "The lockfile is out of date with package.json; run the install locally and commit the lockfile.",
+ );
+ }
+ if (
+ /E401|E403|ERR_PNPM_FETCH_40[13]|Unauthorized|authentication token/i.test(
+ output,
+ )
+ ) {
+ return fail(
+ "A private registry rejected the request; set FF_NPMRC with an auth token.",
+ );
+ }
+ if (
+ /E404|ERR_PNPM_FETCH_404|ERR_PNPM_NO_MATCHING_VERSION|Not Found - GET/i.test(
+ output,
+ )
+ ) {
+ return fail("A dependency (or version) doesn't exist on the registry.");
+ }
+ if (
+ /node-gyp|gyp ERR|make: \*\*\*|g\+\+|cc1plus|Python is not set/i.test(
+ output,
+ )
+ ) {
+ return fail(
+ "A native dependency needed compiling; use the -full image, which has a toolchain.",
+ );
+ }
+ if (
+ /ETIMEDOUT|ECONNRESET|EAI_AGAIN|ENOTFOUND|socket hang up|ERR_SOCKET_TIMEOUT|\b50[234]\b/i.test(
+ output,
+ )
+ ) {
+ return fail("The package registry was unreachable.", true);
+ }
+ return fail();
+}
diff --git a/apps/renderer-service/src/install/project.ts b/apps/renderer-service/src/install/project.ts
new file mode 100644
index 00000000..09157777
--- /dev/null
+++ b/apps/renderer-service/src/install/project.ts
@@ -0,0 +1,170 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RenderError } from "../errors.js";
+
+export type PackageManagerName = "pnpm" | "npm" | "yarn";
+
+export interface PackageJson {
+ name?: string;
+ packageManager?: string;
+ workspaces?: string[] | { packages?: string[] };
+ dependencies?: Record<string, string>;
+ devDependencies?: Record<string, string>;
+ engines?: Record<string, string>;
+}
+
+export interface ProjectInfo {
+ /** Directory the install runs in (workspace root or the package itself). */
+ installRoot: string;
+ /** The package being rendered. */
+ packageDir: string;
+ pkg: PackageJson;
+ manager: PackageManagerName;
+ /** e.g. "[email protected]" from `packageManager`, if pinned. */
+ managerSpec?: string;
+ lockfile?: string;
+ /** Yarn ≥ 2 (berry) uses different flags. */
+ yarnBerry: boolean;
+ /** True when the package is a member of a workspace rooted above it. */
+ inWorkspace: boolean;
+}
+
+const LOCKFILES: [string, PackageManagerName][] = [
+ ["pnpm-lock.yaml", "pnpm"],
+ ["yarn.lock", "yarn"],
+ ["package-lock.json", "npm"],
+ ["npm-shrinkwrap.json", "npm"],
+];
+
+const UNSUPPORTED_LOCKFILES = ["bun.lockb", "bun.lock"];
+
+export async function readPackageJson(
+ dir: string,
+): Promise<PackageJson | undefined> {
+ const file = path.join(dir, "package.json");
+ if (!existsSync(file)) return undefined;
+ try {
+ return JSON.parse(await fs.readFile(file, "utf8")) as PackageJson;
+ } catch (err) {
+ throw new RenderError(
+ "INSTALL_FAILED",
+ `${path.relative(process.cwd(), file)} is not valid JSON.`,
+ {
+ phase: "install",
+ cause: err,
+ },
+ );
+ }
+}
+
+/**
+ * Finds the install root: the nearest directory between the workdir and the
+ * repo root that holds a lockfile or declares workspaces.
+ */
+export async function inspectProject(
+ repoRoot: string,
+ workdir: string,
+): Promise<ProjectInfo | undefined> {
+ const pkg = await readPackageJson(workdir);
+ if (!pkg) return undefined;
+
+ let installRoot = workdir;
+ let rootPkg = pkg;
+ for (let dir = workdir; ; dir = path.dirname(dir)) {
+ const dirPkg = dir === workdir ? pkg : await readPackageJson(dir);
+ const hasLock = LOCKFILES.some(([f]) => existsSync(path.join(dir, f)));
+ const isWorkspaceRoot =
+ existsSync(path.join(dir, "pnpm-workspace.yaml")) ||
+ Boolean(dirPkg?.workspaces);
+ if (dirPkg && (hasLock || isWorkspaceRoot)) {
+ installRoot = dir;
+ rootPkg = dirPkg;
+ break;
+ }
+ if (dir === repoRoot || path.dirname(dir) === dir) break;
+ }
+
+ for (const file of UNSUPPORTED_LOCKFILES) {
+ if (existsSync(path.join(installRoot, file))) {
+ throw new RenderError(
+ "INSTALL_FAILED",
+ `${file} found: bun projects aren't supported yet.`,
+ {
+ phase: "install",
+ hint: "Commit a pnpm, npm or yarn lockfile.",
+ },
+ );
+ }
+ }
+
+ const managerSpec = rootPkg.packageManager?.split("+")[0];
+ const lock = LOCKFILES.find(([f]) => existsSync(path.join(installRoot, f)));
+ const fromSpec = managerSpec?.split("@")[0] as PackageManagerName | undefined;
+ const manager: PackageManagerName =
+ fromSpec && ["pnpm", "npm", "yarn"].includes(fromSpec)
+ ? fromSpec
+ : (lock?.[1] ?? "npm");
+
+ let yarnBerry = false;
+ if (manager === "yarn") {
+ const major = Number(managerSpec?.split("@")[1]?.split(".")[0] ?? 0);
+ const lockText = lock
+ ? await fs.readFile(path.join(installRoot, lock[0]), "utf8")
+ : "";
+ yarnBerry = major >= 2 || lockText.includes("__metadata:");
+ }
+
+ return {
+ installRoot,
+ packageDir: workdir,
+ pkg,
+ manager,
+ managerSpec,
+ lockfile: lock ? path.join(installRoot, lock[0]) : undefined,
+ yarnBerry,
+ inWorkspace: installRoot !== workdir,
+ };
+}
+
+/** Packages the worker provides itself (resolved to its copy, PLAN.md §7). */
+export function isEnginePackage(name: string): boolean {
+ return name === "framefields" || name.startsWith("@framefields/");
+}
+
+/** Build/typing tools that never load at render time. */
+const TOOLING = [
+ /^typescript$/,
+ /^tsx$/,
+ /^ts-node$/,
+ /^@types\//,
+ /^vitest$/,
+ /^@vitest\//,
+ /^@biomejs\//,
+ /^eslint/,
+ /^@eslint\//,
+ /^prettier/,
+ /^tsdown$/,
+ /^tsup$/,
+ /^esbuild$/,
+ /^lefthook$/,
+ /^husky$/,
+];
+
+/**
+ * True when the package needs nothing beyond what the worker provides: every
+ * dependency is a framefields package and every dev dependency is tooling.
+ */
+export function needsNoInstall(pkg: PackageJson): boolean {
+ const deps = Object.keys(pkg.dependencies ?? {});
+ const dev = Object.keys(pkg.devDependencies ?? {});
+ return (
+ deps.every(isEnginePackage) &&
+ dev.every((d) => isEnginePackage(d) || TOOLING.some((re) => re.test(d)))
+ );
+}
+
+/** The range the package declares for `framefields`, if any. */
+export function declaredEngineRange(pkg: PackageJson): string | undefined {
+ return pkg.dependencies?.framefields ?? pkg.devDependencies?.framefields;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 10adf779..8979859f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -193,9 +193,15 @@ importers:
dotenv:
specifier: ^17.0.1
version: 17.3.1
+ framefields:
+ specifier: workspace:*
+ version: link:../../packages/framefields
hono:
specifier: ^4.13.7
version: 4.13.13
+ semver:
+ specifier: ^7.8.5
+ version: 7.8.5
zod:
specifier: ^4.3.6
version: 4.3.6
@@ -206,6 +212,9 @@ importers:
'@types/node':
specifier: ^24.1.0
version: 24.10.14
+ '@types/semver':
+ specifier: ^7.8.0
+ version: 7.8.0
tsx:
specifier: ^4.20.3
version: 4.21.0
@@ -4923,6 +4932,9 @@ packages:
resolution: {integrity: sha512-OowOUbD1lBCOFIPOZ8xnMIhgqA4sCutMiYOmPHL1PTLt5+y1XA+g2+yC9OOyz8p+deMZqPZLxfMjYIfrKsPeFg==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-1mAINjtQCXXeLkJ9ehXkwOcBpqtLxiVtKhpUf83DdRNdQKV0iXZpaHYqRr7nj+wvxuJzoAmAwXI+sCNMv1CzLQ==}
+
'@vitest/[email protected]':
resolution: {integrity: sha512-8MVGEFnJIcdGjcbfKmeq8z0pZHH0JlVtoVZH9Q/qwUp6wyFnEJUBMrw9DCaj+ra3vShGmhavjalMIhPNxZAUcw==}
peerDependencies:
@@ -6081,11 +6093,6 @@ packages:
resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
engines: {node: '>=v12.22.7'}
- resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==}
- engines: {node: '>=10'}
- hasBin: true
-
resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
engines: {node: '>=10'}
@@ -7200,7 +7207,7 @@ snapshots:
package-manager-detector: 0.2.11
picocolors: 1.1.1
resolve-from: 5.0.0
- semver: 7.7.4
+ semver: 7.8.5
spawndamnit: 3.0.1
term-size: 2.2.1
transitivePeerDependencies:
@@ -8642,6 +8649,8 @@ snapshots:
dependencies:
undici-types: 7.16.0
+ '@types/[email protected]': {}
+
dependencies:
'@bcoe/v8-coverage': 1.0.2
@@ -9908,8 +9917,6 @@ snapshots:
dependencies:
xmlchars: 2.2.0
-