@faable/faable 1.26.1 → 1.28.0

package/dist/api/FaableApi.js

@@ -169,6 +169,30 @@ class FaableApi {
     async getMe() {
         return data(this.client.get(`/auth/me`));
     }
+    // Domains are team-scoped rows; a CLI user token carries no default team,
+    // so every call pins the app's team via `x-faable-team` (same pattern as
+    // createSecretsBatch).
+    async listDomains(app_id, team) {
+        return firstPage(data(this.client.get(`/domain`, {
+            params: { app_id },
+            headers: { "x-faable-team": team },
+        })));
+    }
+    async createDomain(team, params) {
+        return data(this.client.post(`/domain`, params, {
+            headers: { "x-faable-team": team },
+        }));
+    }
+    async getDomain(domain_id, team) {
+        return data(this.client.get(`/domain/${domain_id}`, {
+            headers: { "x-faable-team": team },
+        }));
+    }
+    async deleteDomain(domain_id, team) {
+        return data(this.client.delete(`/domain/${domain_id}`, {
+            headers: { "x-faable-team": team },
+        }));
+    }
 }
 
 export { FaableApi };

package/dist/commands/deploy/domains/add.js

@@ -0,0 +1,46 @@
+import { requireApi } from '../../../api/context.js';
+import { log } from '../../../log.js';
+import { resolve_app_id } from '../resolve_app_id.js';
+import { cname_target } from './format.js';
+
+const domains_add = {
+    command: 'add <fqdn>',
+    describe: 'Add a custom domain to the app',
+    builder: yargs => yargs
+        .positional('fqdn', {
+        type: 'string',
+        demandOption: true,
+        description: 'Fully qualified domain name (e.g. www.example.com)'
+    })
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App Identifier (defaults to the linked app)'
+    })
+        .option('tls', {
+        type: 'boolean',
+        default: true,
+        description: 'Provision a TLS certificate automatically (default)'
+    })
+        .example('$0 deploy domains add www.example.com', 'Attach www.example.com to the linked app')
+        .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 domain = await ctx.api.createDomain(app.team, {
+            fqdn: args.fqdn,
+            app_id,
+            tls: args.tls
+        });
+        log.info(`🌐 Domain ${domain.fqdn} added to ${app.name} (${app_id}).`);
+        log.info(``);
+        log.info(`Now create a CNAME record at your DNS provider:`);
+        log.info(`  ${domain.fqdn} → ${cname_target(domain)}`);
+        log.info(``);
+        log.info(`Faable verifies the record automatically once DNS propagates${args.tls ? ' and then provisions the TLS certificate' : ''}.`);
+        log.info(`Track it with: faable deploy domains check ${domain.fqdn}`);
+    }
+};
+
+export { domains_add };

package/dist/commands/deploy/domains/check.js

@@ -0,0 +1,51 @@
+import { requireApi } from '../../../api/context.js';
+import { log } from '../../../log.js';
+import { resolve_app_id } from '../resolve_app_id.js';
+import { find_by_fqdn, dns_badge, cname_target } from './format.js';
+
+const domains_check = {
+    command: 'check <fqdn>',
+    describe: 'Show the DNS verification status of a domain',
+    builder: yargs => yargs
+        .positional('fqdn', {
+        type: 'string',
+        demandOption: true,
+        description: 'Domain to check'
+    })
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App Identifier (defaults to the linked app)'
+    })
+        .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 domains = await ctx.api.listDomains(app_id, app.team);
+        const domain = find_by_fqdn(domains, args.fqdn);
+        if (!domain) {
+            throw new Error(`Domain ${args.fqdn} is not attached to ${app_id}. List them with "faable deploy domains list".`);
+        }
+        const status = domain.status;
+        log.info(`🌐 ${domain.fqdn} — ${dns_badge(domain)}`);
+        log.info(`  Expected CNAME: ${domain.fqdn} → ${cname_target(domain)}`);
+        if (status?.dns_observed?.length) {
+            log.info(`  Observed:       ${status.dns_observed.join(', ')}`);
+        }
+        else {
+            log.info(`  Observed:       (no CNAME resolved yet)`);
+        }
+        if (status?.dns_message) {
+            log.info(`  Diagnostic:     ${status.dns_message}`);
+        }
+        if (status?.dns_checked_at) {
+            log.info(`  Last checked:   ${status.dns_checked_at}`);
+        }
+        if (!domain.verified) {
+            log.info(`Faable re-checks automatically — no action needed beyond the CNAME record.`);
+        }
+    }
+};
+
+export { domains_check };

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

@@ -0,0 +1,24 @@
+// Human summary of a domain's verification state, derived from the DNS
+// verification worker's status. Kept pure for tests.
+const dns_badge = (domain) => {
+    if (domain.verified)
+        return '✅ verified';
+    switch (domain.status?.dns_state) {
+        case 'ok':
+            return '✅ dns ok';
+        case 'misconfigured':
+            return '❌ misconfigured';
+        case 'error':
+            return '❌ dns error';
+        default:
+            return '⏳ pending verification';
+    }
+};
+// The CNAME target the user must configure. The API publishes it in
+// `status.dns_expected` (the dashboard shows `<domain.id>.faable.link` — same
+// value); fall back to deriving it from the id so `add` can print
+// instructions even before the first DNS check populates the status.
+const cname_target = (domain) => domain.status?.dns_expected?.[0] ?? `${domain.id}.faable.link`;
+const find_by_fqdn = (domains, fqdn) => domains.find(d => d.fqdn.toLowerCase() === fqdn.toLowerCase());
+
+export { cname_target, dns_badge, find_by_fqdn };

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

@@ -0,0 +1,21 @@
+import { domains_add } from './add.js';
+import { domains_check } from './check.js';
+import { domains_list } from './list.js';
+import { domains_rm } from './rm.js';
+
+const domains = {
+    command: 'domains <command>',
+    describe: 'Manage custom domains of an app',
+    builder: yargs => yargs
+        .command(domains_list)
+        .command(domains_add)
+        .command(domains_check)
+        .command(domains_rm)
+        .demandCommand(1, 'Specify a domains command: list, add, check or rm'),
+    handler: () => {
+        // Unreachable: demandCommand(1) either routes to a subcommand or fails
+        // through the global .fail() in src/index.ts.
+    }
+};
+
+export { domains };

package/dist/commands/deploy/domains/list.js

@@ -0,0 +1,45 @@
+import { requireApi } from '../../../api/context.js';
+import { log } from '../../../log.js';
+import { resolve_app_id } from '../resolve_app_id.js';
+import { dns_badge, cname_target } from './format.js';
+
+const domains_list = {
+    command: 'list',
+    describe: 'List custom domains of the app',
+    builder: yargs => yargs
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App Identifier (defaults to the linked app)'
+    })
+        .example('$0 deploy domains list', 'Domains of the linked app')
+        .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 domains = await ctx.api.listDomains(app_id, app.team);
+        if (domains.length === 0) {
+            log.info(`🌐 No custom domains for ${app.name} (${app_id}).`);
+            log.info(`Add one with: faable deploy domains add <yourdomain.com>. The app is always live at https://${app.url}.`);
+            return;
+        }
+        log.info(`🌐 ${domains.length} domain(s) for ${app.name} (${app_id}):`);
+        const width = Math.max(...domains.map(d => d.fqdn.length));
+        for (const domain of domains) {
+            const tls = domain.tls ? 'tls' : 'no-tls';
+            log.info(`  ${domain.fqdn.padEnd(width)}  ${dns_badge(domain)}  (${tls})`);
+        }
+        const unverified = domains.filter(d => !d.verified);
+        if (unverified.length > 0) {
+            log.info(``);
+            log.info(`To finish verification, point each domain at Faable with a CNAME:`);
+            for (const domain of unverified) {
+                log.info(`  ${domain.fqdn} → ${cname_target(domain)}`);
+            }
+            log.info(`Run "faable deploy domains check <fqdn>" to see the diagnostic.`);
+        }
+    }
+};
+
+export { domains_list };

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

@@ -0,0 +1,59 @@
+import prompts from 'prompts';
+import { requireApi } from '../../../api/context.js';
+import { log } from '../../../log.js';
+import { resolve_app_id } from '../resolve_app_id.js';
+import { find_by_fqdn } from './format.js';
+
+const domains_rm = {
+    command: 'rm <fqdn>',
+    describe: 'Remove a custom domain from the app',
+    builder: yargs => yargs
+        .positional('fqdn', {
+        type: 'string',
+        demandOption: true,
+        description: 'Domain to remove'
+    })
+        .option('app', {
+        alias: 'a',
+        type: 'string',
+        description: 'App Identifier (defaults to the linked app)'
+    })
+        .option('yes', {
+        alias: 'y',
+        type: 'boolean',
+        default: false,
+        description: 'Skip the confirmation prompt'
+    })
+        .example('$0 deploy domains rm www.example.com', 'Detach after confirmation')
+        .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 domains = await ctx.api.listDomains(app_id, app.team);
+        const domain = find_by_fqdn(domains, args.fqdn);
+        if (!domain) {
+            throw new Error(`Domain ${args.fqdn} is not attached to ${app_id}. List them with "faable deploy domains list".`);
+        }
+        if (!args.yes) {
+            // In a non-TTY run without --yes, prompts resolves undefined → cancel.
+            const { confirm } = await prompts({
+                type: 'toggle',
+                name: 'confirm',
+                message: `Remove domain "${domain.fqdn}" from ${app.name} (${app_id})? Traffic to it will stop being served.`,
+                initial: false,
+                active: 'yes',
+                inactive: 'no'
+            });
+            if (!confirm) {
+                log.info('Cancelled.');
+                return;
+            }
+        }
+        await ctx.api.deleteDomain(domain.id, app.team);
+        log.info(`🗑️ Removed domain ${domain.fqdn} from ${app_id}.`);
+        log.info(`The app stays live at https://${app.url}. Remember to delete the CNAME at your DNS provider.`);
+    }
+};
+
+export { domains_rm };

package/dist/commands/deploy/index.js

@@ -2,6 +2,7 @@ import { requireApi } from '../../api/context.js';
 import { Configuration } from '../../lib/Configuration.js';
 import { log } from '../../log.js';
 import { link } from '../link/index.js';
+import { domains } from './domains/index.js';
 import { git_context } from './git_context.js';
 import { propose_release } from './release_version.js';
 import { deploy_remote } from './remote/index.js';
@@ -17,6 +18,7 @@ const deploy = {
         // app_id positional, so `faable deploy <app_id>` keeps working).
         return yargs
             .command(secrets)
+            .command(domains)
             .command(link)
             .positional('app_id', {
             type: 'string',
@@ -42,12 +44,16 @@ const deploy = {
         const config = Configuration.instance().deployConfig();
         const app_id = await resolve_app_id(args.app_id, ctx.appId, api, workdir);
         const app = await api.getApp(app_id);
-        // Monorepo Root Directory: the server is the source of truth
-        // (App.root_dir), so no repo config file is needed. A local
-        // faable.json rootDir (dev override) still wins if set.
-        if (!config.rootDir && app.root_dir) {
+        // 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(`📁 Monorepo root directory (from app): ${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).

package/package.json

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