@faable/faable 1.7.0 → 1.9.0

package/dist/commands/deploy/buildpacks/Buildpack.js

@@ -0,0 +1,11 @@
+/** One-line summary logged before build so the decision is reconstructible. */
+const plan_summary = (plan) => JSON.stringify({
+    buildpack: plan.buildpack,
+    type: plan.type,
+    runtime: `${plan.runtime.name}${plan.runtime.version ? `-${plan.runtime.version}` : ""}`,
+    start: plan.start_command,
+    ...(plan.install_command ? { install: plan.install_command } : {}),
+    ...(plan.build_script ? { build_script: plan.build_script } : {}),
+});
+
+export { plan_summary };

package/dist/commands/deploy/buildpacks/docker/index.js

@@ -0,0 +1,42 @@
+import fs from 'fs-extra';
+import path__default from 'path';
+import { cmd } from '../../../../lib/cmd.js';
+import { log } from '../../../../log.js';
+import { has_any_of_files } from '../shared/has_any_of_files.js';
+
+// A package.json with a next dependency beside the Dockerfile means this is a
+// Next.js app shipped with a custom image: emit type "next" so the backend
+// provisions the build-cache PVC (runtime_strategy). Reachable via the
+// --buildpack override, since the node buildpack claims package.json first.
+const detect_next = (workdir) => {
+    try {
+        const pkg = fs.readJSONSync(path__default.join(workdir, "package.json"));
+        return Boolean(pkg?.dependencies?.next || pkg?.devDependencies?.next);
+    }
+    catch {
+        return false;
+    }
+};
+const docker_buildpack = {
+    name: "docker",
+    detect_files: ["Dockerfile"],
+    async detect(ctx) {
+        if (!has_any_of_files(this.detect_files, ctx.workdir))
+            return null;
+        const type = detect_next(ctx.workdir) ? "next" : "node";
+        return {
+            buildpack: "docker",
+            runtime: { name: "docker" },
+            type,
+            // The user's image defines its own CMD/ENTRYPOINT.
+            start_command: null,
+        };
+    },
+    async build(ctx) {
+        log.info(`📦 Building with the project's own Dockerfile`);
+        const timeout = 10 * 60 * 1000; // 10 minute timeout
+        await cmd(`docker build --platform linux/amd64 -t ${ctx.app.id} ${ctx.workdir} -f ${path__default.join(ctx.workdir, "Dockerfile")}`, { timeout, enableOutput: true });
+    },
+};
+
+export { docker_buildpack };

package/dist/commands/deploy/{node-pipeline → buildpacks/node}/analyze_package.js

@@ -1,6 +1,6 @@
 import fs from 'fs-extra';
 import path__default from 'path';
-import { log } from '../../../log.js';
+import { log } from '../../../../log.js';
 import { detect_framework } from './frameworks.js';
 
 const analyze_package = async (params) => {

package/dist/commands/deploy/buildpacks/node/build_project.js

@@ -0,0 +1,21 @@
+import { log } from '../../../../log.js';
+import { cmd } from '../../../../lib/cmd.js';
+
+const build_project = async (args) => {
+    const { command, cwd } = args;
+    if (command) {
+        log.info(`⚙️ Building project [${command}]...`);
+        const timeout = 1000 * 60 * 30; // 30 minute timeout
+        await cmd(command, {
+            timeout,
+            cwd,
+            enableOutput: true,
+            ...(args?.env ? { env: args?.env } : {}),
+        });
+    }
+    else {
+        log.info(`⚡️ No build step`);
+    }
+};
+
+export { build_project };

package/dist/commands/deploy/buildpacks/node/ensure_dependencies.js

@@ -0,0 +1,76 @@
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { log } from '../../../../log.js';
+import { cmd } from '../../../../lib/cmd.js';
+
+// Installing can be slow on cold CI runners (no npm cache).
+const INSTALL_TIMEOUT = 15 * 60 * 1000; // 15 minute timeout
+const defaultRun = (command, cwd) => cmd(command, { cwd, timeout: INSTALL_TIMEOUT, enableOutput: true });
+const defaultHasTool = async (name) => {
+    try {
+        await cmd(`command -v ${name}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Dependencies may live in the workdir or be hoisted to a parent directory
+ * (monorepos). Walk upwards checking each level, stopping at the repo root
+ * (first directory containing `.git`) or the filesystem root.
+ */
+const has_node_modules = (workdir, exists) => {
+    let dir = workdir;
+    while (true) {
+        if (exists(join(dir, "node_modules")))
+            return true;
+        if (exists(join(dir, ".git")))
+            return false;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+};
+/**
+ * Install dependencies when `node_modules` is missing, so `faable deploy`
+ * works without a prior `npm ci` step — the generated GitHub Actions workflow
+ * is language-agnostic and no longer installs anything itself. The build
+ * (`npm run build`) and the image (`COPY . .` ships node_modules) both need
+ * dependencies present on the host.
+ *
+ * The install command honors the project's lockfile; yarn/pnpm fall back to
+ * `npm install` when the tool is missing, which may resolve slightly
+ * different versions.
+ */
+const ensure_dependencies = async (workdir, deps = {}) => {
+    const { run = defaultRun, hasTool = defaultHasTool, exists = existsSync } = deps;
+    if (has_node_modules(workdir, exists))
+        return;
+    const has = (file) => exists(join(workdir, file));
+    let install = "npm install --no-audit --no-fund";
+    if (has("package-lock.json") || has("npm-shrinkwrap.json")) {
+        install = "npm ci";
+    }
+    else if (has("yarn.lock")) {
+        if (await hasTool("yarn")) {
+            install = "yarn install --frozen-lockfile";
+        }
+        else {
+            log.warn("yarn.lock found but yarn is not installed — using npm install");
+        }
+    }
+    else if (has("pnpm-lock.yaml")) {
+        if (await hasTool("pnpm")) {
+            install = "pnpm install --frozen-lockfile";
+        }
+        else {
+            log.warn("pnpm-lock.yaml found but pnpm is not installed — using npm install");
+        }
+    }
+    log.info(`📦 node_modules missing — installing dependencies [${install}]`);
+    await run(install, workdir);
+};
+
+export { ensure_dependencies };

package/dist/commands/deploy/{node-pipeline → buildpacks/node}/frameworks.js

@@ -1,7 +1,7 @@
 import fs from 'fs-extra';
 import path__default from 'path';
 import * as R from 'ramda';
-import { log } from '../../../log.js';
+import { log } from '../../../../log.js';
 
 const has_dep = (pkg, name) => Boolean(R.view(R.lensPath(["dependencies", name]), pkg) ||
     R.view(R.lensPath(["devDependencies", name]), pkg));
@@ -39,13 +39,13 @@ const FRAMEWORKS = [
         type: "astro",
         deps: ["astro"],
         outputDir: "dist",
-        serveCommand: (dir) => `npx astro preview --host 0.0.0.0 --port $PORT`,
+        serveCommand: (_dir) => `npx astro preview --host 0.0.0.0 --port $PORT`,
     },
     {
         type: "gatsby",
         deps: ["gatsby"],
         outputDir: "public",
-        serveCommand: (dir) => `npx gatsby serve --host 0.0.0.0 --port $PORT`,
+        serveCommand: (_dir) => `npx gatsby serve --host 0.0.0.0 --port $PORT`,
     },
     {
         type: "cra",
@@ -72,7 +72,7 @@ const FRAMEWORKS = [
         type: "vite",
         deps: ["vite"],
         outputDir: "dist",
-        serveCommand: (dir) => `npx vite preview --host 0.0.0.0 --port $PORT`,
+        serveCommand: (_dir) => `npx vite preview --host 0.0.0.0 --port $PORT`,
     },
 ];
 /**

package/dist/commands/deploy/buildpacks/node/index.js

@@ -0,0 +1,65 @@
+import * as R from 'ramda';
+import { log } from '../../../../log.js';
+import { render_dockerfile, build_image } from '../shared/docker_image.js';
+import { has_any_of_files } from '../shared/has_any_of_files.js';
+import { analyze_package } from './analyze_package.js';
+import { build_project } from './build_project.js';
+import { ensure_dependencies } from './ensure_dependencies.js';
+import { inject_serve } from './inject_serve.js';
+import { resolve_node_version } from './node_version.js';
+
+const BANNER = `NODE_VERSION=$(node --version)
+NPM_VERSION=$(npm --version)
+YARN_VERSION=$(yarn --version)
+
+echo "Faable Cloud · [node $NODE_VERSION] [npm $NPM_VERSION] [yarn $YARN_VERSION]"`;
+const node_buildpack = {
+    name: "node",
+    detect_files: ["package.json"],
+    async detect(ctx) {
+        if (!has_any_of_files(this.detect_files, ctx.workdir))
+            return null;
+        const version = await resolve_node_version(ctx.workdir);
+        const { build_script, type, start_command, inject_serve } = await analyze_package({ workdir: ctx.workdir });
+        // Precedence: explicit faable.json startCommand > framework-detected
+        // command (e.g. serving a static SPA) > default `npm run start`.
+        const start = ctx.config.startCommand ?? start_command ?? "npm run start";
+        return {
+            buildpack: "node",
+            runtime: { name: "node", version },
+            type,
+            start_command: start,
+            build_script,
+            inject_serve,
+            from: `node:${version}`,
+        };
+    },
+    async build(ctx, plan) {
+        const env = R.fromPairs(ctx.env_vars.map((e) => [e.name, e.value]));
+        log.info(`Building with env variables ${Object.keys(env).join(",")}`);
+        // The workflow no longer runs `npm ci` — install here when needed, before
+        // the build and before `COPY . .` packages node_modules into the image.
+        await ensure_dependencies(ctx.workdir);
+        // Host build step: npm script from the plan, else faable.json buildCommand.
+        const build_command = plan.build_script
+            ? `npm run ${plan.build_script}`
+            : ctx.config.buildCommand;
+        await build_project({ command: build_command, env, cwd: ctx.workdir });
+        // Frameworks without a bundled static server (CRA/Vue/Angular) need
+        // `serve` installed into node_modules before packaging.
+        if (plan.inject_serve) {
+            await inject_serve(ctx.workdir);
+        }
+        log.info(`⚙️ Start command: ${plan.start_command}`);
+        log.info(`Using docker image ${plan.from}-slim`);
+        const dockerfile = render_dockerfile({
+            from: plan.from,
+            env: { NODE_ENV: "production" },
+            banner: BANNER,
+            start_command: plan.start_command,
+        });
+        await build_image({ app: ctx.app, workdir: ctx.workdir, dockerfile });
+    },
+};
+
+export { node_buildpack };

package/dist/commands/deploy/{node-pipeline → buildpacks/node}/inject_serve.js

@@ -1,5 +1,5 @@
-import { log } from '../../../log.js';
-import { cmd } from '../../../lib/cmd.js';
+import { log } from '../../../../log.js';
+import { cmd } from '../../../../lib/cmd.js';
 
 // Pinned for reproducible builds. `serve` is the standalone static server used
 // for frameworks without a bundled preview tool (CRA, Vue, Angular).

package/dist/commands/deploy/{runtime-detect/strategies/nodejs.js → buildpacks/node/node_version.js}

@@ -9,19 +9,17 @@ const getCurrentNodeVersion = async () => {
     return version;
 };
 /**
- * Strategy to detect app name from package.json
- * @param api
- * @param workdir
- * @returns
+ * Resolve the Node version for the base image: `engines.node` from
+ * package.json (resolved to a concrete release via `npm view`), else the
+ * version running the deploy. Also validates the package has a `name`
+ * (required since the beginning; kept for compatibility).
  */
-const strategy_nodejs = async (workdir) => {
+const resolve_node_version = async (workdir) => {
     const packageJSONFile = path__default.join(workdir, "package.json");
-    // Check we have a valid name
     const { name, engines } = fs.readJSONSync(packageJSONFile);
     if (!name) {
         throw new Error("Missing name in package.json");
     }
-    // Use engines.node if found
     let runtime_version = await getCurrentNodeVersion();
     if (engines?.node) {
         try {
@@ -37,13 +35,7 @@ const strategy_nodejs = async (workdir) => {
     else {
         log.info(`Node version ${runtime_version}`);
     }
-    return {
-        app_name: name,
-        runtime: {
-            name: "node",
-            version: runtime_version,
-        },
-    };
+    return runtime_version;
 };
 
-export { strategy_nodejs };
+export { resolve_node_version };

package/dist/commands/deploy/buildpacks/python/index.js

@@ -0,0 +1,76 @@
+import { log } from '../../../../log.js';
+import { render_dockerfile, build_image } from '../shared/docker_image.js';
+import { has_any_of_files } from '../shared/has_any_of_files.js';
+import { pipfile_provider } from './providers/pipfile.js';
+import { pyproject_provider } from './providers/pyproject.js';
+import { requirements_provider } from './providers/requirements.js';
+import { resolve_python_version } from './python_version.js';
+import { read_dependencies_text, resolve_start, with_server_injection } from './resolve_start.js';
+
+const BANNER = `PYTHON_VERSION=$(python --version 2>&1)
+PIP_VERSION=$(pip --version 2>&1)
+
+echo "Faable Cloud · [$PYTHON_VERSION] [$PIP_VERSION]"`;
+// Evaluated in order: the first provider whose manifest exists supplies the
+// install command. Classic manifests come before platform-specific ones.
+const PROVIDERS = [
+    requirements_provider,
+    pyproject_provider,
+    pipfile_provider,
+];
+const detect_with_provider = (ctx, provider) => {
+    const resolved = provider.resolve(ctx.workdir);
+    // Framework detection blob: all classic manifests plus whatever the winning
+    // provider contributes (e.g. cerebrium pip package names).
+    const deps = [read_dependencies_text(ctx.workdir), resolved.deps_text ?? ""]
+        .join("\n")
+        .toLowerCase();
+    const { start_command, server } = resolve_start(ctx.workdir, deps, ctx.config, resolved.start_hint);
+    // faable.json buildCommand overrides the provider's install. The cacheable
+    // manifest layer only applies to the provider's own command — an arbitrary
+    // buildCommand may need the full source.
+    const base_install = ctx.config.buildCommand ?? resolved.install_command;
+    const install_command = with_server_injection(base_install, server, deps);
+    const install_files = ctx.config.buildCommand
+        ? undefined
+        : resolved.install_files;
+    const version = resolve_python_version(ctx.workdir, resolved.python_version);
+    log.info(`Using python@${version}`);
+    log.info(`📦 Install command: ${install_command}`);
+    log.info(`⚙️ Start command: ${start_command}`);
+    return {
+        buildpack: "python",
+        runtime: { name: "python", version },
+        type: "python",
+        start_command,
+        install_command,
+        install_files,
+        from: `python:${version}`,
+    };
+};
+const python_buildpack = {
+    name: "python",
+    detect_files: PROVIDERS.flatMap((p) => p.files),
+    async detect(ctx) {
+        const provider = PROVIDERS.find((p) => has_any_of_files(p.files, ctx.workdir));
+        if (!provider)
+            return null;
+        return detect_with_provider(ctx, provider);
+    },
+    async build(ctx, plan) {
+        // Dependencies install inside the image (unlike node); nothing runs on
+        // the host here.
+        log.info(`Using docker image ${plan.from}-slim`);
+        const dockerfile = render_dockerfile({
+            from: plan.from,
+            env: { PYTHONUNBUFFERED: "1" },
+            banner: BANNER,
+            start_command: plan.start_command,
+            install_command: plan.install_command,
+            install_files: plan.install_files,
+        });
+        await build_image({ app: ctx.app, workdir: ctx.workdir, dockerfile });
+    },
+};
+
+export { python_buildpack };

package/dist/commands/deploy/buildpacks/python/providers/pipfile.js

@@ -0,0 +1,13 @@
+const pipfile_provider = {
+    name: "pipfile",
+    files: ["Pipfile"],
+    resolve() {
+        return {
+            // `pipenv install --deploy` reads Pipfile.lock too — keep the install
+            // after `COPY . .` so it sees whatever the repo ships.
+            install_command: "pip install --no-cache-dir pipenv && pipenv install --system --deploy",
+        };
+    },
+};
+
+export { pipfile_provider };

package/dist/commands/deploy/buildpacks/python/providers/pyproject.js

@@ -0,0 +1,13 @@
+const pyproject_provider = {
+    name: "pyproject",
+    files: ["pyproject.toml"],
+    resolve() {
+        return {
+            // `pip install .` builds the package, so it needs the full source —
+            // no install_files: the install runs after `COPY . .`.
+            install_command: "pip install --no-cache-dir .",
+        };
+    },
+};
+
+export { pyproject_provider };

package/dist/commands/deploy/buildpacks/python/providers/requirements.js

@@ -0,0 +1,14 @@
+const requirements_provider = {
+    name: "requirements",
+    files: ["requirements.txt"],
+    resolve() {
+        return {
+            install_command: "pip install --no-cache-dir -r requirements.txt",
+            // Copying only the manifest keeps the install layer cached until
+            // requirements.txt itself changes.
+            install_files: ["requirements.txt"],
+        };
+    },
+};
+
+export { requirements_provider };

package/dist/commands/deploy/{runtime-detect/strategies/python.js → buildpacks/python/python_version.js}

@@ -1,16 +1,16 @@
 import fs from 'fs-extra';
 import path__default from 'path';
-import { log } from '../../../../log.js';
 
 const DEFAULT_VERSION = "3.11.3";
 /**
  * Resolve the Python version from (in order):
  *  1. runtime.txt          → `python-3.11.3`
  *  2. .python-version      → `3.11.3` (pyenv)
- *  3. pyproject.toml       → `requires-python = ">=3.11"` (first concrete X.Y[.Z])
+ *  3. provider hint        → e.g. cerebrium.toml `python_version`
+ *  4. pyproject.toml       → `requires-python = ">=3.11"` (first concrete X.Y[.Z])
  * Falls back to DEFAULT_VERSION.
  */
-const resolve_python_version = (workdir) => {
+const resolve_python_version = (workdir, provider_hint) => {
     const runtime_config = path__default.join(workdir, "runtime.txt");
     if (fs.existsSync(runtime_config)) {
         const runtime_data = fs.readFileSync(runtime_config).toString().trim();
@@ -25,6 +25,8 @@ const resolve_python_version = (workdir) => {
         if (version)
             return version;
     }
+    if (provider_hint)
+        return provider_hint;
     const pyproject = path__default.join(workdir, "pyproject.toml");
     if (fs.existsSync(pyproject)) {
         const toml = fs.readFileSync(pyproject).toString();
@@ -34,15 +36,5 @@ const resolve_python_version = (workdir) => {
     }
     return DEFAULT_VERSION;
 };
-const strategy_python = async (workdir) => {
-    const runtime_version = resolve_python_version(workdir);
-    log.info(`Using python@${runtime_version}`);
-    return {
-        runtime: {
-            name: "python",
-            version: runtime_version,
-        },
-    };
-};
 
-export { strategy_python };
+export { resolve_python_version };

package/dist/commands/deploy/{python-pipeline/analyze_python.js → buildpacks/python/resolve_start.js}

@@ -1,10 +1,9 @@
 import fs from 'fs-extra';
 import path__default from 'path';
-import { log } from '../../../log.js';
-import { Configuration } from '../../../lib/Configuration.js';
+import { log } from '../../../../log.js';
 import { parse_procfile } from './parse_procfile.js';
 
-/** Combine all dependency manifests into one lowercased blob for cheap lookups. */
+/** Combine all classic dependency manifests into one lowercased blob. */
 const read_dependencies_text = (workdir) => {
     const files = ["requirements.txt", "pyproject.toml", "Pipfile"];
     return files
@@ -65,13 +64,20 @@ const find_app_module = (workdir, pattern) => {
     }
     return first_existing;
 };
-/** Resolve the container start command and which server it needs installed. */
-const resolve_start = (workdir, deps) => {
+/**
+ * Resolve the container start command and which server it needs installed.
+ * Precedence: faable.json startCommand → Procfile `web:` → provider start
+ * hint (e.g. cerebrium entrypoint) → framework detection (Django → FastAPI/
+ * ASGI → Flask).
+ */
+const resolve_start = (workdir, deps, config, start_hint) => {
     // 1. Explicit override in faable.json
-    const configured = Configuration.instance().configuredStartCommand;
-    if (configured) {
+    if (config.startCommand) {
         log.info(`Using start command from faable.json`);
-        return { start_command: configured, server: server_from_command(configured) };
+        return {
+            start_command: config.startCommand,
+            server: server_from_command(config.startCommand),
+        };
     }
     // 2. Procfile `web:` line
     const procfile = parse_procfile(workdir);
@@ -79,7 +85,12 @@ const resolve_start = (workdir, deps) => {
         log.info(`Using start command from Procfile`);
         return { start_command: procfile, server: server_from_command(procfile) };
     }
-    // 3. Framework detection
+    // 3. Provider hint (e.g. cerebrium.toml runtime entrypoint)
+    if (start_hint) {
+        log.info(`Using start command from the project manifest`);
+        return { start_command: start_hint, server: server_from_command(start_hint) };
+    }
+    // 4. Framework detection
     // Django: manage.py + the package holding wsgi.py
     if (fs.existsSync(path__default.join(workdir, "manage.py"))) {
         const pkg = find_django_package(workdir);
@@ -115,23 +126,13 @@ const resolve_start = (workdir, deps) => {
     }
     throw new Error("Could not detect how to start this Python app. Set `startCommand` in faable.json or add a Procfile with a `web:` line.");
 };
-/** Build the dependency-install command run during the Docker build. */
-const build_install_command = (workdir, server, deps) => {
-    const steps = [];
-    const configured_build = Configuration.instance().buildCommand;
-    if (configured_build) {
-        steps.push(configured_build);
-    }
-    else if (fs.existsSync(path__default.join(workdir, "requirements.txt"))) {
-        steps.push("pip install --no-cache-dir -r requirements.txt");
-    }
-    else if (fs.existsSync(path__default.join(workdir, "pyproject.toml"))) {
-        steps.push("pip install --no-cache-dir .");
-    }
-    else if (fs.existsSync(path__default.join(workdir, "Pipfile"))) {
-        steps.push("pip install --no-cache-dir pipenv && pipenv install --system --deploy");
-    }
-    // Ensure the WSGI/ASGI server is available when not already declared.
+/**
+ * Append the WSGI/ASGI server install when the start command needs one that
+ * isn't already declared in the dependencies. Returns "true" (no-op) when
+ * there is nothing to install at all.
+ */
+const with_server_injection = (base, server, deps) => {
+    const steps = base ? [base] : [];
     if (server === "gunicorn" && !has_token(deps, "gunicorn")) {
         steps.push("pip install --no-cache-dir gunicorn");
     }
@@ -139,20 +140,9 @@ const build_install_command = (workdir, server, deps) => {
         steps.push("pip install --no-cache-dir uvicorn[standard]");
     }
     if (steps.length === 0) {
-        // No manifest found — nothing to install, but warn the user.
-        log.warn("No requirements.txt/pyproject.toml/Pipfile found");
         return "true";
     }
     return steps.join(" && ");
 };
-const analyze_python = async (params) => {
-    const { workdir } = params;
-    const deps = read_dependencies_text(workdir);
-    const { start_command, server } = resolve_start(workdir, deps);
-    const install_command = build_install_command(workdir, server, deps);
-    log.info(`📦 Install command: ${install_command}`);
-    log.info(`⚙️ Start command: ${start_command}`);
-    return { install_command, start_command };
-};
 
-export { analyze_python };
+export { find_app_module, has_token, read_dependencies_text, resolve_start, with_server_injection };

package/dist/commands/deploy/buildpacks/registry.js

@@ -0,0 +1,60 @@
+import { docker_buildpack } from './docker/index.js';
+import { node_buildpack } from './node/index.js';
+import { python_buildpack } from './python/index.js';
+
+/**
+ * Ordered registry, first claim wins. Order is load-bearing:
+ *  1. node before python — full-stack repos shipping both a package.json and
+ *     Python manifests build as node (historical rule).
+ *  2. python (all its manifest providers) before docker — a dependency
+ *     manifest beats a Dockerfile; the Dockerfile is the explicit escape
+ *     hatch evaluated last among strong triggers.
+ * Weak signals (python's entrypoint fallback) run in a second pass so they
+ * lose against ANY strong trigger without buildpacks knowing about each other.
+ */
+const BUILDPACKS = [
+    node_buildpack,
+    python_buildpack,
+    docker_buildpack,
+];
+const buildpack_names = () => BUILDPACKS.map((b) => b.name);
+const get_buildpack = (name) => BUILDPACKS.find((b) => b.name === name);
+/**
+ * Resolve the buildpack plan for a workdir. `override` (from --buildpack or
+ * faable.json) skips detection order and forces one buildpack; it still runs
+ * that buildpack's detect so the plan is computed from real project files.
+ */
+const detect_buildpack = async (ctx, override) => {
+    if (override) {
+        const buildpack = get_buildpack(override);
+        if (!buildpack) {
+            throw new Error(`Unknown buildpack "${override}". Valid buildpacks: ${buildpack_names().join(", ")}.`);
+        }
+        const plan = (await buildpack.detect(ctx)) ??
+            (await buildpack.detect_fallback?.(ctx)) ??
+            null;
+        if (!plan) {
+            throw new Error(`Buildpack "${override}" was forced but none of its trigger files ` +
+                `(${[...buildpack.detect_files, ...(buildpack.fallback_files ?? [])].join(", ")}) ` +
+                `exist in ${ctx.workdir}.`);
+        }
+        return plan;
+    }
+    // Strong pass: manifests and Dockerfiles.
+    for (const buildpack of BUILDPACKS) {
+        const plan = await buildpack.detect(ctx);
+        if (plan)
+            return plan;
+    }
+    // Fallback pass: weak signals, only when nothing claimed the project.
+    for (const buildpack of BUILDPACKS) {
+        if (!buildpack.detect_fallback)
+            continue;
+        const plan = await buildpack.detect_fallback(ctx);
+        if (plan)
+            return plan;
+    }
+    throw new Error("Cannot detect project type");
+};
+
+export { BUILDPACKS, buildpack_names, detect_buildpack, get_buildpack };

package/dist/commands/deploy/buildpacks/shared/docker_image.js

@@ -0,0 +1,49 @@
+import fs from 'fs-extra';
+import Handlebars from 'handlebars';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { cmd } from '../../../../lib/cmd.js';
+import { log } from '../../../../log.js';
+
+const __filename$1 = fileURLToPath(import.meta.url);
+const __dirname$1 = path.dirname(__filename$1);
+const templates_dir = path.join(__dirname$1, "templates");
+const dockerfile_source = fs
+    .readFileSync(path.join(templates_dir, "Dockerfile"))
+    .toString();
+const entrypoint_source = fs
+    .readFileSync(path.join(templates_dir, "entrypoint.sh"))
+    .toString("utf-8");
+// Backslash-escape content so it survives BOTH the unquoted bash heredoc the
+// Dockerfile is piped through (docker build -f -<<EOF) and, for the entry
+// script, the single-quoted `RUN echo '...'`.
+Handlebars.registerHelper("escape", function (variable) {
+    const escaped_lines = variable
+        .replace(/(['`\\])/g, "\\$1")
+        .replace(/([$])/g, "\\$1");
+    return escaped_lines.split("\n").join("\\n");
+});
+const docker_template = Handlebars.compile(dockerfile_source);
+const entrypoint_template = Handlebars.compile(entrypoint_source);
+/** Pure render of the final Dockerfile contents — snapshot-tested. */
+const render_dockerfile = (params) => {
+    // NOTE: use slim to build projects
+    const from = [params.from, "slim"].filter((e) => e).join("-");
+    const entry_script = entrypoint_template({ banner: params.banner });
+    return docker_template({
+        from,
+        env: params.env,
+        entry_script,
+        start_command: params.start_command,
+        install_command: params.install_command,
+        install_files: params.install_files,
+    });
+};
+const build_image = async (props) => {
+    const { app, workdir, dockerfile } = props;
+    log.info(`📦 Packaging inside a docker image`);
+    const timeout = 10 * 60 * 1000; // 10 minute timeout
+    await cmd(`docker build --platform linux/amd64 -t ${app.id} ${workdir} -f -<<EOF\n${dockerfile}\nEOF`, { timeout, enableOutput: true });
+};
+
+export { build_image, render_dockerfile };

package/dist/commands/deploy/{python-pipeline → buildpacks/shared}/templates/Dockerfile

@@ -6,17 +6,31 @@ WORKDIR /faable/app
 
 # Environment variables for runtime
 ENV PORT=80
-ENV PYTHONUNBUFFERED=1
+{{#each env}}
+ENV {{@key}}={{this}}
+{{/each}}
 # `escape` keeps `$PORT` literal so the build heredoc (unquoted bash) doesn't
 # eat it; Docker then expands $PORT (=80) when building the ENV value.
 ENV START_COMMAND="{{{escape start_command}}}"
 
+{{#if install_files}}
+# Copy dependency manifests first so the install layer stays cached until
+# they change (any source change no longer reinstalls dependencies).
+{{#each install_files}}
+COPY {{this}} ./
+{{/each}}
+RUN {{{escape install_command}}}
+{{/if}}
+
 # Copy Usercode
 COPY . .
 
-# Install dependencies (Python needs them built into the image, unlike node_modules).
-# Triple-stache + escape: keep `&&` intact and any `$` heredoc-safe.
+{{#unless install_files}}
+{{#if install_command}}
+# Install needs the full source (e.g. `pip install .`), so it runs after COPY.
 RUN {{{escape install_command}}}
+{{/if}}
+{{/unless}}
 
 # Entrypoint stript
 RUN echo '{{{escape entry_script}}}' >> entrypoint.sh

package/dist/commands/deploy/buildpacks/shared/templates/entrypoint.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+{{{banner}}}
+eval $START_COMMAND

package/dist/commands/deploy/index.js

@@ -1,12 +1,10 @@
 import { requireApi } from '../../api/context.js';
-import { cmd } from '../../lib/cmd.js';
 import { Configuration } from '../../lib/Configuration.js';
 import { log } from '../../log.js';
+import { plan_summary } from './buildpacks/Buildpack.js';
+import { detect_buildpack, get_buildpack, buildpack_names } from './buildpacks/registry.js';
 import { check_environment } from './check_environment.js';
 import { git_context } from './git_context.js';
-import { build_node } from './node-pipeline/index.js';
-import { build_python } from './python-pipeline/index.js';
-import { runtime_detection } from './runtime-detect/runtime_detection.js';
 import { upload_tag } from './upload_tag.js';
 
 const deploy = {
@@ -22,6 +20,12 @@ const deploy = {
             alias: 'w',
             type: 'string',
             description: 'Working directory'
+        })
+            .option('buildpack', {
+            alias: 'b',
+            type: 'string',
+            choices: buildpack_names(),
+            description: 'Force a specific buildpack (overrides auto-detection and faable.json)'
         })
             .showHelpOnFail(false);
     },
@@ -29,8 +33,10 @@ const deploy = {
         const workdir = args.workdir || process.cwd();
         const ctx = await requireApi();
         const { api } = ctx;
-        // Resolve runtime
-        const { runtime } = await runtime_detection(workdir);
+        // Resolve the buildpack plan (detection or forced override). All the
+        // build thinking happens here; build() below just executes the plan.
+        const config = Configuration.instance().deployConfig();
+        const plan = await detect_buildpack({ workdir, config }, args.buildpack || config.buildpack);
         // app_id resolution (the user never has to look one up):
         //  1. explicit positional (monorepo escape hatch)
         //  2. OIDC in CI — the backend resolves the app from the linked repository
@@ -42,33 +48,19 @@ const deploy = {
         const app = await api.getApp(app_id);
         // Check if we can build docker images
         await check_environment();
-        log.info(`🚀 Deploying "${app.name}" (${app.id}) runtime=${runtime.name}-${runtime.version}`);
+        const runtime_label = plan.runtime.version
+            ? `${plan.runtime.name}-${plan.runtime.version}`
+            : plan.runtime.name;
+        log.info(`🚀 Deploying "${app.name}" (${app.id}) runtime=${runtime_label}`);
+        log.info(`🧩 Build plan ${plan_summary(plan)}`);
         // get environment variables
         const env_vars = await api.getAppSecrets(app.id);
-        let type;
-        if (runtime.name == 'node') {
-            const node_result = await build_node(app, {
-                workdir,
-                runtime,
-                env_vars
-            });
-            type = node_result.type;
-        }
-        else if (runtime.name == 'python') {
-            const python_result = await build_python(app, {
-                workdir,
-                runtime});
-            type = python_result.type;
-        }
-        else if (runtime.name == 'docker') {
-            type = 'node';
-            await cmd(`docker build -t ${app.id} .`, {
-                enableOutput: true
-            });
-        }
-        else {
-            throw new Error(`No build pipeline for runtime=${runtime.name}`);
+        const buildpack = get_buildpack(plan.buildpack);
+        if (!buildpack) {
+            throw new Error(`No buildpack registered for plan=${plan.buildpack}`);
         }
+        await buildpack.build({ workdir, config, app, env_vars }, plan);
+        const type = plan.type;
         // Upload to Faable registry
         const { upload_tagname } = await upload_tag({ app, api });
         // Capture the commit/ref/actor so the deployment records which commit it

package/dist/commands/link/workflow_template.js

@@ -22,7 +22,6 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
-      - run: npm ci
       - run: npx @faable/faable@latest deploy
 `;
 const DEPLOY_DOCS_URL = "https://faable.com/docs/deploy/github-actions";

package/dist/lib/Configuration.js

@@ -45,6 +45,17 @@ class Configuration {
     get buildCommand() {
         return this.config.buildCommand;
     }
+    /**
+     * faable.json subset consumed by the deploy buildpacks. Buildpacks receive
+     * this via their context and never touch the singleton directly.
+     */
+    deployConfig() {
+        return {
+            startCommand: this.config.startCommand,
+            buildCommand: this.config.buildCommand,
+            buildpack: this.config.buildpack,
+        };
+    }
     get app_slug() {
         return this.config.app_slug;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",

package/dist/commands/deploy/node-pipeline/build_docker.js

@@ -1,52 +0,0 @@
-import { log } from '../../../log.js';
-import { cmd } from '../../../lib/cmd.js';
-import fs from 'fs-extra';
-import Handlebars from 'handlebars';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-import { Configuration } from '../../../lib/Configuration.js';
-
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
-const templates_dir = path.join(__dirname$1, "templates");
-const dockerfile = fs.readFileSync(`${templates_dir}/Dockerfile`).toString();
-const entrypoint = fs
-    .readFileSync(`${templates_dir}/entrypoint.sh`)
-    .toString("utf-8");
-Handlebars.registerHelper("escape", function (variable) {
-    //const escaped_quotes = variable.replace(/(['"])/g, "\\$1");
-    const escaped_lines = variable
-        .replace(/(['`\\])/g, "\\$1")
-        .replace(/([$])/g, "\\$1");
-    return escaped_lines.split("\n").join("\\n");
-    //return escaped_lines.split("\n").join("\\n");
-});
-// Docker template file
-const docker_template = Handlebars.compile(dockerfile);
-const entrypoint_template = Handlebars.compile(entrypoint);
-const build_docker = async (props) => {
-    const { app, workdir, template_context } = props;
-    const entrypoint_custom = entrypoint_template(template_context);
-    // Precedence: explicit faable.json startCommand > framework-detected command
-    // (e.g. serving a static SPA) > default `npm run start`.
-    const start_command = Configuration.instance().configuredStartCommand ??
-        props.start_command ??
-        "npm run start";
-    log.info(`⚙️ Start command: ${start_command}`);
-    // NOTE: use slim to build projects
-    const linux_distro = "slim";
-    const from = [template_context.from, linux_distro].filter((e) => e).join("-");
-    log.info(`Using docker image ${from}`);
-    // run template
-    const dockerfile = docker_template({
-        from,
-        entry_script: entrypoint_custom,
-        start_command,
-    });
-    log.info(`📦 Packaging inside a docker image`);
-    // Build options
-    const timeout = 10 * 60 * 1000; // 10 minute timeout
-    await cmd(`docker build --platform linux/amd64 -t ${app.id} ${workdir} -f -<<EOF\n${dockerfile}\nEOF`, { timeout, enableOutput: true });
-};
-
-export { build_docker };

package/dist/commands/deploy/node-pipeline/build_project.js

@@ -1,26 +0,0 @@
-import { log } from '../../../log.js';
-import { cmd } from '../../../lib/cmd.js';
-import { Configuration } from '../../../lib/Configuration.js';
-
-const build_project = async (args) => {
-    const build_script = args.build_script;
-    const build_command = build_script
-        ? `npm run ${build_script}`
-        : Configuration.instance().buildCommand;
-    if (build_command) {
-        const cwd = args.cwd || process.cwd();
-        log.info(`⚙️ Building project [${build_command}]...`);
-        const timeout = 1000 * 60 * 30; // 30 minute timeout
-        await cmd(build_command, {
-            timeout,
-            cwd,
-            enableOutput: true,
-            ...(args?.env ? { env: args?.env } : {}),
-        });
-    }
-    else {
-        log.info(`⚡️ No build step`);
-    }
-};
-
-export { build_project };

package/dist/commands/deploy/node-pipeline/index.js

@@ -1,40 +0,0 @@
-import { build_docker } from './build_docker.js';
-import { analyze_package } from './analyze_package.js';
-import { build_project } from './build_project.js';
-import { inject_serve } from './inject_serve.js';
-import * as R from 'ramda';
-import { log } from '../../../log.js';
-
-const build_node = async (app, options) => {
-    // log.info(`🚀 Build Toolchain ${app.name} [${app.id}]`);
-    const { workdir, runtime, env_vars = [] } = options;
-    if (!runtime.version) {
-        throw new Error("Runtime version not specified for node");
-    }
-    // Analyze package.json to check if build is needed
-    const { build_script, type, start_command, inject_serve: needs_serve } = await analyze_package({
-        workdir,
-    });
-    // Environment variables
-    const env = R.fromPairs(env_vars.map((e) => [e.name, e.value]));
-    log.info(`Building with env variables ${Object.keys(env).join(",")}`);
-    // Do build
-    await build_project({ build_script, env });
-    // Frameworks without a bundled static server (CRA/Vue/Angular) need `serve`
-    // installed into node_modules before packaging, so it ships in the image.
-    if (needs_serve) {
-        await inject_serve(workdir);
-    }
-    // Bundle project inside a docker image
-    await build_docker({
-        app,
-        workdir,
-        start_command,
-        template_context: {
-            from: `node:${runtime.version}`,
-        },
-    });
-    return { type };
-};
-
-export { build_node };

package/dist/commands/deploy/node-pipeline/templates/Dockerfile

@@ -1,18 +0,0 @@
-FROM {{from}}
-LABEL com.faable.cloud="FaableCloud"
-LABEL description="Faablecloud automatic deployment"
-
-WORKDIR /faable/app
-
-# Environment variables for runtime
-ENV PORT=80
-ENV NODE_ENV=production
-ENV START_COMMAND="{{start_command}}"
-
-# Copy Usercode
-COPY . .
-
-# Entrypoint stript
-RUN echo '{{{escape entry_script}}}' >> entrypoint.sh
-
-CMD ["/bin/sh", "./entrypoint.sh"]  

package/dist/commands/deploy/node-pipeline/templates/entrypoint.sh

@@ -1,8 +0,0 @@
-#!/bin/sh
-
-NODE_VERSION=$(node --version)
-NPM_VERSION=$(npm --version)
-YARN_VERSION=$(yarn --version)
-
-echo "Faable Cloud · [node $NODE_VERSION] [npm $NPM_VERSION] [yarn $YARN_VERSION]"
-eval $START_COMMAND

package/dist/commands/deploy/python-pipeline/build_docker.js

@@ -1,42 +0,0 @@
-import { log } from '../../../log.js';
-import { cmd } from '../../../lib/cmd.js';
-import fs from 'fs-extra';
-import Handlebars from 'handlebars';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
-const templates_dir = path.join(__dirname$1, "templates");
-const dockerfile = fs.readFileSync(`${templates_dir}/Dockerfile`).toString();
-const entrypoint = fs
-    .readFileSync(`${templates_dir}/entrypoint.sh`)
-    .toString("utf-8");
-Handlebars.registerHelper("escape", function (variable) {
-    const escaped_lines = variable
-        .replace(/(['`\\])/g, "\\$1")
-        .replace(/([$])/g, "\\$1");
-    return escaped_lines.split("\n").join("\\n");
-});
-const docker_template = Handlebars.compile(dockerfile);
-const entrypoint_template = Handlebars.compile(entrypoint);
-const build_docker = async (props) => {
-    const { app, workdir, install_command, start_command, template_context } = props;
-    const entrypoint_custom = entrypoint_template({});
-    log.info(`⚙️ Start command: ${start_command}`);
-    // NOTE: use slim to build projects
-    const linux_distro = "slim";
-    const from = [template_context.from, linux_distro].filter((e) => e).join("-");
-    log.info(`Using docker image ${from}`);
-    const dockerfile = docker_template({
-        from,
-        entry_script: entrypoint_custom,
-        install_command,
-        start_command,
-    });
-    log.info(`📦 Packaging inside a docker image`);
-    const timeout = 10 * 60 * 1000; // 10 minute timeout
-    await cmd(`docker build --platform linux/amd64 -t ${app.id} ${workdir} -f -<<EOF\n${dockerfile}\nEOF`, { timeout, enableOutput: true });
-};
-
-export { build_docker };

package/dist/commands/deploy/python-pipeline/index.js

@@ -1,25 +0,0 @@
-import { analyze_python } from './analyze_python.js';
-import { build_docker } from './build_docker.js';
-
-const build_python = async (app, options) => {
-    const { workdir, runtime } = options;
-    if (!runtime.version) {
-        throw new Error("Runtime version not specified for python");
-    }
-    // Resolve how to install deps and start the app. Unlike node, there is no
-    // separate local build step: dependency install happens inside the Docker
-    // build (where network is available), so we go straight to packaging.
-    const { install_command, start_command } = await analyze_python({ workdir });
-    await build_docker({
-        app,
-        workdir,
-        install_command,
-        start_command,
-        template_context: {
-            from: `python:${runtime.version}`,
-        },
-    });
-    return { type: "python" };
-};
-
-export { build_python };

package/dist/commands/deploy/python-pipeline/templates/entrypoint.sh

@@ -1,7 +0,0 @@
-#!/bin/sh
-
-PYTHON_VERSION=$(python --version 2>&1)
-PIP_VERSION=$(pip --version 2>&1)
-
-echo "Faable Cloud · [$PYTHON_VERSION] [$PIP_VERSION]"
-eval $START_COMMAND

package/dist/commands/deploy/runtime-detect/runtime_detection.js

@@ -1,25 +0,0 @@
-import * as R from 'ramda';
-import { has_any_of_files } from './helpers/has_any_of_files.js';
-import { strategy_docker } from './strategies/docker.js';
-import { strategy_nodejs } from './strategies/nodejs.js';
-import { strategy_python } from './strategies/python.js';
-
-const runtime_detection = async (workdir) => {
-    const has = R.curry(has_any_of_files);
-    // Order matters: node wins for full-stack apps that ship both a package.json
-    // and Python deps; Dockerfile is the explicit escape hatch evaluated last.
-    const strategy = R.cond([
-        [has(['package.json']), R.always(strategy_nodejs)],
-        [
-            has(['requirements.txt', 'pyproject.toml', 'Pipfile']),
-            R.always(strategy_python)
-        ],
-        [has(['Dockerfile']), R.always(strategy_docker)]
-    ])(workdir);
-    if (!strategy) {
-        throw new Error('Cannot detect project type');
-    }
-    return strategy(workdir);
-};
-
-export { runtime_detection };

package/dist/commands/deploy/runtime-detect/strategies/docker.js

@@ -1,9 +0,0 @@
-const strategy_docker = async (_workdir) => {
-    return {
-        runtime: {
-            name: "docker",
-        },
-    };
-};
-
-export { strategy_docker };