@faable/faable 4.14.0 → 4.16.0

package/dist/api/FaableApi.js

@@ -95,7 +95,9 @@ class FaableApi {
                             ? 'This Faable API key is invalid or was revoked. Create a new one in the dashboard (project settings → API Keys).'
                             : 'Your Faable session has expired or is invalid. Run `faable login` to sign in again.', { cause: error });
                         expired.status = 401;
-                        expired.code = by_key ? 'apikey_invalid' : 'session_expired';
+                        expired.code = by_key
+                            ? 'apikey_invalid'
+                            : 'session_expired';
                         throw expired;
                     }
                     const serverMessage = res.data?.message || res.statusText || 'Unknown Error';
@@ -157,7 +159,11 @@ class FaableApi {
     async listProjects(params) {
         const { q, user_id, ...page } = params;
         return data(this.client.get(`/project`, {
-            params: { ...page_params(page), ...(q ? { q } : {}), ...(user_id ? { user_id } : {}) }
+            params: {
+                ...page_params(page),
+                ...(q ? { q } : {}),
+                ...(user_id ? { user_id } : {})
+            }
         }));
     }
     async getProject(project_id) {

package/dist/commands/deploy/launch.js

@@ -7,6 +7,7 @@ import { log } from '../../log.js';
 import { requireProject } from '../../api/project.js';
 import { git_context } from './git_context.js';
 import { show_deploy_help } from './help.js';
+import { reachable_timeout_ms, wait_reachable } from './reachable.js';
 import { propose_release } from './release_version.js';
 import { assert_name_free } from './apps/name_free.js';
 import { deploy_remote } from './remote/index.js';
@@ -221,6 +222,13 @@ const launch = {
                     log.debug(`Polling app status failed, retrying...`);
                 }
             }
+            // Promoted is not yet answering: wait for the edge to route the URL
+            // (F9). `undefined` when the check is off (FAABLE_REACHABLE_TIMEOUT_MS=0).
+            let reachable;
+            if (promoted && reachable_timeout_ms() > 0) {
+                log.info(`⏳ Live — waiting for https://${app.url} to answer...`);
+                reachable = await wait_reachable(`https://${app.url}`, reachable_timeout_ms());
+            }
             if (args.json) {
                 const outcome = promoted
                     ? 'live'
@@ -239,6 +247,7 @@ const launch = {
                     deployment_id: deployment.id,
                     outcome,
                     url: `https://${app.url}`,
+                    ...(reachable !== undefined ? { reachable } : {}),
                     ...(failure
                         ? {
                             phase: failure.phase,
@@ -262,6 +271,9 @@ const launch = {
             }
             if (promoted) {
                 log.info(`🌍 Deployment promoted and live, visit: https://${app.url}`);
+                if (reachable === false) {
+                    log.warn(`⚠️ The URL still answers "app not found" — the edge is picking up the route. Try again in a minute.`);
+                }
             }
             else if (superseded) {
                 // Not a failure: the app IS live, just on a sibling deployment (e.g.

package/dist/commands/deploy/reachable.js

@@ -0,0 +1,52 @@
+// A promoted deployment is not yet a URL that answers: the edge picks up a
+// new app's route a little later, and until then it says `APP_NOT_FOUND`
+// (header `x-faable-error`, cacheable for 120 s). On 2026-10-16 a deploy
+// reported `outcome: live` and the URL gave 404 for about a minute — an agent
+// checking it right away would conclude the deploy was broken
+// (arch/deploy/cli-mcp-fallos-2026-10-16-plan.md, F9).
+//
+// Only the edge's own "no app here" counts as not served: an app is free to
+// answer 404 (or anything) on `/`, and that is its answer, not ours.
+const NOT_FOUND = 'APP_NOT_FOUND';
+// FAABLE_REACHABLE_TIMEOUT_MS: how long to wait for the edge (default 120 s);
+// `0` skips the check — a stub API in tests, or a caller that only wants the
+// deployment's phase.
+const reachable_timeout_ms = (env = process.env) => {
+    const raw = env.FAABLE_REACHABLE_TIMEOUT_MS;
+    const n = raw === undefined || raw === '' ? 120_000 : Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : 120_000;
+};
+/**
+ * Wait until `url` is served by the app rather than the edge's "no app here".
+ * True as soon as it is; false when `timeout_ms` runs out (the deploy is
+ * still live — the route is just late). Never throws: a failed request is one
+ * more "not yet".
+ */
+const wait_reachable = async (url, timeout_ms, deps = {}) => {
+    const fetch_ = deps.fetch ?? fetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
+    const deadline = now() + timeout_ms;
+    for (;;) {
+        try {
+            // The not-found answer is cacheable: bust it, or we would read our own
+            // first answer back for two minutes.
+            const probe = `${url}${url.includes('?') ? '&' : '?'}_faable_probe=${now()}`;
+            const res = await fetch_(probe, {
+                method: 'GET',
+                redirect: 'manual',
+                headers: { 'cache-control': 'no-cache' }
+            });
+            if (res.headers.get('x-faable-error') !== NOT_FOUND)
+                return true;
+        }
+        catch {
+            // not reachable yet
+        }
+        if (now() >= deadline)
+            return false;
+        await sleep(3_000);
+    }
+};
+
+export { reachable_timeout_ms, wait_reachable };

package/dist/commands/deploy/waf/add_rule.js

@@ -62,6 +62,21 @@ const add_rule = async (opts) => {
     }
     if (json)
         return waf;
+    if (action === 'allow') {
+        // The one rule that opens instead of closing: say exactly what it opens.
+        log.info(`🔓 ${describe_selector(want)} → reaches your app`);
+        log.info(`   for ${app_name} (${app_id}), even where Faable blocks it for every app`);
+        log.info(`   (archives like .zip or .tar.gz, dotfiles, config files).`);
+        log.info(``);
+        log.info(`Your own block and sink rules still win over it, and certificate checks,`);
+        log.info(`/.faable/* and /_next/* are never affected.`);
+        log.info(``);
+        log.info(`It takes about 20s to reach the edge. Then check it with:`);
+        log.info(`  curl -s -o /dev/null -w '%{http_code}\\n' https://${app_url}<path>`);
+        log.info(``);
+        log.info(`Undo: faable deploy waf rm ${undo_args(want)} --action allow -a ${app_id}`);
+        return waf;
+    }
     const answer = action === 'deny' ? '403' : '404';
     log.info(`🛡️  ${describe_selector(want)} → ${answer} at the edge`);
     log.info(`   for ${app_name} (${app_id}).`);

package/dist/commands/deploy/waf/allow.js

@@ -0,0 +1,58 @@
+import { requireApi } from '../../../api/context.js';
+import { print_json, json_option } from '../../../lib/listing.js';
+import { resolve_app_id } from '../resolve_app_id.js';
+import { add_rule } from './add_rule.js';
+
+/**
+ * The one WAF rule that opens instead of closing: paths of THIS app that Faable
+ * blocks for every app (archives, dotfiles, config files) and that this app
+ * really serves — a `.zip` download, say. Path only: a user-agent or query
+ * exception could be claimed by anyone sending that header.
+ */
+const waf_allow = {
+    command: 'allow <pattern>',
+    describe: 'Let a path Faable blocks for every app (e.g. *.zip) reach your app',
+    builder: yargs => json_option(yargs)
+        .positional('pattern', {
+        type: 'string',
+        demandOption: true,
+        description: 'Anchored path regex, e.g. ^/downloads/.*\\.zip$ (quote it in your shell)'
+    })
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App id, name or slug (defaults to the linked app)'
+    })
+        .option('description', {
+        alias: 'd',
+        type: 'string',
+        description: 'Why this rule exists (shown in `waf list`)'
+    })
+        .example("$0 deploy waf allow '^/downloads/.*\\.zip$'", 'Serve the .zip files under /downloads that Faable would otherwise refuse')
+        .epilogue('Faable refuses some paths for every app before they reach it — ' +
+        'archives like .zip or .tar.gz, dotfiles, config files — because ' +
+        'scanners request them by the thousand. If your app really serves ' +
+        'one, allow exactly that path. Keep the pattern narrow: your own ' +
+        'block and sink rules still win over it, and it can never cover ' +
+        '/.well-known/acme-challenge, /.faable or /_next.')
+        .showHelpOnFail(false),
+    handler: async (args) => {
+        const ctx = await requireApi();
+        const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
+        const app = await ctx.api.getApp(app_id);
+        const waf = await add_rule({
+            api: ctx.api,
+            app_id,
+            app_name: app.name,
+            app_url: app.url,
+            pattern: args.pattern,
+            action: 'allow',
+            description: args.description,
+            json: args.json
+        });
+        if (args.json)
+            print_json(waf);
+    }
+};
+
+export { waf_allow };

package/dist/commands/deploy/waf/format.js

@@ -5,7 +5,9 @@ const action_label = (action) => action === 'sink'
         ? '403 (blocked at the edge)'
         : action === 'probe'
             ? 'answered by Faable, app not woken (uptime monitors)'
-            : action;
+            : action === 'allow'
+                ? 'allowed (reaches your app where Faable blocks it for every app)'
+                : action;
 /**
  * Render the effective WAF of an app.
  *

package/dist/commands/deploy/waf/index.js

@@ -1,3 +1,4 @@
+import { waf_allow } from './allow.js';
 import { waf_block } from './block.js';
 import { waf_list } from './list.js';
 import { waf_rm } from './rm.js';
@@ -10,8 +11,9 @@ const waf = {
         .command(waf_list)
         .command(waf_block)
         .command(waf_sink)
+        .command(waf_allow)
         .command(waf_rm)
-        .demandCommand(1, 'Specify a waf command: list, block, sink or rm'),
+        .demandCommand(1, 'Specify a waf command: list, block, sink, allow or rm'),
     handler: () => {
         // Unreachable: demandCommand(1) either routes to a subcommand or fails
         // through the global .fail() in src/index.ts.

package/dist/commands/deploy/waf/rm.js

@@ -27,7 +27,7 @@ const waf_rm = {
     })
         .option('action', {
         type: 'string',
-        choices: ['deny', 'sink'],
+        choices: ['deny', 'sink', 'allow'],
         description: 'Only needed when the same rule exists as both'
     })
         .option('app', {

package/dist/commands/deploy/wait.js

@@ -1,3 +1,5 @@
+import { reachable_timeout_ms, wait_reachable } from './reachable.js';
+
 // The phases a deployment does not leave on its own. READY is the good one.
 const TERMINAL_PHASES = new Set([
     'READY',
@@ -27,8 +29,15 @@ const wait_for_deployment = async (api, deployment_id, opts, deps = {}) => {
                 done: true,
                 ok: phase === 'READY'
             };
-            if (phase === 'READY' && opts.app_url)
+            if (phase === 'READY' && opts.app_url) {
                 result.url = opts.app_url;
+                const check = deps.reachable ??
+                    (reachable_timeout_ms() > 0
+                        ? (url) => wait_reachable(url, reachable_timeout_ms())
+                        : undefined);
+                if (check)
+                    result.reachable = await check(opts.app_url);
+            }
             if (phase !== 'READY' && d?.status?.reason) {
                 result.reason = d.status.reason;
             }

package/dist/mcp/tools.js

@@ -854,6 +854,25 @@ const TOOLS = [
         },
         example: { app: 'web', repo: 'acme/web', branch: 'main' }
     },
+    {
+        name: 'delete_app',
+        title: 'Delete an app',
+        description: "Delete an app, as the dashboard's Delete app does: its deployments, domains and secrets go with it and its URL stops being served. It cannot be undone — confirm with the user which app (get_app) before calling it. Only on the local server with `faable mcp --writes`.",
+        input: { app, project },
+        command: ['deploy', 'apps', 'rm'],
+        flags: a => ['--yes', ...target(a)],
+        write: true,
+        // The hosted server promises its users nothing destructive (the consent
+        // screen and docs/cli.md say so): deleting stays with whoever runs the
+        // MCP on their own machine and passed --writes.
+        local_only: true,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true
+        },
+        example: { app: 'web' }
+    },
     {
         name: 'deploy_directory',
         title: 'Deploy a local directory',

package/package.json

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