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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.yamlindex 10adf779..8979859f 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -193,9 +193,15 @@ importers:dotenv:specifier: ^17.0.1version: 17.3.1+ framefields:+ specifier: workspace:*+ version: link:../../packages/framefieldshono:specifier: ^4.13.7version: 4.13.13+ semver:+ specifier: ^7.8.5+ version: 7.8.5zod:specifier: ^4.3.6version: 4.3.6@@ -206,6 +212,9 @@ importers:'@types/node':specifier: ^24.1.0version: 24.10.14+ '@types/semver':+ specifier: ^7.8.0+ version: 7.8.0tsx:specifier: ^4.20.3version: 4.21.0@@ -4923,6 +4932,9 @@ packages:'@types/[email protected]':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.11picocolors: 1.1.1resolve-from: 5.0.0- semver: 7.7.4+ semver: 7.8.5spawndamnit: 3.0.1term-size: 2.2.1transitivePeerDependencies:@@ -8642,6 +8649,8 @@ snapshots:dependencies:undici-types: 7.16.0+ '@types/[email protected]': {}+'@vitest/[email protected]([email protected])':dependencies:'@bcoe/v8-coverage': 1.0.2@@ -9908,8 +9917,6 @@ snapshots:dependencies:xmlchars: 2.2.0- [email protected]: {}-