@oalo-ai/cli 0.1.0 → 0.2.0

package/src/migrate/plan.js

@@ -0,0 +1,478 @@
+import { parseToml } from "./toml.js";
+import { parseYaml } from "./yaml.js";
+import { parseDotenv } from "../envfile.js";
+
+/**
+ * `oalo migrate`'s plan: what an app on another platform becomes on Oalo,
+ * worked out from its files and what that platform's CLI reports. Pure: the
+ * command reads the files and runs the CLIs, this decides.
+ *
+ *   input.files  { procfile, appJson, flyToml, railwayJson, railwayToml, renderYaml,
+ *                  dockerfile, aptfile, packageJson, lockfile, oaloAppJson }  (text, or true/false)
+ *   input.remote { vars: {NAME: value} | null, secretNames: [..] | null, dynos: [{type, size}] | null, notes: [..] }
+ *   input.envFile  text of a .env file to add, or null
+ *   input.fromApp  the app or service on that platform, when named
+ *
+ * Returns { platform, label, procfile, manifest, vars, warnings } where vars
+ * carry values (for the command to send) and nothing else does.
+ */
+
+export const PLATFORMS = {
+  heroku: { label: "Heroku", cli: "heroku", prefixes: ["HEROKU_"] },
+  railway: { label: "Railway", cli: "railway", prefixes: ["RAILWAY_", "RAILPACK_", "NIXPACKS_"] },
+  render: { label: "Render", cli: null, prefixes: ["RENDER_"], names: ["IS_PULL_REQUEST", "NODE_VERSION", "PYTHON_VERSION", "RUBY_VERSION", "GO_VERSION", "BUN_VERSION", "ELIXIR_VERSION", "ERLANG_VERSION", "POETRY_VERSION", "UV_VERSION"] },
+  fly: { label: "Fly.io", cli: "fly", prefixes: ["FLY_"], names: ["PRIMARY_REGION"] },
+  primcloud: { label: "Primcloud", cli: null, prefixes: ["PRIMCLOUD_"] },
+};
+
+// What Oalo sets itself (the Base refuses these names), as in `oalo env`.
+const RESERVED = new Set(
+  `PORT DATABASE_URL APP_SCHEMA APP_SLUG OALO_ENV EXPO_PUBLIC_OALO_ENV VITE_PORT CONTAINER_HOST VITE_CONTAINER_HOST
+   EXPO_PUBLIC_CONTAINER_HOST BROWSER MIX_ENV MIX_HOME HEX_HOME PATH HOME LANG LANGUAGE LC_ALL LC_CTYPE TZ TMPDIR
+   FLUTTER_HOME FLUTTER_ROOT PUB_CACHE HOSTNAME`.split(/\s+/),
+);
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const PROC_RE = /^[A-Za-z0-9_-]+$/;
+const MAX_VALUE = 32768;
+const MAX_VARS = 200;
+
+// Oalo's sizes, smallest first, by memory.
+export const SIZES = [
+  { size: "tiny", mb: 512 },
+  { size: "small", mb: 1024 },
+  { size: "medium", mb: 2048 },
+  { size: "large", mb: 4096 },
+];
+
+/** The smallest Oalo size with at least `mb` of memory, and whether even large is short. */
+export function sizeFor(mb) {
+  if (!(mb > 0)) return null;
+  const fit = SIZES.find((s) => s.mb >= mb);
+  return fit ? { size: fit.size, over: false } : { size: "large", over: true };
+}
+
+const HEROKU_MB = {
+  free: 512, hobby: 512, eco: 512, basic: 512, "standard-1x": 512, "1x": 512, "standard-2x": 1024, "2x": 1024,
+  "performance-m": 2560, "performance-l": 14336, "performance-l-ram": 30720, "performance-xl": 63488, "performance-2xl": 129024,
+  "private-s": 1024, "private-m": 2560, "private-l": 14336, "shield-s": 1024, "shield-m": 2560, "shield-l": 14336,
+};
+const RENDER_MB = { free: 512, starter: 512, standard: 2048, pro: 4096, "pro plus": 8192, "pro max": 16384, "pro ultra": 32768 };
+const FLY_MB = {
+  "shared-cpu-1x": 256, "shared-cpu-2x": 512, "shared-cpu-4x": 1024, "shared-cpu-8x": 2048,
+  "performance-1x": 2048, "performance-2x": 4096, "performance-4x": 8192, "performance-8x": 16384, "performance-16x": 32768,
+};
+
+export function buildPlan(platform, input) {
+  const def = PLATFORMS[platform];
+  if (!def) throw new Error(`unknown platform ${platform}`);
+  const files = input.files || {};
+  const remote = input.remote || {};
+  const warnings = [...(remote.notes || [])];
+  const vars = new Map(); // name -> { value, from }
+  const missing = []; // { name, why }
+
+  let read;
+  if (platform === "heroku") read = fromHeroku(files, remote, warnings);
+  else if (platform === "railway") read = fromRailway(files, warnings);
+  else if (platform === "render") read = fromRender(files, input.fromApp, warnings, missing, vars);
+  else if (platform === "fly") read = fromFly(files, warnings, vars, remote, missing);
+  else read = fromPrimcloud(files, warnings);
+
+  if (remote.vars) for (const [name, value] of Object.entries(remote.vars)) vars.set(name, { value: value == null ? "" : String(value), from: def.label });
+  if (input.envFile != null) {
+    for (const { name, value } of parseDotenv(input.envFile)) vars.set(name, { value, from: "--env-file" });
+  }
+
+  const procfile = procfilePlan(files, read.processes, read.release, warnings);
+  const manifest = manifestPlan(files, procfile, read.sizes || {}, read.health, warnings);
+  const varPlan = filterVars(def, vars, missing, warnings);
+  commonChecks(files, warnings);
+
+  return { platform, label: def.label, procfile, manifest, vars: varPlan, warnings: dedupe(warnings) };
+}
+
+// ── per platform ──────────────────────────────────────────────────────
+
+function fromHeroku(files, remote, warnings) {
+  const sizes = {};
+  let fromSize = null;
+  let appJson = null;
+  if (files.appJson) {
+    try {
+      appJson = JSON.parse(files.appJson);
+    } catch {
+      warnings.push("app.json isn't valid JSON, so its formation sizes were skipped.");
+    }
+  }
+  const list = remote.dynos?.length
+    ? remote.dynos.map((d) => ({ type: d.type, size: d.size }))
+    : Object.entries(appJson?.formation || {}).map(([type, f]) => ({ type, size: f?.size }));
+  for (const { type, size } of list) {
+    if (!type || !size || sizes[type]) continue;
+    const mb = HEROKU_MB[String(size).toLowerCase()];
+    if (mb) sizes[type] = { mb, from: `${size} dyno` };
+    else fromSize = size;
+  }
+  if (fromSize) warnings.push(`Dyno size ${fromSize} isn't one oalo migrate knows: set that process's size in .oalo/app.json by hand.`);
+  if (files.aptfile) warnings.push("Aptfile: Oalo's buildpacks don't read it. Add a Dockerfile that installs those packages.");
+  warnings.push("Heroku Scheduler jobs can't be read from here. Add a `scheduler:` Procfile line that runs your language's cron library, or a workflow on a schedule.");
+  return { processes: null, release: null, sizes, health: null };
+}
+
+function fromRailway(files, warnings) {
+  let cfg = null;
+  if (files.railwayJson) cfg = parseOrWarn(() => JSON.parse(files.railwayJson), "railway.json", warnings);
+  else if (files.railwayToml) cfg = parseOrWarn(() => parseToml(files.railwayToml), "railway.toml", warnings);
+  const deploy = cfg?.deploy || {};
+  const build = cfg?.build || {};
+  const processes = [];
+  let release = null;
+
+  if (deploy.cronSchedule) {
+    warnings.push(`This service runs on a schedule (${deploy.cronSchedule}), not all the time. On Oalo that's a \`scheduler:\` Procfile line running your language's cron library, or a workflow on a schedule. No web line was written for it.`);
+  } else if (deploy.startCommand) {
+    processes.push(["web", String(deploy.startCommand)]);
+  }
+  if (deploy.preDeployCommand) release = joinCommands(deploy.preDeployCommand);
+  if (deploy.numReplicas > 1) warnings.push(`Railway ran ${deploy.numReplicas} replicas. Each Oalo process runs as one copy.`);
+  if (build.buildCommand) warnings.push(`Railway's build command (${build.buildCommand}) doesn't carry over: put it in package.json's \`build\` script, or a Dockerfile.`);
+  if (build.dockerfilePath && !/^\.?\/?Dockerfile$/.test(build.dockerfilePath)) {
+    warnings.push(`Railway built from ${build.dockerfilePath}. Oalo builds from ./Dockerfile at the repo's root.`);
+  }
+  if (!cfg) warnings.push("No railway.json or railway.toml here, so start and pre-deploy commands come from the Railway dashboard: copy them into a Procfile (`web:` and `release:`).");
+  warnings.push("A service built from another repo becomes its own Oalo app: run oalo migrate in that repo too.");
+  warnings.push("Volumes don't come along: an Oalo process can write only to /tmp, which is emptied when it restarts.");
+  return { processes, release, sizes: {}, health: deploy.healthcheckPath || null };
+}
+
+function fromRender(files, fromApp, warnings, missing, vars) {
+  if (!files.renderYaml) {
+    warnings.push("No render.yaml here, so start and pre-deploy commands come from each service's Settings page: copy them into a Procfile (`web:`, `worker:` and `release:`), and the variables into a file for --env-file.");
+    return { processes: null, release: null, sizes: {}, health: null };
+  }
+  const doc = parseOrWarn(() => parseYaml(files.renderYaml), "render.yaml", warnings);
+  if (!doc) return { processes: null, release: null, sizes: {}, health: null };
+
+  const groups = new Map((doc.envVarGroups || []).map((g) => [g?.name, g?.envVars || []]));
+  let services = (doc.services || []).filter((s) => s && typeof s === "object");
+  if (fromApp) {
+    const named = services.filter((s) => s.name === fromApp);
+    if (!named.length) warnings.push(`render.yaml has no service named ${fromApp}; all its services were read.`);
+    else services = named;
+  }
+
+  const processes = [];
+  const sizes = {};
+  let release = null;
+  let health = null;
+  let webDone = false;
+
+  for (const s of services) {
+    const type = s.type;
+    const runtime = s.runtime || s.env;
+    const name = s.name || type;
+    const cmd = s.startCommand || s.dockerCommand || null;
+
+    if (type === "web" && runtime === "static") {
+      warnings.push(`${name} is a static site: on Oalo it's its own web app (oalo deploy --new in its folder), not a process.`);
+      continue;
+    }
+    if (type === "static") {
+      warnings.push(`${name} is a static site: on Oalo it's its own web app (oalo deploy --new in its folder), not a process.`);
+      continue;
+    }
+    if (type === "cron") {
+      warnings.push(`${name} is a cron job (${s.schedule || "on a schedule"}: ${cmd || "its command"}). On Oalo that's a \`scheduler:\` Procfile line running your language's cron library, or a workflow on a schedule.`);
+      continue;
+    }
+    if (type === "pserv") {
+      warnings.push(`${name} is a private service: on Oalo it's its own app, reached at its public address.`);
+      continue;
+    }
+    if (type === "keyvalue" || type === "redis") {
+      warnings.push(`${name} is Render Key Value: keep it, and set its external URL as REDIS_URL (its access settings must let your Base in).`);
+      continue;
+    }
+
+    let proc;
+    if (type === "web") {
+      if (webDone) {
+        warnings.push(`${name} is a second web service: on Oalo it's its own app.`);
+        continue;
+      }
+      proc = "web";
+      webDone = true;
+      if (s.preDeployCommand) release = joinCommands(s.preDeployCommand);
+      if (s.healthCheckPath) health = s.healthCheckPath;
+    } else if (type === "worker" || type === "bworker") {
+      proc = procName(name);
+    } else {
+      warnings.push(`${name} has type ${type}, which oalo migrate doesn't map: add it to the Procfile by hand.`);
+      continue;
+    }
+
+    if (cmd) processes.push([proc, String(cmd).trim()]);
+    else if (runtime !== "docker") warnings.push(`${name} has no startCommand in render.yaml: add its \`${proc}:\` line by hand, from its Settings page.`);
+    if (s.plan && RENDER_MB[String(s.plan).toLowerCase()]) sizes[proc] = { mb: RENDER_MB[String(s.plan).toLowerCase()], from: `Render ${s.plan}` };
+    if (s.buildCommand) warnings.push(`${name}'s build command (${s.buildCommand}) doesn't carry over: Oalo builds with buildpacks or your Dockerfile. Put extra steps in package.json's \`build\` script, or the Dockerfile.`);
+    if (s.disk) warnings.push(`${name} has a persistent disk (${s.disk.mountPath || s.disk.name || "mounted"}): it doesn't come along. A process can write only to /tmp, which is emptied when it restarts.`);
+    if (s.numInstances > 1 || s.scaling) warnings.push(`${name} ran more than one instance. Each Oalo process runs as one copy.`);
+    if (s.rootDir) warnings.push(`${name} builds from ${s.rootDir}. Oalo reads the repo's root: run oalo migrate and oalo deploy --new from that folder's own repo, or add a root Dockerfile.`);
+
+    for (const v of s.envVars || []) renderVar(v, groups, vars, missing);
+  }
+
+  for (const db of doc.databases || []) {
+    if (db?.name) warnings.push(`Render Postgres ${db.name}: keep it and set its external URL as EXTERNAL_DATABASE_URL, or copy its data in with oalo db restore.`);
+  }
+  return { processes, release, sizes, health };
+}
+
+function renderVar(v, groups, vars, missing) {
+  if (!v || typeof v !== "object") return;
+  if (v.fromGroup) {
+    for (const g of groups.get(v.fromGroup) || []) renderVar(g, groups, vars, missing);
+    if (!groups.has(v.fromGroup)) missing.push({ name: `(group ${v.fromGroup})`, why: "an environment group render.yaml doesn't define: copy its variables from the dashboard" });
+    return;
+  }
+  if (!v.key) return;
+  if (v.value !== undefined && v.value !== null) vars.set(v.key, { value: String(v.value), from: "render.yaml" });
+  else if (v.fromDatabase) missing.push({ name: v.key, why: "Render fills it from a database: use that database's external URL" });
+  else if (v.fromService) missing.push({ name: v.key, why: "Render fills it from another service: use that service's public address or value" });
+  else if (v.generateValue) missing.push({ name: v.key, why: "Render generated it: copy it from the Environment page" });
+  else missing.push({ name: v.key, why: "set in the dashboard (sync: false): copy it from the Environment page" });
+}
+
+function fromFly(files, warnings, vars, remote, missing) {
+  if (!files.flyToml) {
+    warnings.push("No fly.toml here: run oalo migrate fly in the folder that has it.");
+    return { processes: null, release: null, sizes: {}, health: null };
+  }
+  const cfg = parseOrWarn(() => parseToml(files.flyToml), "fly.toml", warnings);
+  if (!cfg) return { processes: null, release: null, sizes: {}, health: null };
+
+  const http = cfg.http_service || null;
+  const webGroup = (http?.processes && http.processes[0]) || "app";
+  const processes = [];
+  const sizes = {};
+  for (const [group, cmd] of Object.entries(cfg.processes || {})) {
+    processes.push([group === webGroup ? "web" : procName(group), String(cmd)]);
+  }
+  if (!Object.keys(cfg.processes || {}).length && !files.dockerfile && !files.procfile) {
+    warnings.push("fly.toml names no [processes] and there's no Dockerfile or Procfile: add a Procfile with a `web:` line.");
+  }
+  const release = cfg.deploy?.release_command ? String(cfg.deploy.release_command) : null;
+
+  const port = http?.internal_port || cfg.services?.[0]?.internal_port;
+  if (port) warnings.push(`Fly sent traffic to port ${port}. On Oalo, web must listen on $PORT (0.0.0.0): check the server reads it.`);
+
+  const health = flyHealth(cfg);
+
+  for (const vm of [].concat(cfg.vm || [])) {
+    const mb = flyMemory(vm);
+    if (!mb) continue;
+    const groups = vm.processes?.length ? vm.processes : Object.keys(cfg.processes || {}).length ? Object.keys(cfg.processes) : [webGroup];
+    for (const g of groups) {
+      const proc = g === webGroup ? "web" : procName(g);
+      if (!sizes[proc]) sizes[proc] = { mb, from: `Fly VM, ${mb} MB` };
+    }
+  }
+
+  for (const [name, value] of Object.entries(cfg.env || {})) vars.set(name, { value: String(value), from: "fly.toml [env]" });
+  for (const name of remote.secretNames || []) {
+    if (!vars.has(name)) missing.push({ name, why: "a Fly secret: Fly never shows its value, so get it from where it came from" });
+  }
+
+  if (cfg.mounts) warnings.push("fly.toml mounts a volume: it doesn't come along. A process can write only to /tmp, which is emptied when it restarts.");
+  if (http?.auto_stop_machines) warnings.push("Machines that stopped when idle become processes that are always on.");
+  if (files.dockerfile && !/^\s*USER\s+/im.test(files.dockerfile)) {
+    warnings.push("The Dockerfile has no USER line. On Oalo the image runs as uid 1000 with a read-only filesystem (only /tmp is writable): make sure nothing needs root or writes elsewhere.");
+  }
+  return { processes, release, sizes, health };
+}
+
+function flyHealth(cfg) {
+  const checks = [];
+  for (const c of [].concat(cfg.http_service?.checks || [])) checks.push(c);
+  for (const s of [].concat(cfg.services || [])) for (const c of [].concat(s.http_checks || [])) checks.push(c);
+  for (const c of Object.values(cfg.checks || {})) if (c?.type === "http") checks.push(c);
+  const path = checks.find((c) => typeof c?.path === "string")?.path;
+  return path || null;
+}
+
+function flyMemory(vm) {
+  if (typeof vm.memory_mb === "number") return vm.memory_mb;
+  const m = vm.memory;
+  if (typeof m === "number") return m;
+  if (typeof m === "string") {
+    const x = m.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(gb|g|mb|m)?$/);
+    if (x) return Math.round(Number(x[1]) * (x[2] && x[2].startsWith("g") ? 1024 : 1));
+  }
+  if (vm.size && FLY_MB[vm.size]) return FLY_MB[vm.size];
+  return null;
+}
+
+function fromPrimcloud(files, warnings) {
+  warnings.push("Primcloud's formation sizes can't be read from here: set each process's size in .oalo/app.json (Standard 1x is tiny, 2x small, 4x or Performance 1x medium, Performance 2x large).");
+  warnings.push("Secrets: reveal them in Primcloud's Settings, Secrets, put them in a .env file and pass it with --env-file.");
+  if (!files.procfile) warnings.push("No Procfile here: Primcloud apps usually have one. Add it at the repo's root.");
+  return { processes: null, release: null, sizes: {}, health: null };
+}
+
+// ── Procfile and .oalo/app.json ───────────────────────────────────────
+
+function procfilePlan(files, processes, release, warnings) {
+  const lines = [];
+  if (release) lines.push(["release", release]);
+  for (const p of processes || []) lines.push(p);
+
+  if (files.procfile) {
+    const have = parseProcfile(files.procfile);
+    const missingLines = lines.filter(([n]) => !have.some(([h]) => h === n));
+    if (missingLines.length) {
+      warnings.push(`Your Procfile is kept as it is. From the old config it would also have: ${missingLines.map(([n, c]) => `\`${n}: ${c}\``).join(", ")}.`);
+    }
+    return { action: "keep", lines: have };
+  }
+  if (!lines.length) return { action: "none", lines: [] };
+  return { action: "write", lines, text: lines.map(([n, c]) => `${n}: ${c}`).join("\n") + "\n" };
+}
+
+export function parseProcfile(text) {
+  const out = [];
+  for (const line of String(text).split(/\r?\n/)) {
+    if (line.trim().startsWith("#")) continue;
+    const m = line.match(/^\s*([A-Za-z0-9_-]+)\s*:\s*(.+?)\s*$/);
+    if (m) out.push([m[1], m[2]]);
+  }
+  return out;
+}
+
+function manifestPlan(files, procfile, sizesIn, health, warnings) {
+  let existing = null;
+  if (files.oaloAppJson) {
+    try {
+      existing = JSON.parse(files.oaloAppJson);
+    } catch {
+      warnings.push(".oalo/app.json isn't valid JSON, so it's left alone. Fix it before you deploy.");
+      return { action: "none", sizes: {}, health: null };
+    }
+  }
+
+  const procs = new Set(procfile.lines.map(([n]) => n).filter((n) => n !== "release"));
+  const sizes = {};
+  for (const [proc, s] of Object.entries(sizesIn)) {
+    if (procs.size && !procs.has(proc)) continue;
+    const fit = sizeFor(s.mb);
+    if (!fit) continue;
+    sizes[proc] = { size: fit.size, from: s.from };
+    if (fit.over) warnings.push(`${proc} had ${s.mb} MB (${s.from}). The largest Oalo size is large (2 CPUs, 4 GB): check it fits before you go live.`);
+  }
+
+  const next = { ...(existing || {}) };
+  const added = { sizes: {}, health: null };
+  for (const [proc, s] of Object.entries(sizes)) {
+    if (next.sizes?.[proc]) continue;
+    next.sizes = { ...(next.sizes || {}), [proc]: s.size };
+    added.sizes[proc] = s;
+  }
+  if (health && !next.health && /^\/(?!\/)[^\s]*$/.test(health) && !health.includes("..") && health.length <= 200) {
+    next.health = health;
+    added.health = health;
+  }
+
+  const changed = Object.keys(added.sizes).length || added.health;
+  if (!changed) return { action: existing ? "keep" : "none", sizes: {}, health: null };
+  return { action: existing ? "merge" : "write", sizes: added.sizes, health: added.health, text: JSON.stringify(next, null, 2) + "\n" };
+}
+
+// ── variables ─────────────────────────────────────────────────────────
+
+function filterVars(def, vars, missing, warnings) {
+  const set = [];
+  const dropped = [];
+  const renamed = [];
+  const hasExternal = vars.has("EXTERNAL_DATABASE_URL");
+
+  for (const [name, { value, from }] of vars) {
+    if (name === "DATABASE_URL") {
+      if (hasExternal) dropped.push({ name, why: "EXTERNAL_DATABASE_URL is already there" });
+      else {
+        renamed.push({ from: name, to: "EXTERNAL_DATABASE_URL" });
+        set.push({ name: "EXTERNAL_DATABASE_URL", value, from });
+      }
+      continue;
+    }
+    if (RESERVED.has(name) || name.startsWith("OALO_")) {
+      dropped.push({ name, why: "Oalo sets it" });
+      continue;
+    }
+    if (def.prefixes.some((p) => name.startsWith(p)) || (def.names || []).includes(name)) {
+      dropped.push({ name, why: `${def.label}'s own` });
+      continue;
+    }
+    if (!NAME_RE.test(name)) {
+      dropped.push({ name, why: "not a name Oalo takes (letters, digits and _)" });
+      continue;
+    }
+    if (Buffer.byteLength(value, "utf8") > MAX_VALUE) {
+      dropped.push({ name, why: "over 32 KB" });
+      continue;
+    }
+    set.push({ name, value, from });
+  }
+
+  for (const v of set) {
+    if (/\$\{\{/.test(v.value)) warnings.push(`${v.name} holds a \`\${{ ... }}\` reference, which only resolves on Railway: put its plain value in --env-file.`);
+    const host = privateHost(v.value);
+    if (host) warnings.push(`${v.name} points at ${host}, which your Base can't reach: use that service's public address.`);
+  }
+  if (set.length > MAX_VARS) warnings.push(`That's ${set.length} variables; an app takes up to ${MAX_VARS}.`);
+
+  const setNames = new Set(set.map((v) => v.name));
+  return {
+    set: set.sort((a, b) => a.name.localeCompare(b.name)),
+    renamed,
+    dropped: dropped.sort((a, b) => a.name.localeCompare(b.name)),
+    missing: missing
+      .map((m) => (m.name === "DATABASE_URL" ? { name: "EXTERNAL_DATABASE_URL", why: `${m.why} (DATABASE_URL on Oalo is the Base's own Postgres)` } : m))
+      .filter((m) => !setNames.has(m.name)),
+  };
+}
+
+function privateHost(value) {
+  const m = String(value).match(/(?:@|\/\/|^)([A-Za-z0-9.-]+\.(?:railway\.internal|flycast|internal)|localhost|127\.0\.0\.1)(?=[:/]|$)/);
+  return m ? m[1] : null;
+}
+
+// ── checks every platform gets ────────────────────────────────────────
+
+function commonChecks(files, warnings) {
+  if (files.packageJson && !files.lockfile && !files.dockerfile) {
+    warnings.push("package.json has no lockfile committed next to it (package-lock.json, yarn.lock, pnpm-lock.yaml or bun.lock): the build needs one.");
+  }
+}
+
+// ── helpers ───────────────────────────────────────────────────────────
+
+function joinCommands(c) {
+  return Array.isArray(c) ? c.map(String).join(" && ") : String(c);
+}
+
+function procName(name) {
+  const n = String(name).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  return n && PROC_RE.test(n) && n !== "web" && n !== "release" ? n : "worker";
+}
+
+function parseOrWarn(fn, file, warnings) {
+  try {
+    return fn();
+  } catch (e) {
+    warnings.push(`${file} couldn't be read (${e.message}): copy its commands by hand.`);
+    return null;
+  }
+}
+
+function dedupe(list) {
+  return [...new Set(list)];
+}