@faable/faable 4.10.1 → 4.12.0

package/README.md

@@ -87,6 +87,9 @@ faable login
 faable deploy                       # deploy the current directory (= deploy launch)
 faable deploy launch --app app_x    # deploy another app, from anywhere
 faable deploy apps create --repo acme/web   # create, link, first deploy
+faable deploy --create site --workdir ./public --yes   # a new app from a folder (git or not)
+faable deploy link --app web --repo acme/web      # link a repository to an existing app
+faable deploy apps rm --app app_x   # delete an app (asks first; --yes to skip)
 faable deploy status                # phase, URL and detected stack
 faable deploy logs --build -n 100   # end of the build output (--follow to tail)
 faable deploy traffic --since 7d    # status codes, top and failing paths

package/dist/api/auth.js

@@ -1,5 +1,5 @@
 import { FaableAuthApi, authBearer } from '@faable/auth-sdk';
-import os from 'os';
+import os__default from 'os';
 import { CLI_CLIENT } from './client_id.js';
 
 // The CLI talks to the Faable tenant's auth server through the same SDK the
@@ -40,8 +40,8 @@ const PLATFORM_LABELS = {
 // Human-friendly device name shown on the auth confirm page so the user can
 // recognise which device they are authorising, e.g. "marcs-mbp (macOS)".
 function deviceName() {
-    const platform = PLATFORM_LABELS[os.platform()] || os.platform();
-    return `${os.hostname()} (${platform})`;
+    const platform = PLATFORM_LABELS[os__default.platform()] || os__default.platform();
+    return `${os__default.hostname()} (${platform})`;
 }
 async function getDeviceCode() {
     return anonymous.fetcher.post(`/oauth/device/code`, {

package/dist/api/auth_admin.js

@@ -1,5 +1,5 @@
 import fs from 'fs-extra';
-import os from 'os';
+import os__default from 'os';
 import path__default from 'path';
 import { ContextStore } from '../lib/ContextStore.js';
 import { CredentialsStore } from '../lib/CredentialsStore.js';
@@ -139,7 +139,7 @@ const subject = (token) => {
 };
 class TenantTokenCache {
     file;
-    constructor(file = path__default.join(os.homedir(), '.faable', 'tenant-tokens.json')) {
+    constructor(file = path__default.join(os__default.homedir(), '.faable', 'tenant-tokens.json')) {
         this.file = file;
     }
     async read() {

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

@@ -1,5 +1,6 @@
 import { apps_list } from '../inspect/list.js';
 import { apps_create } from './create.js';
+import { apps_rm } from './rm.js';
 import { apps_set } from './set.js';
 import { status } from '../inspect/status.js';
 
@@ -13,7 +14,8 @@ const apps = {
         .command(apps_get)
         .command(apps_create)
         .command(apps_set)
-        .demandCommand(1, 'Specify an apps command: list, get, create or set'),
+        .command(apps_rm)
+        .demandCommand(1, 'Specify an apps command: list, get, create, set 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/apps/name_free.js

@@ -0,0 +1,21 @@
+import { CliError } from '../../../lib/errors.js';
+import { fetch_page } from '../../../lib/listing.js';
+
+// Before creating an app: is the name free in the project? The api accepts a
+// duplicate, but a second "web" in a project is never what someone retrying
+// meant — it is the app from the last attempt, and from then on `--app web`
+// is ambiguous (arch/deploy/cli-mcp-fallos-2026-10-16-plan.md, F2). The error
+// names the existing app, so the next step is to deploy to it.
+const assert_name_free = async (api, project, name) => {
+    const apps = await fetch_page(p => api.listApps(p, project), {
+        limit: 200,
+        all: true
+    });
+    const wanted = name.toLowerCase();
+    const clash = apps.data.find(a => a.name.toLowerCase() === wanted);
+    if (clash) {
+        throw new CliError('name_taken', `${project} already has an app named "${clash.name}" (${clash.id}). Deploy to it with --app ${clash.id}, or choose another name.`);
+    }
+};
+
+export { assert_name_free };

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

@@ -0,0 +1,55 @@
+import { requireApi } from '../../../api/context.js';
+import { CliError } from '../../../lib/errors.js';
+import { confirm } from '../../../lib/interactive.js';
+import { print_json, json_option } from '../../../lib/listing.js';
+import { log } from '../../../log.js';
+import { resolve_app_ref } from '../resolve_app_id.js';
+
+// `faable deploy apps rm` — delete an app, as the dashboard's «Delete app»
+// does (same endpoint: the api applies the same holds and records who
+// deleted it, `GET /app/:id/deletion`). Before this, a stray app — the empty
+// one a failed `deploy --create` used to leave — could only go from the
+// dashboard (arch/deploy/cli-mcp-fallos-2026-10-16-plan.md, F5).
+//
+// The app is always named: deleting the one this checkout happens to be
+// linked to is not something to infer.
+const apps_rm = {
+    command: 'rm',
+    describe: 'Delete an app: its deployments, domains and secrets go with it',
+    builder: yargs => json_option(yargs)
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App id, name or slug (always explicit)'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .example('$0 deploy apps rm --app app_a1b2c3', 'Delete after confirmation')
+        .showHelpOnFail(false),
+    handler: async (args) => {
+        if (!args.app) {
+            throw new CliError('app_required', 'Say which app to delete: --app <id|name>. It is never taken from the current directory.');
+        }
+        const { api } = await requireApi();
+        const app = await api.getApp(await resolve_app_ref(api, args.app));
+        const go = await confirm({
+            message: `Delete ${app.name} (${app.id})? https://${app.url} stops being served, and its deployments, domains and secrets go with it.`,
+            yes: args.yes
+        });
+        if (!go) {
+            log.info('Cancelled.');
+            return;
+        }
+        await api.deleteApp(app.id, app.team);
+        if (args.json) {
+            return print_json({ deleted: true, id: app.id, name: app.name });
+        }
+        log.info(`🗑️ Deleted ${app.name} (${app.id}).`);
+    }
+};
+
+export { apps_rm };

package/dist/commands/deploy/launch.js

@@ -8,7 +8,9 @@ import { requireProject } from '../../api/project.js';
 import { git_context } from './git_context.js';
 import { show_deploy_help } from './help.js';
 import { propose_release } from './release_version.js';
+import { assert_name_free } from './apps/name_free.js';
 import { deploy_remote } from './remote/index.js';
+import { collect_manifest } from './remote/manifest.js';
 import { find_app_id } from './resolve_app_id.js';
 import { is_superseded } from './superseded.js';
 
@@ -76,186 +78,213 @@ const launch = {
         const ctx = await requireApi(args.app?.startsWith('app_') ? args.app : undefined);
         const { api } = ctx;
         const config = Configuration.instance().deployConfig();
+        // stdout carries the JSON outcome: the build log streams to stderr then.
+        const log_stream = args.json || is_non_interactive() ? process.stderr : process.stdout;
         // --create: a directory with no app yet (the agent's «deploy this folder
         // and give me the URL»). The app is new, so nothing existing is touched.
-        let created_id;
+        // Whatever can fail before the deploy runs first — the source, the name —
+        // and an app that never got a deployment is taken back: a retry must
+        // not leave one empty app per attempt (plan F2, backlog §365).
+        let created;
+        let manifest;
+        let deployment_started = false;
         if (args.create) {
             const { id: project } = await requireProject(api);
-            const created = await api.createApp(project, { name: args.create });
-            created_id = created.id;
-            log.info(`📦 Created ${created.name} (${created.id})`);
+            manifest = await collect_manifest(workdir);
+            await assert_name_free(api, project, args.create);
+            const app = await api.createApp(project, { name: args.create });
+            created = { id: app.id, team: app.team };
+            log.info(`📦 Created ${app.name} (${app.id})`);
         }
-        const app_id = created_id ?? (await find_app_id(args.app, ctx.appId, api, workdir));
-        // Nothing to deploy from here. `faable deploy` is the entry point to the
-        // whole product, so an unlinked directory is a perfectly normal way to
-        // arrive: list what deploy can do (like `faable auth` does) instead of
-        // answering a bare `faable deploy` with an error and nothing else.
-        if (!app_id) {
-            show_deploy_help();
-            throw new CliError('app_required', `No app linked to ${workdir}. Connect a repository from the dashboard (or run "faable deploy link"), or target one with --app <app_id>.`);
-        }
-        const app = await api.getApp(app_id);
-        // Confirm which app/dir is about to go out. Only in a real terminal — CI
-        // (non-TTY) deploys unattended, so pipelines need no changes.
-        if (process.stdout.isTTY &&
-            !(await confirm({
-                message: `Deploy "${app.name}" (${app.id}) from ${workdir}?`,
-                yes: args.yes
-            }))) {
-            log.info('Cancelled.');
-            return;
-        }
-        // Monorepo Root Directory — single precedence rule everywhere
-        // (arch/deploy/root-dir-faable-json.md): App.root_dir (platform
-        // override, exceptional) > repo faable.json rootDir (the supported
-        // user option) > repo root. Matches the remote builder.
-        if (app.root_dir) {
-            config.rootDir = app.root_dir;
-            log.info(`📁 Root directory: ${app.root_dir} (platform override)`);
-        }
-        else if (config.rootDir) {
-            log.info(`📁 Root directory: ${config.rootDir} (from faable.json)`);
-        }
-        // 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 });
-        // Propose the release version (--release > FAABLE_RELEASE > git tag).
-        // Optional: when absent the platform injects no FAABLE_RELEASE and the
-        // app falls back to its own version source.
-        const proposed = await propose_release({ workdir, explicit: args.release });
-        if (proposed) {
-            log.info(`🏷️ Release: ${proposed.release} (from ${proposed.source})`);
-        }
-        // Remote build only (arch/deploy/remote-artifact-default-cutover.md): the
-        // CLI no longer builds — it uploads the source and the platform builds
-        // server-side (framework detection, buildpacks, artifact/image output all
-        // live in the builder). No Docker, no local fallback: a rejected admission
-        // (build_mode=local opt-out, or the global kill-switch off) or a build
-        // error throws and exits red.
-        log.info(`🚀 Deploying "${app.name}" (${app.id})`);
-        const deployment = await deploy_remote({
-            api,
-            app,
-            git,
-            release: proposed?.release,
-            workdir
-        });
-        const dashboard_url = `https://dashboard.faable.com/deploy/${app.team}/app/${app.id}`;
-        log.info(`Preparing to deploy in faable cloud · ${deployment.id}`);
-        log.info(`📊 View it in the dashboard -> ${dashboard_url}`);
-        // Wait (up to 5 minutes) for the deployment to be promoted (live)
-        const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-        const timeoutMs = 5 * 60 * 1000;
-        const intervalMs = 5000;
-        const start = Date.now();
-        log.info(`⏳ Waiting for deployment to be promoted...`);
-        let promoted = false;
-        let failure = null;
-        let superseded = null;
-        // The pointer at wait-start is the PREVIOUS deployment (older than ours)
-        // — only a pointer CHANGE to something that isn't us needs a look.
-        const initialActiveId = app.status?.deployment;
-        while (Date.now() - start < timeoutMs) {
-            await wait(intervalMs);
-            try {
-                const current = await api.getApp(app.id);
-                if (current.status?.deployment === deployment.id) {
-                    promoted = true;
-                    break;
+        const created_id = created?.id;
+        const take_back_created = async () => {
+            if (!created || deployment_started)
+                return;
+            await api.deleteApp(created.id, created.team).then(() => log.info(`🧹 Removed ${created.id}: it never got a deployment`), () => log.warn(`Could not remove ${created.id}, which never got a deployment — delete it from the dashboard.`));
+        };
+        try {
+            const app_id = created_id ?? (await find_app_id(args.app, ctx.appId, api, workdir));
+            // Nothing to deploy from here. `faable deploy` is the entry point to the
+            // whole product, so an unlinked directory is a perfectly normal way to
+            // arrive: list what deploy can do (like `faable auth` does) instead of
+            // answering a bare `faable deploy` with an error and nothing else.
+            if (!app_id) {
+                show_deploy_help();
+                throw new CliError('app_required', `No app linked to ${workdir}. Connect a repository from the dashboard (or run "faable deploy link"), or target one with --app <app_id>.`);
+            }
+            const app = await api.getApp(app_id);
+            // Confirm which app/dir is about to go out. Only in a real terminal — CI
+            // (non-TTY) deploys unattended, so pipelines need no changes.
+            if (process.stdout.isTTY &&
+                !(await confirm({
+                    message: `Deploy "${app.name}" (${app.id}) from ${workdir}?`,
+                    yes: args.yes
+                }))) {
+                await take_back_created();
+                log.info('Cancelled.');
+                return;
+            }
+            // Monorepo Root Directory — single precedence rule everywhere
+            // (arch/deploy/root-dir-faable-json.md): App.root_dir (platform
+            // override, exceptional) > repo faable.json rootDir (the supported
+            // user option) > repo root. Matches the remote builder.
+            if (app.root_dir) {
+                config.rootDir = app.root_dir;
+                log.info(`📁 Root directory: ${app.root_dir} (platform override)`);
+            }
+            else if (config.rootDir) {
+                log.info(`📁 Root directory: ${config.rootDir} (from faable.json)`);
+            }
+            // 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 });
+            // Propose the release version (--release > FAABLE_RELEASE > git tag).
+            // Optional: when absent the platform injects no FAABLE_RELEASE and the
+            // app falls back to its own version source.
+            const proposed = await propose_release({ workdir, explicit: args.release });
+            if (proposed) {
+                log.info(`🏷️ Release: ${proposed.release} (from ${proposed.source})`);
+            }
+            // Remote build only (arch/deploy/remote-artifact-default-cutover.md): the
+            // CLI no longer builds — it uploads the source and the platform builds
+            // server-side (framework detection, buildpacks, artifact/image output all
+            // live in the builder). No Docker, no local fallback: a rejected admission
+            // (build_mode=local opt-out, or the global kill-switch off) or a build
+            // error throws and exits red.
+            log.info(`🚀 Deploying "${app.name}" (${app.id})`);
+            const deployment = await deploy_remote({
+                api,
+                app,
+                git,
+                release: proposed?.release,
+                workdir,
+                manifest,
+                log_stream,
+                on_deployment: () => {
+                    deployment_started = true;
                 }
-                // Superseded: the pointer moved to a deployment at least as new as
-                // ours (twin workflows on the same push, or a rapid follow-up
-                // deploy). It only moves forward — waiting longer can never succeed.
-                const activeId = current.status?.deployment;
-                if (activeId && activeId !== initialActiveId) {
-                    const active = await api.getDeployment(activeId).catch(() => null);
-                    if (active &&
-                        is_superseded(deployment, active)) {
-                        superseded = activeId;
+            });
+            const dashboard_url = `https://dashboard.faable.com/deploy/${app.team}/app/${app.id}`;
+            log.info(`Preparing to deploy in faable cloud · ${deployment.id}`);
+            log.info(`📊 View it in the dashboard -> ${dashboard_url}`);
+            // Wait (up to 5 minutes) for the deployment to be promoted (live)
+            const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+            const timeoutMs = 5 * 60 * 1000;
+            const intervalMs = 5000;
+            const start = Date.now();
+            log.info(`⏳ Waiting for deployment to be promoted...`);
+            let promoted = false;
+            let failure = null;
+            let superseded = null;
+            // The pointer at wait-start is the PREVIOUS deployment (older than ours)
+            // — only a pointer CHANGE to something that isn't us needs a look.
+            const initialActiveId = app.status?.deployment;
+            while (Date.now() - start < timeoutMs) {
+                await wait(intervalMs);
+                try {
+                    const current = await api.getApp(app.id);
+                    if (current.status?.deployment === deployment.id) {
+                        promoted = true;
+                        break;
+                    }
+                    // Superseded: the pointer moved to a deployment at least as new as
+                    // ours (twin workflows on the same push, or a rapid follow-up
+                    // deploy). It only moves forward — waiting longer can never succeed.
+                    const activeId = current.status?.deployment;
+                    if (activeId && activeId !== initialActiveId) {
+                        const active = await api.getDeployment(activeId).catch(() => null);
+                        if (active &&
+                            is_superseded(deployment, active)) {
+                            superseded = activeId;
+                            break;
+                        }
+                    }
+                    // Watch for a terminal runtime failure so we fail fast (and red)
+                    // instead of timing out green. The controller marks a crash-looping
+                    // deployment ERROR — with a reason (e.g. a missing module) — within
+                    // ~1min, long before this 5min promotion timeout.
+                    const dep = await api.getDeployment(deployment.id);
+                    const phase = dep.status?.phase;
+                    if (phase === 'ERROR' || phase === 'BUILD_ERROR') {
+                        failure = { phase, reason: dep.status?.reason };
+                        break;
+                    }
+                    // CANCELED: the platform superseded this build before it produced a
+                    // runnable (a sibling deployment of the app won the promotion).
+                    if (phase === 'CANCELED') {
+                        superseded = dep.status?.reason ?? 'canceled';
                         break;
                     }
                 }
-                // Watch for a terminal runtime failure so we fail fast (and red)
-                // instead of timing out green. The controller marks a crash-looping
-                // deployment ERROR — with a reason (e.g. a missing module) — within
-                // ~1min, long before this 5min promotion timeout.
-                const dep = await api.getDeployment(deployment.id);
-                const phase = dep.status?.phase;
-                if (phase === 'ERROR' || phase === 'BUILD_ERROR') {
-                    failure = { phase, reason: dep.status?.reason };
-                    break;
+                catch (_error) {
+                    // Ignore transient errors while polling and keep waiting
+                    log.debug(`Polling app status failed, retrying...`);
                 }
-                // CANCELED: the platform superseded this build before it produced a
-                // runnable (a sibling deployment of the app won the promotion).
-                if (phase === 'CANCELED') {
-                    superseded = dep.status?.reason ?? 'canceled';
-                    break;
+            }
+            if (args.json) {
+                const outcome = promoted
+                    ? 'live'
+                    : superseded
+                        ? 'superseded'
+                        : failure
+                            ? 'failed'
+                            : 'timeout';
+                const fault = failure
+                    ? await api.getDeploymentFault(deployment.id).catch(() => null)
+                    : null;
+                const result = {
+                    app_id: app.id,
+                    app_name: app.name,
+                    ...(created_id ? { created: true } : {}),
+                    deployment_id: deployment.id,
+                    outcome,
+                    url: `https://${app.url}`,
+                    ...(failure
+                        ? {
+                            phase: failure.phase,
+                            reason: failure.reason,
+                            ...(fault
+                                ? { fault_owner: fault.fault_owner, error_code: fault.error_code }
+                                : {})
+                        }
+                        : {}),
+                    dashboard_url
+                };
+                if (failure) {
+                    // A failed deploy still exits red (CI depends on it); the outcome
+                    // travels in the error so a program reads it without parsing prose.
+                    const err = new CliError('usage', `Deployment ${deployment.id} failed (${failure.phase})${fault?.fault_owner ? ` — ${fault.fault_owner}'s side` : ''}: ${failure.reason ?? 'no reason recorded'}`, { action: JSON.stringify(result) });
+                    // The api's own code when it classified the failure.
+                    err.code = fault?.error_code ?? 'deploy_failed';
+                    throw err;
                 }
+                return print_json(result);
             }
-            catch (_error) {
-                // Ignore transient errors while polling and keep waiting
-                log.debug(`Polling app status failed, retrying...`);
+            if (promoted) {
+                log.info(`🌍 Deployment promoted and live, visit: https://${app.url}`);
             }
-        }
-        if (args.json) {
-            const outcome = promoted
-                ? 'live'
-                : superseded
-                    ? 'superseded'
-                    : failure
-                        ? 'failed'
-                        : 'timeout';
-            const fault = failure
-                ? await api.getDeploymentFault(deployment.id).catch(() => null)
-                : null;
-            const result = {
-                app_id: app.id,
-                app_name: app.name,
-                ...(created_id ? { created: true } : {}),
-                deployment_id: deployment.id,
-                outcome,
-                url: `https://${app.url}`,
-                ...(failure
-                    ? {
-                        phase: failure.phase,
-                        reason: failure.reason,
-                        ...(fault
-                            ? { fault_owner: fault.fault_owner, error_code: fault.error_code }
-                            : {})
-                    }
-                    : {}),
-                dashboard_url
-            };
-            if (failure) {
-                // A failed deploy still exits red (CI depends on it); the outcome
-                // travels in the error so a program reads it without parsing prose.
-                const err = new CliError('usage', `Deployment ${deployment.id} failed (${failure.phase})${fault?.fault_owner ? ` — ${fault.fault_owner}'s side` : ''}: ${failure.reason ?? 'no reason recorded'}`, { action: JSON.stringify(result) });
-                // The api's own code when it classified the failure.
-                err.code = fault?.error_code ?? 'deploy_failed';
-                throw err;
+            else if (superseded) {
+                // Not a failure: the app IS live, just on a sibling deployment (e.g.
+                // duplicated workflows firing on the same push). Green exit — there is
+                // nothing for the user to fix in THIS run.
+                log.warn(`⚠️ Deployment superseded — a newer deployment of this app was promoted (${superseded}). The app is live: https://${app.url}`);
+            }
+            else if (failure) {
+                // Fail the command (non-zero exit → red GitHub Action) and surface the
+                // reason the controller captured so the user sees WHY without digging.
+                log.error(`❌ Deployment failed (${failure.phase}).`);
+                if (failure.reason)
+                    log.error(failure.reason);
+                log.error(`Check the logs in the dashboard -> ${dashboard_url}`);
+                throw new Error(`Deployment ${deployment.id} failed with phase ${failure.phase}`);
+            }
+            else {
+                log.warn(`⌛ Timed out after 5min waiting for promotion. The deployment is still rolling out, check the dashboard -> ${dashboard_url}`);
             }
-            return print_json(result);
-        }
-        if (promoted) {
-            log.info(`🌍 Deployment promoted and live, visit: https://${app.url}`);
-        }
-        else if (superseded) {
-            // Not a failure: the app IS live, just on a sibling deployment (e.g.
-            // duplicated workflows firing on the same push). Green exit — there is
-            // nothing for the user to fix in THIS run.
-            log.warn(`⚠️ Deployment superseded — a newer deployment of this app was promoted (${superseded}). The app is live: https://${app.url}`);
-        }
-        else if (failure) {
-            // Fail the command (non-zero exit → red GitHub Action) and surface the
-            // reason the controller captured so the user sees WHY without digging.
-            log.error(`❌ Deployment failed (${failure.phase}).`);
-            if (failure.reason)
-                log.error(failure.reason);
-            log.error(`Check the logs in the dashboard -> ${dashboard_url}`);
-            throw new Error(`Deployment ${deployment.id} failed with phase ${failure.phase}`);
         }
-        else {
-            log.warn(`⌛ Timed out after 5min waiting for promotion. The deployment is still rolling out, check the dashboard -> ${dashboard_url}`);
+        catch (error) {
+            await take_back_created();
+            throw error;
         }
     }
 };

package/dist/commands/deploy/remote/follow.js

@@ -12,7 +12,12 @@ const wait = (ms) => new Promise((r) => setTimeout(r, ms));
  * (image landed — the regular promotion poll takes over); throws on
  * BUILD_ERROR/ERROR with the server-provided reason.
  */
-const follow_remote_build = async (api, deployment_id) => {
+const follow_remote_build = async (api, deployment_id, 
+// Where the build log goes. stdout for a person; stderr when stdout carries
+// a JSON document (--json, or a program driving the CLI): one build line in
+// front of it and the caller can't parse the outcome — the MCP reported a
+// live deploy as failed that way (arch/deploy/cli-mcp-fallos-2026-10-16-plan.md, F1).
+out = process.stdout) => {
     let printed = 0;
     let last_phase = "";
     const started = Date.now();
@@ -21,7 +26,7 @@ const follow_remote_build = async (api, deployment_id) => {
             const logs = await api.getDeploymentLogs(deployment_id);
             const content = logs?.content ?? "";
             if (content.length > printed) {
-                process.stdout.write(content.slice(printed));
+                out.write(content.slice(printed));
                 printed = content.length;
             }
             else if (content.length < printed) {

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

@@ -1,4 +1,5 @@
 import { log } from '../../../log.js';
+import { format_bytes } from '../inspect/detail.js';
 import { follow_remote_build } from './follow.js';
 import { collect_manifest } from './manifest.js';
 import { upload_missing_blobs } from './upload.js';
@@ -17,8 +18,11 @@ import { upload_missing_blobs } from './upload.js';
 const deploy_remote = async (props) => {
     const { api, app, git, release, workdir } = props;
     log.info(`☁️ Remote build`);
-    const manifest = await collect_manifest(workdir);
-    log.info(`🗂️ ${manifest.length} files in the source manifest`);
+    const manifest = props.manifest ?? (await collect_manifest(workdir));
+    // The total is what the api weighs against the plan when the app's last
+    // build came out too large — say it before anything is uploaded.
+    const total = manifest.reduce((sum, f) => sum + f.size, 0);
+    log.info(`🗂️ ${manifest.length} files in the source manifest (${format_bytes(total)})`);
     await upload_missing_blobs(api, app.id, workdir, manifest);
     // No `plan`: the builder re-detects on the assembled tree and syncs the app's
     // runtime_strategy on completion.
@@ -28,8 +32,9 @@ const deploy_remote = async (props) => {
         ...(release ? { release } : {}),
         ...git,
     });
+    props.on_deployment?.(deployment.id);
     log.info(`Preparing to build in faable cloud · ${deployment.id}`);
-    await follow_remote_build(api, deployment.id);
+    await follow_remote_build(api, deployment.id, props.log_stream);
     return deployment;
 };
 

package/dist/commands/deploy/remote/manifest.js

@@ -1,7 +1,10 @@
+import { execFile } from 'child_process';
 import { createHash } from 'crypto';
-import { lstatSync, readFileSync } from 'fs';
+import { lstatSync, readFileSync, mkdtempSync, rmSync } from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { cmd } from '../../../lib/cmd.js';
+import { log } from '../../../log.js';
 
 // Server-side admission caps (mirror DeploymentSource on the API); checking
 // here fails fast with a clearer message than a 400.
@@ -15,26 +18,24 @@ const MAX_FILE_BYTES = 100 * 1024 * 1024;
  * them like a fresh clone would.
  *
  * Symlinks are rejected (no representation in the manifest by design — see
- * deploy-v2-remote-build.md) and a non-git directory is unsupported (the source
- * tree is collected via git).
+ * deploy-v2-remote-build.md).
+ *
+ * A folder that is not a repository (`faable deploy` on a plain directory, the
+ * MCP's deploy_directory) is collected by git too, through a throwaway index:
+ * see list_without_repo.
  */
 const collect_manifest = async (workdir) => {
-    const inside = await cmd(`git rev-parse --is-inside-work-tree`, {
-        cwd: workdir,
-    }).catch(() => null);
-    if (!inside || String(inside.stdout).trim() !== "true") {
-        throw new Error("Deploys need a git repository (the source tree is collected via git). Initialize one with `git init` and commit your files.");
-    }
+    const in_repo = await is_git_work_tree(workdir);
     // -c/-o: tracked + untracked; --exclude-standard: .gitignore/.git/info.
     // -z: NUL-separated (paths with spaces/UTF-8 survive).
-    const out = await cmd(`git ls-files -co --exclude-standard -z`, {
-        cwd: workdir,
-    });
-    const rel_paths = String(out.stdout)
-        .split("\0")
-        .filter((p) => p.length > 0);
+    const rel_paths = in_repo
+        ? split_z((await cmd(`git ls-files -co --exclude-standard -z`, { cwd: workdir }))
+            .stdout)
+        : await list_without_repo(workdir);
     if (rel_paths.length === 0) {
-        throw new Error("No files to upload (empty git tree?)");
+        throw new Error(in_repo
+            ? "No files to upload (empty git tree?)"
+            : `No files to upload in ${workdir}.`);
     }
     if (rel_paths.length > MAX_FILES) {
         throw new Error(`Too many files for a remote build (${rel_paths.length} > ${MAX_FILES}).`);
@@ -73,5 +74,39 @@ const collect_manifest = async (workdir) => {
     }
     return manifest;
 };
+// Outside a repository git exits 128 with `fatal: not a git repository`:
+// that is the answer here, not an error to show — so not through cmd(), which
+// logs a failing command's stderr and exit code.
+const is_git_work_tree = (workdir) => new Promise((resolve) => {
+    execFile("git", ["rev-parse", "--is-inside-work-tree"], { cwd: workdir }, (err, stdout) => resolve(!err && String(stdout).trim() === "true"));
+});
+const split_z = (out) => String(out)
+    .split("\0")
+    .filter((p) => p.length > 0);
+const shell_quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+// Out of an upload even when no .gitignore says so — a plain folder has none,
+// and these are the files a repository would have ignored anyway.
+const NO_REPO_EXCLUDES = ["node_modules/", ".env", ".env.*", ".DS_Store"];
+/**
+ * The files of a folder that is not a git repository. Git still lists them:
+ * a temporary repository holds the index and the folder is its work tree, so
+ * every .gitignore inside counts exactly as it would in a clone, and nothing
+ * is written to the folder (arch/deploy/cli-mcp-fallos-2026-10-16-plan.md, F3).
+ */
+const list_without_repo = async (workdir) => {
+    const git_dir = mkdtempSync(path.join(os.tmpdir(), "faable-manifest-"));
+    try {
+        await cmd(`git init -q ${shell_quote(git_dir)}`).catch(() => {
+            throw new Error("Deploys collect the source with git, and git is not available. Install git and try again.");
+        });
+        log.info(`📂 ${workdir} is not a git repository: uploading the folder (its .gitignore files apply; ${NO_REPO_EXCLUDES.join(", ")} stay out)`);
+        const excludes = NO_REPO_EXCLUDES.map((p) => `-x ${shell_quote(p)}`).join(" ");
+        const out = await cmd(`git --git-dir=${shell_quote(path.join(git_dir, ".git"))} --work-tree=${shell_quote(workdir)} ls-files -o --exclude-standard ${excludes} -z`, { cwd: workdir });
+        return split_z(out.stdout);
+    }
+    finally {
+        rmSync(git_dir, { recursive: true, force: true });
+    }
+};
 
-export { collect_manifest };
+export { NO_REPO_EXCLUDES, collect_manifest };

package/dist/commands/link/index.js

@@ -2,6 +2,11 @@ import { requireApi } from '../../api/context.js';
 import prompts from 'prompts';
 import { log } from '../../log.js';
 import { getGitRemoteUrl } from '../../lib/git_remote.js';
+import { CliError } from '../../lib/errors.js';
+import { is_non_interactive } from '../../lib/interactive.js';
+import { print_json } from '../../lib/listing.js';
+import { parse_repo } from '../deploy/apps/create.js';
+import { resolve_app_ref } from '../deploy/resolve_app_id.js';
 
 const DEPLOY_DOCS_URL = "https://faable.com/docs/deploy/github-actions";
 const link = {
@@ -14,9 +19,33 @@ const link = {
             type: "string",
             description: "Working directory",
         })
+            .option("app", {
+            alias: "a",
+            type: "string",
+            description: "App id, name or slug to link (no list to pick from: what a script or agent uses)",
+        })
+            .option("repo", {
+            alias: "r",
+            type: "string",
+            description: "GitHub repository, owner/repo or its URL (defaults to the origin remote of --workdir)",
+        })
+            .option("branch", {
+            alias: "b",
+            type: "string",
+            description: "Branch to deploy (defaults to the repository default)",
+        })
+            .option("json", {
+            type: "boolean",
+            default: false,
+            description: "Print the link as JSON: app, repository, branch and how it deploys",
+        })
+            .example("$0 deploy link --app web --repo acme/web", "Link acme/web to the app web: from now on a push deploys it")
             .showHelpOnFail(false);
     },
     handler: async (args) => {
+        if (args.app || args.json || is_non_interactive()) {
+            return link_to_app(args);
+        }
         const workdir = args.workdir || process.cwd();
         // `faable link <app_id>` is deprecated. Linking is now fully interactive and
         // the repository is auto-detected from the current folder — users never need
@@ -113,6 +142,54 @@ const link = {
         }
     },
 };
+// `link --app`: the app is named, so nothing is asked. What a script or an
+// agent runs — the picker above needs a person, and the MCP could not link a
+// repository to an existing app at all (arch/deploy/cli-mcp-fallos-2026-10-16-plan.md,
+// F4; backlog §366). Driven by a program, the repository is spelled out too:
+// the origin remote of whatever directory the process runs in is a guess.
+const link_to_app = async (args) => {
+    if (!args.app) {
+        throw new CliError("app_required", "Say which app to link: --app <id|name>. Without a terminal there is no list to pick from.");
+    }
+    const repository = args.repo
+        ? parse_repo(args.repo)
+        : is_non_interactive()
+            ? undefined
+            : await getGitRemoteUrl(args.workdir || process.cwd());
+    if (!repository) {
+        throw new CliError("usage", is_non_interactive()
+            ? "Say which repository to link: --repo owner/repo."
+            : "No GitHub origin remote here: pass --repo owner/repo.");
+    }
+    const { api } = await requireApi();
+    const app = await api.getApp(await resolve_app_ref(api, args.app));
+    let linked;
+    try {
+        linked = await api.linkRepository(app.id, { repository, ...(args.branch ? { github_branch: args.branch } : {}) }, app.team);
+    }
+    catch (err) {
+        const e = err;
+        const failed = new CliError("usage", `Could not link ${repository} to ${app.name}: ${e.message}`, { status: e.status, action: e.action, cause: err });
+        // The api's reason (github_installation_missing,
+        // github_repository_not_found…) says what to fix.
+        if (e.code)
+            failed.code = e.code;
+        throw failed;
+    }
+    const result = {
+        app_id: app.id,
+        app_name: app.name,
+        repository: linked?.repository ?? repository,
+        branch: linked?.github_branch,
+        deploy_trigger: linked?.deploy_trigger,
+    };
+    if (args.json)
+        return print_json(result);
+    log.info(`Linked ${result.repository} to ${app.name} (${app.id}).`);
+    log.info(result.deploy_trigger === "webhook"
+        ? `Push to deploy is on: the next push to "${result.branch ?? "the default branch"}" deploys. What is live now stays until then.`
+        : `This repository has its own Faable deploy workflow — pushes keep deploying through it. Docs: ${DEPLOY_DOCS_URL}`);
+};
 // Top-level `faable link` predates the per-product layout (`faable deploy link`).
 // Kept as a hidden alias so existing docs/scripts don't break; remove in a
 // future major.

package/dist/lib/ContextStore.js

@@ -1,10 +1,10 @@
 import fs from 'fs-extra';
-import os from 'os';
+import os__default from 'os';
 import path__default from 'path';
 
 class ContextStore {
     faable_home;
-    constructor(faable_home = path__default.join(os.homedir(), '.faable')) {
+    constructor(faable_home = path__default.join(os__default.homedir(), '.faable')) {
         this.faable_home = faable_home;
     }
     get path() {

package/dist/lib/CredentialsStore.js

@@ -1,5 +1,5 @@
 import fs from 'fs-extra';
-import os from 'os';
+import os__default from 'os';
 import path__default from 'path';
 import { log } from '../log.js';
 
@@ -8,7 +8,7 @@ class CredentialsStore {
     faable_home;
     constructor(log$1 = log) {
         this.log = log$1;
-        this.faable_home = path__default.join(os.homedir(), '.faable');
+        this.faable_home = path__default.join(os__default.homedir(), '.faable');
     }
     async deleteCredentials() {
         if (fs.existsSync(this.credentials_path)) {

package/dist/lib/UpdateChecker.js

@@ -1,6 +1,6 @@
 import { spawn } from 'child_process';
 import fs from 'fs-extra';
-import os from 'os';
+import os__default from 'os';
 import path__default from 'path';
 import { log } from '../log.js';
 
@@ -10,7 +10,7 @@ const PACKUMENT_URL = `https://registry.npmjs.org/${CLI_PACKAGE.replace("/", "%2
 // Hitting the registry at most once a day keeps the background refresh rare.
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const UPGRADE_FETCH_TIMEOUT_MS = 10_000;
-const cache_path = () => path__default.join(os.homedir(), ".faable", "update-check.json");
+const cache_path = () => path__default.join(os__default.homedir(), ".faable", "update-check.json");
 // Local dev runs with the semantic-release placeholder version.
 const isDevBuild = (version) => version.startsWith("0.0.0");
 const isCacheStale = (cache, now) => {

package/dist/mcp/run_cli.js

@@ -34,6 +34,31 @@ const portable_exec_argv = (exec_argv = process.execArgv, resolve = resolve_load
 };
 // The last JSON line on stderr is the error document; anything before it is
 // the CLI's own log lines.
+// The command's JSON document on stdout. Normally stdout IS the document; if
+// a stray line got in front of it (a build log once did, and a deploy that
+// went fine came back as an error — arch/deploy/cli-mcp-fallos-2026-10-16-plan.md,
+// F1), the document is still the last thing printed: try each line that
+// opens one at column 0, from the end, through to the end of the output.
+const parse_output = (stdout) => {
+    try {
+        return { ok: true, data: JSON.parse(stdout) };
+    }
+    catch {
+        // look for the document after the stray lines
+    }
+    const lines = stdout.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (!/^[[{]/.test(lines[i]))
+            continue;
+        try {
+            return { ok: true, data: JSON.parse(lines.slice(i).join('\n')) };
+        }
+        catch {
+            // not where the document starts: keep going up
+        }
+    }
+    return { ok: false };
+};
 const parse_error = (stderr, code) => {
     const lines = stderr.trim().split('\n').reverse();
     for (const line of lines) {
@@ -89,18 +114,16 @@ const run_cli = (args, opts = {}) => new Promise(resolve => {
         clearTimeout(timer);
         if (code !== 0)
             return resolve({ ok: false, error: parse_error(stderr, code) });
-        try {
-            resolve({ ok: true, data: JSON.parse(stdout) });
-        }
-        catch {
-            resolve({
+        const parsed = parse_output(stdout);
+        resolve(parsed.ok
+            ? { ok: true, data: parsed.data }
+            : {
                 ok: false,
                 error: {
                     message: `faable printed something that is not JSON: ${stdout.slice(0, 200)}`
                 }
             });
-        }
     });
 });
 
-export { portable_exec_argv, run_cli };
+export { parse_output, portable_exec_argv, run_cli };

package/dist/mcp/tools.js

@@ -826,10 +826,38 @@ const TOOLS = [
             mode: 'push'
         }
     },
+    {
+        name: 'link_repo',
+        title: 'Link a repository to an app',
+        description: "Link a GitHub repository to an app that already exists, so a push deploys it (for a new app, create_app does both). What is live keeps serving until the next push — linking starts no deploy. Needs the Faable GitHub App installed on the repository; if not, the error says what to fix.",
+        input: {
+            app,
+            repo: z.string().describe('GitHub repository, owner/repo'),
+            branch: z
+                .string()
+                .optional()
+                .describe('Branch to deploy (defaults to the repository default)'),
+            project
+        },
+        command: ['deploy', 'link'],
+        flags: a => [
+            '--repo',
+            a.repo,
+            ...opt('--branch', a.branch),
+            ...target(a)
+        ],
+        write: true,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true
+        },
+        example: { app: 'web', repo: 'acme/web', branch: 'main' }
+    },
     {
         name: 'deploy_directory',
         title: 'Deploy a local directory',
-        description: "Upload a directory of this machine and deploy it (`faable deploy`): Faable builds it and serves it. Pass `app` to deploy to an existing app, or `create` to make a new one with that name. Waits until it is live and returns the URL — or why it failed and whether that is the user's code (`user`) or Faable (`platform`). Only on the local server (`npx @faable/faable mcp`). Prefer create_app/deploy_app when the code is on GitHub: a push then deploys on its own.",
+        description: "Upload a directory of this machine and deploy it (`faable deploy`): Faable builds it and serves it. Any folder works, a git repository or not — in a plain folder its .gitignore files apply, and node_modules and .env files stay out. Pass `app` to deploy to an existing app, or `create` to make a new one with that name: a name already used in the project is refused (deploy to that app instead), and if the deploy cannot start the new app is removed, so a retry never leaves an empty one. Waits until it is live and returns the URL — or why it failed and whether that is the user's code (`user`) or Faable (`platform`). Only on the local server (`npx @faable/faable mcp`). Prefer create_app/deploy_app when the code is on GitHub: a push then deploys on its own.",
         input: {
             workdir: z
                 .string()

package/package.json

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