@faable/faable 4.44.0 → 4.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,9 @@ import { requireProject } from '../../api/project.js';
3
3
  import { CliError } from '../../lib/errors.js';
4
4
  import { print_json, json_option } from '../../lib/listing.js';
5
5
  import { log } from '../../log.js';
6
- import { catalog_lines, parse_inputs, missing_fields, wait_for_installation } from './install_lib.js';
6
+ import { acme_record, cname_target } from './domains/format.js';
7
+ import { catalog_lines, parse_inputs, missing_fields, app_name_from_title, domain_problem, wait_for_installation } from './install_lib.js';
8
+ import { reachable_timeout_ms, wait_reachable } from './reachable.js';
7
9
 
8
10
  // `faable deploy install wordpress` — the dashboard's «Install an app»:
9
11
  // installs an app of the Faable catalogue in the project (its App, a Volume
@@ -20,7 +22,7 @@ const install = {
20
22
  .option('name', {
21
23
  alias: 'n',
22
24
  type: 'string',
23
- description: 'Name of the app it creates (lowercase, digits and dashes)'
25
+ description: 'Name of the app it creates (lowercase, digits and dashes); defaults to the site title as a slug'
24
26
  })
25
27
  .option('input', {
26
28
  alias: 'i',
@@ -31,6 +33,10 @@ const install = {
31
33
  .option('tier', {
32
34
  type: 'string',
33
35
  description: "Database tier (db-s, db-m); defaults to the plan's"
36
+ })
37
+ .option('domain', {
38
+ type: 'string',
39
+ description: 'Production domain of the site (e.g. www.example.com), besides its faable.link address; you configure its DNS'
34
40
  })
35
41
  .option('wait', {
36
42
  type: 'boolean',
@@ -43,7 +49,8 @@ const install = {
43
49
  description: 'With --wait: give up waiting after this many seconds'
44
50
  })
45
51
  .example('$0 deploy install', 'List the apps you can install')
46
- .example('$0 deploy install wordpress --name blog --input title="My blog" --input admin_email=me@example.com --wait', 'Install WordPress as "blog" and wait until it is ready')
52
+ .example('$0 deploy install wordpress --input title="My blog" --wait', 'Install WordPress (you are its admin) and wait until it is ready')
53
+ .example('$0 deploy install wordpress --input title="My blog" --domain www.example.com', 'Install it on your own domain; it prints the DNS record to create')
47
54
  .showHelpOnFail(false),
48
55
  handler: async (args) => {
49
56
  const { api } = await requireApi();
@@ -65,21 +72,29 @@ const install = {
65
72
  if (!bp) {
66
73
  throw new CliError('usage', `"${args.app}" is not in the catalogue. Available: ${catalog.map(b => b.slug).join(', ') || 'none'}.`);
67
74
  }
68
- if (!args.name) {
69
- throw new CliError('usage', `Give the app a name: faable deploy install ${bp.slug} --name <name>.`);
70
- }
71
75
  const inputs = parse_inputs(args.input);
72
76
  const missing = missing_fields(bp, inputs);
73
77
  if (missing.length) {
74
78
  throw new CliError('usage', `${bp.name} also needs: ${missing.map(f => `--input ${f.name}=… (${f.label})`).join(', ')}.`);
75
79
  }
80
+ // The app is the site's container: named after its title unless asked.
81
+ const name = args.name ??
82
+ (inputs.title ? app_name_from_title(inputs.title) : undefined);
83
+ if (!name) {
84
+ throw new CliError('usage', `Give the app a name: faable deploy install ${bp.slug} --name <name>.`);
85
+ }
86
+ const fqdn = args.domain?.trim().toLowerCase() || undefined;
87
+ const bad = fqdn ? domain_problem(fqdn) : null;
88
+ if (bad)
89
+ throw new CliError('usage', bad);
76
90
  const { id: project } = await requireProject(api);
77
91
  let inst;
78
92
  try {
79
93
  inst = await api.createInstallation(project, {
80
94
  blueprint: bp.slug,
81
- name: args.name,
95
+ name,
82
96
  ...(args.tier ? { tier: args.tier } : {}),
97
+ ...(fqdn ? { domain: fqdn } : {}),
83
98
  ...(Object.keys(inputs).length ? { inputs } : {})
84
99
  });
85
100
  }
@@ -93,21 +108,60 @@ const install = {
93
108
  throw err;
94
109
  }
95
110
  log.info(`📦 Installing ${bp.name} as ${inst.name} (${inst.id})`);
111
+ // The domain is created with the installation: its DNS is the user's, and
112
+ // the site does not load on it until it points here (§548).
113
+ const domain = inst.domain_id
114
+ ? await api.getDomain(inst.domain_id, inst.team).catch(() => undefined)
115
+ : undefined;
116
+ const dns = domain
117
+ ? {
118
+ fqdn: domain.fqdn,
119
+ expected_cname: cname_target(domain),
120
+ prevalidation_cname: acme_record(domain)
121
+ }
122
+ : undefined;
123
+ if (dns && !args.json) {
124
+ log.info(``);
125
+ log.info(`🌐 The site lives on ${dns.fqdn}. Configure its DNS — until it points at Faable, the site does not load there:`);
126
+ log.info(` ${dns.fqdn} CNAME → ${dns.expected_cname}`);
127
+ log.info(` A bare domain (example.com) takes an ALIAS instead, where your provider has it: https://faable.com/docs/deploy/domains/apex`);
128
+ log.info(` Optional, to issue its certificate first: ${dns.prevalidation_cname.name} CNAME → ${dns.prevalidation_cname.target}`);
129
+ log.info(`Track it with: faable deploy domains check ${dns.fqdn}`);
130
+ log.info(``);
131
+ }
96
132
  let waited;
97
133
  let url;
98
134
  if (args.wait) {
99
135
  waited = await wait_for_installation(api, inst, {
100
136
  timeout_s: args.timeout ?? 900
101
137
  });
102
- if (waited.ok && inst.app_id) {
138
+ if (waited.ok && dns) {
139
+ // WordPress lives on the domain (its faable.link address redirects
140
+ // there), which answers once its DNS is in place: nothing to probe.
141
+ url = `https://${dns.fqdn}`;
142
+ }
143
+ else if (waited.ok && inst.app_id) {
103
144
  url = await api
104
145
  .getApp(inst.app_id)
105
146
  .then(a => (a.url ? `https://${a.url}` : undefined))
106
147
  .catch(() => undefined);
107
148
  }
149
+ // Ready on the platform is not yet a URL that answers: the edge takes
150
+ // a minute or two to route a new app, and its "app not found" is
151
+ // cached for 120 s — the URL right away would look broken (17-11,
152
+ // wp-catalog-canary). Same check as a deploy's (reachable.ts, F9).
153
+ if (waited.ok && url && !dns) {
154
+ const timeout = reachable_timeout_ms();
155
+ if (timeout > 0)
156
+ waited.reachable = await wait_reachable(url, timeout);
157
+ }
108
158
  if (!args.json) {
109
159
  log.info(waited.ok
110
- ? `✅ Ready${url ? `: ${url}` : ''}`
160
+ ? waited.reachable === false
161
+ ? `✅ Ready${url ? `: ${url}` : ''} — the address may take another minute to answer`
162
+ : dns
163
+ ? `✅ Ready: ${url} — once its DNS points at Faable`
164
+ : `✅ Ready${url ? `: ${url}` : ''}`
111
165
  : waited.done
112
166
  ? `❌ The installation failed: ${waited.error ?? 'see the dashboard'}`
113
167
  : `⏳ Still ${waited.state} after ${args.timeout}s — it goes on; check it in the dashboard`);
@@ -116,6 +170,7 @@ const install = {
116
170
  if (args.json) {
117
171
  return print_json({
118
172
  installation: inst,
173
+ ...(dns ? { dns } : {}),
119
174
  ...(waited ? { result: { ...waited, ...(url ? { url } : {}) } } : {})
120
175
  });
121
176
  }
@@ -48,5 +48,39 @@ const wait_for_installation = async (api, inst, opts) => {
48
48
  await sleep(opts.poll_ms ?? 5000);
49
49
  }
50
50
  };
51
+ /**
52
+ * The app's name when `--name` is not given: the site title as a slug, as the
53
+ * dashboard derives it ("Café & Co." → cafe-co). The app's address adds a
54
+ * random suffix, so two sites with the same title do not clash.
55
+ */
56
+ const app_name_from_title = (title) => {
57
+ const slug = title
58
+ .normalize('NFD')
59
+ .replace(/[̀-ͯ]/g, '')
60
+ .toLowerCase()
61
+ .replace(/[^a-z0-9]+/g, '-')
62
+ .replace(/^-+/, '')
63
+ .slice(0, 50)
64
+ .replace(/-+$/, '');
65
+ if (slug.length >= 3)
66
+ return slug;
67
+ return slug ? `${slug}-site` : 'site';
68
+ };
69
+ // Same rule as the api's (deploy/domain/Domain.model.ts isValidFqdn).
70
+ const FQDN = /^(?=.{4,253}$)((?!-)[a-z0-9-]{1,63}(?<!-)\.)+[a-z]{2,}$/i;
71
+ const RESERVED = ['faable.link', 'faable.com'];
72
+ /**
73
+ * What is wrong with `--domain`, before anything is created; null when it is
74
+ * fine. The api checks it again (and that no other project has it).
75
+ */
76
+ const domain_problem = (fqdn) => {
77
+ if (!FQDN.test(fqdn)) {
78
+ return `--domain ${fqdn}: give the hostname on its own, like www.example.com — no https:// or path.`;
79
+ }
80
+ if (RESERVED.some(r => fqdn === r || fqdn.endsWith(`.${r}`))) {
81
+ return `--domain ${fqdn}: addresses under faable.link and faable.com are assigned by Faable — the site gets one anyway.`;
82
+ }
83
+ return null;
84
+ };
51
85
 
52
- export { catalog_lines, missing_fields, parse_inputs, wait_for_installation };
86
+ export { app_name_from_title, catalog_lines, domain_problem, missing_fields, parse_inputs, wait_for_installation };
package/dist/mcp/tools.js CHANGED
@@ -997,16 +997,21 @@ const TOOLS = [
997
997
  {
998
998
  name: 'install_blueprint',
999
999
  title: 'Install an app from the catalogue',
1000
- description: "Install an app of the Faable catalogue (WordPress…) in a project: its app, a volume for its files and a database with daily backups, with sign-in through Faable Auth (the dashboard's Install an app). Needs a Hobby or Pro project; the database is billed per month. list_blueprints says what each app asks for in `inputs`.",
1000
+ description: "Install an app of the Faable catalogue (WordPress…) in a project: its app, a volume for its files and a database with daily backups, with sign-in through Faable Auth (the dashboard's Install an app). Needs a Hobby or Pro project; the database is billed per month. list_blueprints says what each app asks for in `inputs`. The user installing it is the site's admin, by their verified email. With `domain`, the site lives on that domain: the result's `dns` is the record the user must create at their DNS provider — tell them, the site does not load there until it points at Faable.",
1001
1001
  input: {
1002
1002
  blueprint: z.string().describe('Catalogue app, e.g. wordpress'),
1003
1003
  name: z
1004
1004
  .string()
1005
- .describe('Name of the app it creates: lowercase letters, digits and dashes'),
1005
+ .optional()
1006
+ .describe('Name of the app it creates: lowercase letters, digits and dashes. Defaults to the site title as a slug'),
1006
1007
  inputs: z
1007
1008
  .record(z.string(), z.string())
1008
1009
  .optional()
1009
- .describe('What the app asks for (list_blueprints), e.g. { "title": "My blog", "admin_email": "me@example.com" }'),
1010
+ .describe('What the app asks for (list_blueprints), e.g. { "title": "My blog", "locale": "es_ES" }'),
1011
+ domain: z
1012
+ .string()
1013
+ .optional()
1014
+ .describe("The site's production domain, e.g. www.example.com (not under faable.link). The user configures its DNS"),
1010
1015
  tier: z
1011
1016
  .string()
1012
1017
  .optional()
@@ -1023,6 +1028,7 @@ const TOOLS = [
1023
1028
  ...optText('--name', a.name),
1024
1029
  ...Object.entries((a.inputs ?? {})).map(([k, v]) => `--input=${k}=${v}`),
1025
1030
  ...opt('--tier', a.tier),
1031
+ ...optText('--domain', a.domain),
1026
1032
  ...(a.wait ? ['--wait', '--timeout', '600'] : []),
1027
1033
  ...scope(a)
1028
1034
  ],
@@ -1036,7 +1042,8 @@ const TOOLS = [
1036
1042
  example: {
1037
1043
  blueprint: 'wordpress',
1038
1044
  name: 'blog',
1039
- inputs: { title: 'My blog', admin_email: 'me@example.com' },
1045
+ inputs: { title: 'My blog' },
1046
+ domain: 'www.example.com',
1040
1047
  wait: true
1041
1048
  }
1042
1049
  },
@@ -1145,7 +1152,9 @@ const TOOLS = [
1145
1152
  input: {
1146
1153
  app: optional_app,
1147
1154
  project,
1148
- fqdn: z.string().describe('The domain that redirects, e.g. www.example.com'),
1155
+ fqdn: z
1156
+ .string()
1157
+ .describe('The domain that redirects, e.g. www.example.com'),
1149
1158
  target: z
1150
1159
  .string()
1151
1160
  .nullable()
@@ -1709,12 +1718,7 @@ const TOOLS = [
1709
1718
  project
1710
1719
  },
1711
1720
  command: ['auth', 'clients', 'update'],
1712
- flags: a => [
1713
- a.client,
1714
- '--signup-protection',
1715
- a.mode,
1716
- ...auth_scope(a)
1717
- ],
1721
+ flags: a => [a.client, '--signup-protection', a.mode, ...auth_scope(a)],
1718
1722
  shape: (c) => ({
1719
1723
  id: c.id,
1720
1724
  client_id: c.client_id,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.44.0",
3
+ "version": "4.45.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",