@faable/faable 1.5.26 → 1.5.28

package/dist/commands/deploy/git_context.js

@@ -0,0 +1,39 @@
+import { exec } from 'child_process';
+
+// Quiet git runner: returns trimmed stdout, or undefined on any failure (not a
+// git repo, git missing, etc.). A deploy must never fail because we couldn't
+// read git metadata, so errors are swallowed and the field is just omitted.
+const gitRunner = (workdir) => command => new Promise(resolve => {
+    exec(command, { cwd: workdir }, (err, stdout) => {
+        if (err)
+            return resolve(undefined);
+        const out = stdout?.toString().trim();
+        resolve(out || undefined);
+    });
+});
+// Resolve the commit / ref / actor for the current deploy. In GitHub Actions
+// these come from the standard env vars; locally we fall back to git so manual
+// deploys still record a commit. `github_actor` is CI-only (a GitHub login),
+// left undefined locally where no reliable login is available.
+const git_context = async (opts) => {
+    const env = opts?.env ?? process.env;
+    const run = opts?.run ?? gitRunner(opts?.workdir);
+    const github_commit = env.GITHUB_SHA || (await run("git rev-parse HEAD"));
+    let github_ref = env.GITHUB_REF || undefined;
+    if (!github_ref) {
+        const branch = await run("git rev-parse --abbrev-ref HEAD");
+        if (branch && branch !== "HEAD")
+            github_ref = `refs/heads/${branch}`;
+    }
+    const github_actor = env.GITHUB_ACTOR || undefined;
+    const ctx = {};
+    if (github_commit)
+        ctx.github_commit = github_commit;
+    if (github_ref)
+        ctx.github_ref = github_ref;
+    if (github_actor)
+        ctx.github_actor = github_actor;
+    return ctx;
+};
+
+export { git_context };

package/dist/commands/deploy/index.js

@@ -2,6 +2,7 @@ import { context } from '../../api/context.js';
 import { cmd } from '../../lib/cmd.js';
 import { log } from '../../log.js';
 import { check_environment } from './check_environment.js';
+import { git_context } from './git_context.js';
 import { build_node } from './node-pipeline/index.js';
 import { runtime_detection } from './runtime-detect/runtime_detection.js';
 import { upload_tag } from './upload_tag.js';
@@ -58,11 +59,15 @@ const deploy = {
         }
         // Upload to Faable registry
         const { upload_tagname } = await upload_tag({ app, api });
+        // Capture the commit/ref/actor so the deployment records which commit it
+        // came from and who pushed it (env in CI, git fallback locally).
+        const git = await git_context({ workdir });
         // Create a deployment for this image
         const deployment = await api.createDeployment({
             app_id: app.id,
             image: upload_tagname,
-            type
+            type,
+            ...git
         });
         const dashboard_url = `https://dashboard.faable.com/deploy/${app.team}/app/${app.id}`;
         log.info(`🌍 Deployment created (${deployment.id}) -> https://${app.url}`);
@@ -83,7 +88,7 @@ const deploy = {
                     break;
                 }
             }
-            catch (error) {
+            catch (_error) {
                 // Ignore transient errors while polling and keep waiting
                 log.debug(`Polling app status failed, retrying...`);
             }

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

@@ -1,7 +1,7 @@
 import fs from 'fs-extra';
 import path__default from 'path';
 import { log } from '../../../log.js';
-import * as R from 'ramda';
+import { detect_framework } from './frameworks.js';
 
 const analyze_package = async (params) => {
     const workdir = params.workdir;
@@ -11,23 +11,24 @@ const analyze_package = async (params) => {
     // Check if build is required to run
     const build_script = process.env.FAABLE_NPM_BUILD_SCRIPT
         ? process.env.FAABLE_NPM_BUILD_SCRIPT
-        : pkg?.scripts["build"]
+        : pkg?.scripts?.["build"]
             ? "build"
             : null;
     if (!build_script) {
         log.info(`No build script on package.json`);
     }
-    let type = "node";
-    // Detect nextjs deployment type
-    const next_dep = R.lensPath(["dependencies", "next"]);
-    const next_devdep = R.lensPath(["devDependencies", "next"]);
-    if (R.view(next_dep, pkg) || R.view(next_devdep, pkg)) {
-        type = "next";
-    }
+    const has_start = Boolean(pkg?.scripts?.["start"]);
+    const { type, start_command, inject_serve } = detect_framework({
+        pkg,
+        workdir,
+        has_start,
+    });
     log.info(`⚡️ Detected deployment type=${type}`);
     return {
         build_script,
         type,
+        start_command,
+        inject_serve,
     };
 };
 

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

@@ -27,7 +27,11 @@ const entrypoint_template = Handlebars.compile(entrypoint);
 const build_docker = async (props) => {
     const { app, workdir, template_context } = props;
     const entrypoint_custom = entrypoint_template(template_context);
-    const start_command = Configuration.instance().startCommand;
+    // 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";

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

@@ -0,0 +1,108 @@
+import fs from 'fs-extra';
+import path__default from 'path';
+import * as R from 'ramda';
+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));
+/**
+ * Read Angular's build output path from angular.json. Defaults to `dist` when
+ * it can't be resolved. Angular ≥17 (application builder) emits into
+ * `<outputPath>/browser`, so we append it when the project uses that builder.
+ */
+const resolve_angular_output = (workdir) => {
+    const fallback = "dist";
+    try {
+        const angular_json = fs.readJSONSync(path__default.join(workdir, "angular.json"));
+        const projects = angular_json?.projects ?? {};
+        const project_name = angular_json?.defaultProject ?? Object.keys(projects)[0];
+        const build = projects?.[project_name]?.architect?.build;
+        const output = build?.options?.outputPath;
+        if (!output)
+            return fallback;
+        const builder = build?.builder ?? "";
+        const is_application_builder = builder.includes("application") || builder.includes("browser-esbuild");
+        return is_application_builder ? path__default.join(output, "browser") : output;
+    }
+    catch {
+        return fallback;
+    }
+};
+/**
+ * Framework registry, evaluated in order. Order matters: Astro/SvelteKit/CRA
+ * pull Vite in transitively, so Vite must be the last static fallback.
+ */
+const FRAMEWORKS = [
+    // Next.js: handled by its own runtime_strategy/PVC, never static-served here.
+    { type: "next", deps: ["next"] },
+    {
+        type: "astro",
+        deps: ["astro"],
+        outputDir: "dist",
+        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`,
+    },
+    {
+        type: "cra",
+        deps: ["react-scripts"],
+        outputDir: "build",
+        injectServe: true,
+        serveCommand: (dir) => `npx serve -s ${dir} -l $PORT`,
+    },
+    {
+        type: "vue",
+        deps: ["@vue/cli-service"],
+        outputDir: "dist",
+        injectServe: true,
+        serveCommand: (dir) => `npx serve -s ${dir} -l $PORT`,
+    },
+    {
+        type: "angular",
+        deps: ["@angular/cli", "@angular-devkit/build-angular"],
+        injectServe: true,
+        resolveOutput: resolve_angular_output,
+        serveCommand: (dir) => `npx serve -s ${dir} -l $PORT`,
+    },
+    {
+        type: "vite",
+        deps: ["vite"],
+        outputDir: "dist",
+        serveCommand: (dir) => `npx vite preview --host 0.0.0.0 --port $PORT`,
+    },
+];
+/**
+ * Detect the framework from package.json and compute how to serve it.
+ *
+ * When the project defines its own `start` script we never override it (the app
+ * ships a real server — custom SSR, Nuxt, Remix, SvelteKit node-adapter, etc.),
+ * so `start_command`/`inject_serve` stay neutral.
+ */
+const detect_framework = (params) => {
+    const { pkg, workdir, has_start } = params;
+    const framework = FRAMEWORKS.find((fw) => fw.deps.some((dep) => has_dep(pkg, dep)));
+    if (!framework) {
+        return { type: "node", start_command: null, inject_serve: false };
+    }
+    // Static frameworks only override the start command when the project doesn't
+    // ship its own server.
+    if (framework.serveCommand && !has_start) {
+        const output_dir = framework.resolveOutput
+            ? framework.resolveOutput(workdir)
+            : framework.outputDir ?? "dist";
+        const start_command = framework.serveCommand(output_dir);
+        log.info(`No start script on package.json, serving ${framework.type} output (${output_dir}) with [${start_command}]`);
+        return {
+            type: framework.type,
+            start_command,
+            inject_serve: Boolean(framework.injectServe),
+        };
+    }
+    return { type: framework.type, start_command: null, inject_serve: false };
+};
+
+export { FRAMEWORKS, detect_framework, resolve_angular_output };

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

@@ -1,6 +1,7 @@
 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';
 
@@ -11,16 +12,24 @@ const build_node = async (app, options) => {
         throw new Error("Runtime version not specified for node");
     }
     // Analyze package.json to check if build is needed
-    const { build_script, type } = await analyze_package({ workdir });
+    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}`,
         },

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

@@ -0,0 +1,20 @@
+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).
+const SERVE_VERSION = "14";
+/**
+ * Install `serve` into the project's node_modules so it ships inside the image
+ * via `COPY . .` (the Dockerfile does no `npm install`). This lets `npx serve`
+ * resolve the local copy at container start — no runtime download needed.
+ *
+ * `--no-save` keeps the user's package.json/lockfile untouched.
+ */
+const inject_serve = async (workdir) => {
+    log.info(`📥 Injecting static server (serve@${SERVE_VERSION}) into image`);
+    const timeout = 5 * 60 * 1000; // 5 minute timeout
+    await cmd(`npm install serve@${SERVE_VERSION} --no-save --no-audit --no-fund`, { cwd: workdir, timeout, enableOutput: true });
+};
+
+export { inject_serve };

package/dist/commands/link/index.js

@@ -3,6 +3,7 @@ import prompts from 'prompts';
 import { log } from '../../log.js';
 import { cmd } from '../../lib/cmd.js';
 import { Configuration } from '../../lib/Configuration.js';
+import { workflowExists, DEPLOY_WORKFLOW_PATH, writeWorkflow, DEPLOY_DOCS_URL, DEPLOY_WORKFLOW_YAML } from './workflow_template.js';
 
 const getGitRemoteUrl = async (workdir) => {
     try {
@@ -117,7 +118,38 @@ const link = {
         // Save locally for CLI convenience (only after the API confirms the link)
         Configuration.instance().saveConfig({ app_slug: selectedApp.name, app_id: selectedApp.id });
         log.info(`Successfully linked local repository to ${selectedApp.name}.`);
+        // Onboarding: deploys happen via a GitHub Actions workflow on push. Offer
+        // to scaffold it, and always explain the next steps so the user isn't left
+        // wondering why nothing deploys.
+        await setupDeployWorkflow(workdir);
     },
 };
+const setupDeployWorkflow = async (workdir) => {
+    if (workflowExists(workdir)) {
+        log.info(`Deploy workflow already present at ${DEPLOY_WORKFLOW_PATH}. Commit & push to "main" to deploy.`);
+        return;
+    }
+    const { create } = await prompts({
+        type: "toggle",
+        name: "create",
+        message: `Create the GitHub Actions deploy workflow (${DEPLOY_WORKFLOW_PATH})?`,
+        initial: true,
+        active: "yes",
+        inactive: "no",
+    });
+    if (create) {
+        const filePath = await writeWorkflow(workdir);
+        log.info(`Created ${filePath}`);
+        log.info("Next steps:");
+        log.info("  1. Commit the workflow file");
+        log.info('  2. Push to "main" — that triggers your first deploy');
+        log.info(`Docs: ${DEPLOY_DOCS_URL}`);
+    }
+    else {
+        log.info(`Skipped. To enable automated deploys, add ${DEPLOY_WORKFLOW_PATH} with:`);
+        log.info(`\n${DEPLOY_WORKFLOW_YAML}`);
+        log.info(`Then commit & push to "main". Docs: ${DEPLOY_DOCS_URL}`);
+    }
+};
 
 export { link };

package/dist/commands/link/workflow_template.js

@@ -0,0 +1,37 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+// The canonical GitHub Actions workflow that deploys a Faable app on push.
+// Mirrors the docs at https://faable.com/docs/deploy/github-actions.
+const DEPLOY_WORKFLOW_PATH = ".github/workflows/deploy.yaml";
+const DEPLOY_WORKFLOW_YAML = `name: Deploy to Faable
+on:
+  push:
+    branches:
+      - main
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+  issues: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    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";
+const workflowExists = (workdir) => existsSync(join(workdir, DEPLOY_WORKFLOW_PATH));
+const writeWorkflow = async (workdir) => {
+    const filePath = join(workdir, DEPLOY_WORKFLOW_PATH);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, DEPLOY_WORKFLOW_YAML, "utf8");
+    return filePath;
+};
+
+export { DEPLOY_DOCS_URL, DEPLOY_WORKFLOW_PATH, DEPLOY_WORKFLOW_YAML, workflowExists, writeWorkflow };

package/dist/lib/Configuration.js

@@ -38,6 +38,10 @@ class Configuration {
     get startCommand() {
         return this.config.startCommand || "npm run start";
     }
+    /** Start command explicitly set in faable.json, or undefined when relying on the default. */
+    get configuredStartCommand() {
+        return this.config.startCommand;
+    }
     get buildCommand() {
         return this.config.buildCommand;
     }

package/package.json

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