@faable/faable 1.5.25 → 1.5.27

package/dist/api/FaableApi.js

@@ -34,9 +34,15 @@ class FaableApi {
                 const url = e.config?.url || "";
                 if (res) {
                     const serverMessage = res.data?.message || res.statusText || "Unknown Error";
-                    throw new Error(`FaableApi ${url} ${res.status}: ${serverMessage}`, {
-                        cause: error,
-                    });
+                    const wrapped = new Error(`FaableApi ${url} ${res.status}: ${serverMessage}`, { cause: error });
+                    // Surface the structured error contract (e.g. the repository-link
+                    // flow returns { code, action }) so callers can branch on it.
+                    wrapped.status = res.status;
+                    if (res.data?.code)
+                        wrapped.code = res.data.code;
+                    if (res.data?.action)
+                        wrapped.action = res.data.action;
+                    throw wrapped;
                 }
                 else {
                     throw new Error(`FaableApi ${url} ${e.message}`, { cause: error });
@@ -69,6 +75,17 @@ class FaableApi {
     async updateApp(app_id, params) {
         return data(this.client.post(`/app/${app_id}`, params));
     }
+    async linkRepository(app_id, params) {
+        return data(this.client.post(`/app/${app_id}/link-repository`, params));
+    }
+    // Organizations/accounts where the Faable GitHub App is installed.
+    async listGithubInstallations() {
+        return data(this.client.get(`/github/installations`)).then((res) => res.installations);
+    }
+    // Top repositories for a single installation (org), optionally filtered.
+    async listGithubRepos(installation_id, params = {}) {
+        return data(this.client.get(`/github/installations/${installation_id}/repositories`, { params })).then((res) => res.repositories);
+    }
     async getMe() {
         return data(this.client.get(`/auth/me`));
     }

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/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 {
@@ -84,18 +85,71 @@ const link = {
             return;
         }
         log.info(`Linking to "${selectedApp.name}" (${selectedApp.id})...`);
-        // Update the app in the API
-        if (gitUrl) {
-            await api.updateApp(selectedApp.id, { repository: gitUrl });
-            log.info(`Updated app with github_repo: ${gitUrl}`);
+        if (!gitUrl) {
+            log.error("No git remote URL detected. Add a GitHub 'origin' remote and try again.");
+            return;
         }
-        else {
-            log.warn("No git remote URL detected. Skipping API update for github_repo.");
+        // The API verifies that the user has a connected GitHub identity AND
+        // access to the repository before persisting the link.
+        try {
+            await api.linkRepository(selectedApp.id, { repository: gitUrl });
+        }
+        catch (err) {
+            const code = err?.code;
+            switch (code) {
+                case "github_identity_missing":
+                    log.error("You have not connected a GitHub account to Faable. Connect GitHub in the dashboard, then re-run `faable link`.");
+                    break;
+                case "github_token_invalid":
+                    log.error("Your GitHub authorization has expired. Reconnect GitHub in the dashboard, then re-run `faable link`.");
+                    break;
+                case "github_installation_missing":
+                    log.error("The Faable GitHub App is not installed on your repositories. Install it from the Faable dashboard, then re-run `faable link`.");
+                    break;
+                case "github_repository_not_found":
+                    log.error(`Faable can't access "${gitUrl}". Check the repository name and that the Faable GitHub App is installed on it.`);
+                    break;
+                default:
+                    log.error(`Could not link repository: ${err?.message ?? err}`);
+            }
+            return;
         }
-        // Save locally for CLI convenience
+        log.info(`Linked repository ${gitUrl} to ${selectedApp.name}.`);
+        // 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/package.json

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