@faable/faable 4.46.0 → 4.48.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.
package/README.md CHANGED
@@ -70,7 +70,8 @@ claude mcp add faable -- npx -y @faable/faable mcp
70
70
  By default it exposes reads plus `deploy_app` (build the latest commit server-side).
71
71
  `faable mcp --writes` adds the reversible writes: create an app from a repository,
72
72
  set environment variables, add a domain, retry or cancel a build, change deploy
73
- settings. Nothing destructive is exposed. Secret values are never returned, and
73
+ settings, rotate a Challenge secret. `delete_app` and `delete_challenge_site`
74
+ are the local server's only deletions. Secret values are never returned, and
74
75
  logs come back marked as data, not instructions.
75
76
 
76
77
  ### Scripting and agents
@@ -526,6 +526,16 @@ class FaableApi {
526
526
  headers: projectHeader(team)
527
527
  }));
528
528
  }
529
+ async listInstallations(team) {
530
+ return data(this.client.get(`/installation`, {
531
+ headers: projectHeader(team)
532
+ })).then(res => res.results);
533
+ }
534
+ // Brings an uninstalled one back as a new app (§550): its files, a copy of
535
+ // its database, its Auth tenant and its own domain. Answers at once.
536
+ async restoreInstallation(id, team) {
537
+ return data(this.client.post(`/installation/${id}/restore`, {}, { headers: projectHeader(team) }));
538
+ }
529
539
  // ── apps: create, configure, observe ─────────────────────────────────────
530
540
  // A bare app in a project; `linkRepository` gives it something to build.
531
541
  async createApp(project, params) {
@@ -4,7 +4,7 @@ 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
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';
7
+ import { catalog_lines, parse_inputs, missing_fields, app_name_from_title, domain_problem, wait_for_installation, restorable, restorable_lines, find_restorable } from './install_lib.js';
8
8
  import { reachable_timeout_ms, wait_reachable } from './reachable.js';
9
9
 
10
10
  // `faable deploy install wordpress` — the dashboard's «Install an app»:
@@ -12,12 +12,16 @@ import { reachable_timeout_ms, wait_reachable } from './reachable.js';
12
12
  // for its files and a Database with daily backups; Hobby and Pro). Without
13
13
  // an app, lists the catalogue: what can be installed and what each asks for.
14
14
  const install = {
15
- command: 'install [app]',
15
+ command: 'install [app] [installation]',
16
16
  describe: 'Install an app from the Faable catalogue (WordPress…); without one, list the catalogue',
17
17
  builder: yargs => json_option(yargs)
18
18
  .positional('app', {
19
19
  type: 'string',
20
- description: 'Catalogue app to install (e.g. wordpress)'
20
+ description: 'Catalogue app to install (e.g. wordpress), or `restore` to bring back an uninstalled one'
21
+ })
22
+ .positional('installation', {
23
+ type: 'string',
24
+ description: 'With restore: the uninstalled installation, by name or id; without it, list what can be restored'
21
25
  })
22
26
  .option('name', {
23
27
  alias: 'n',
@@ -51,8 +55,11 @@ const install = {
51
55
  .example('$0 deploy install', 'List the apps you can install')
52
56
  .example('$0 deploy install wordpress --input title="My blog" --wait', 'Install WordPress (you are its admin) and wait until it is ready')
53
57
  .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')
58
+ .example('$0 deploy install restore my-blog --wait', 'Bring back a WordPress you uninstalled (within 30 days, if its database was kept)')
54
59
  .showHelpOnFail(false),
55
60
  handler: async (args) => {
61
+ if (args.app === 'restore')
62
+ return restoreInstallation(args);
56
63
  const { api } = await requireApi();
57
64
  const catalog = await api.listBlueprints();
58
65
  if (!args.app) {
@@ -179,5 +186,73 @@ const install = {
179
186
  }
180
187
  }
181
188
  };
189
+ // `faable deploy install restore [installation]` (§550): the dashboard's
190
+ // Restore. A new app with the uninstalled one's files, a copy of its
191
+ // database, its Auth tenant and its own domain; on faable.link, a new
192
+ // address with its links moved. Without an installation, the list.
193
+ const restoreInstallation = async (args) => {
194
+ const { api } = await requireApi();
195
+ const { id: project } = await requireProject(api);
196
+ const list = await api.listInstallations(project);
197
+ if (!args.installation) {
198
+ const can = restorable(list);
199
+ if (args.json)
200
+ return print_json(can);
201
+ if (!can.length) {
202
+ log.info('Nothing to restore: no uninstalled installation in this project.');
203
+ return;
204
+ }
205
+ log.info('Uninstalled, and restorable while their data is kept (30 days, if the database was not deleted with them):');
206
+ for (const line of restorable_lines(list))
207
+ log.info(` ${line}`);
208
+ log.info('Restore one with: faable deploy install restore <name> --wait');
209
+ return;
210
+ }
211
+ const found = find_restorable(list, args.installation);
212
+ if ('problem' in found)
213
+ throw new CliError('usage', found.problem);
214
+ let inst;
215
+ try {
216
+ inst = await api.restoreInstallation(found.inst.id, project);
217
+ }
218
+ catch (err) {
219
+ const e = err;
220
+ if (e.code === 'plan_required') {
221
+ const failed = new CliError('usage', `Restoring it needs a Hobby or Pro project (it comes back with a volume and a database). Upgrade it from the dashboard: project settings › Plan.`, { cause: err });
222
+ failed.code = 'plan_required';
223
+ throw failed;
224
+ }
225
+ throw err;
226
+ }
227
+ log.info(`♻️ Restoring ${inst.name} (${inst.id}) as a new app`);
228
+ let waited;
229
+ let url;
230
+ if (args.wait) {
231
+ waited = await wait_for_installation(api, inst, {
232
+ timeout_s: args.timeout ?? 900
233
+ });
234
+ if (waited.ok) {
235
+ const now = await api.getInstallation(inst.id, project).catch(() => inst);
236
+ url = now.site_url ?? undefined;
237
+ inst = now;
238
+ }
239
+ if (!args.json) {
240
+ log.info(waited.ok
241
+ ? `✅ Restored${url ? `: ${url}` : ''}`
242
+ : waited.done
243
+ ? `❌ The restore failed: ${waited.error ?? 'see the dashboard'} — resume it from the dashboard (Deploy › Installations)`
244
+ : `⏳ Still ${waited.state} after ${args.timeout}s — it goes on; check it in the dashboard`);
245
+ }
246
+ }
247
+ if (args.json) {
248
+ return print_json({
249
+ installation: inst,
250
+ ...(waited ? { result: { ...waited, ...(url ? { url } : {}) } } : {})
251
+ });
252
+ }
253
+ if (!args.wait) {
254
+ log.info(`⏳ Copying its database takes a few minutes. Follow it in the dashboard (Deploy › Installations), or run again with --wait.`);
255
+ }
256
+ };
182
257
 
183
258
  export { install };
@@ -82,5 +82,51 @@ const domain_problem = (fqdn) => {
82
82
  }
83
83
  return null;
84
84
  };
85
+ /**
86
+ * `faable deploy install restore`: what can come back — the uninstalled
87
+ * installations whose files and database are still kept. An api without
88
+ * `restorable` (older) leaves every uninstalled one in; the restore says.
89
+ */
90
+ const restorable = (list) => list.filter(i => i.state === 'retained' && i.restorable !== false);
91
+ const restorable_lines = (list) => restorable(list).map(i => {
92
+ const where = i.domain ?? i.site_url;
93
+ const until = i.restorable_until
94
+ ? `until ${i.restorable_until.slice(0, 10)}`
95
+ : '';
96
+ return [i.name, i.blueprint_slug, i.id, where, until]
97
+ .filter(Boolean)
98
+ .join(' ');
99
+ });
100
+ /**
101
+ * The installation to restore, by id or by name. A name may repeat (an app
102
+ * name is reused after an uninstall): the uninstalled one is the one meant,
103
+ * and two uninstalled ones need the id. A reason when none fits.
104
+ */
105
+ const find_restorable = (list, ref) => {
106
+ const byId = list.find(i => i.id === ref || i.id.replace(/^[a-z]+_/, '') === ref);
107
+ const matches = byId ? [byId] : list.filter(i => i.name === ref);
108
+ if (!matches.length) {
109
+ return {
110
+ problem: `No installation "${ref}" in this project. See what can be restored with: faable deploy install restore`
111
+ };
112
+ }
113
+ const retained = restorable(matches);
114
+ if (retained.length === 1)
115
+ return { inst: retained[0] };
116
+ if (retained.length > 1) {
117
+ return {
118
+ problem: `More than one uninstalled "${ref}": restore it by id (${retained.map(i => i.id).join(', ')}).`
119
+ };
120
+ }
121
+ const gone = matches.find(i => i.state === 'retained');
122
+ if (gone) {
123
+ return {
124
+ problem: `"${ref}" can't be restored any more: its files or its database were deleted (uninstalled with its database, or past its 30 days).`
125
+ };
126
+ }
127
+ return {
128
+ problem: `"${ref}" is ${matches[0].state}: only an uninstalled installation can be restored.`
129
+ };
130
+ };
85
131
 
86
- export { app_name_from_title, catalog_lines, domain_problem, missing_fields, parse_inputs, wait_for_installation };
132
+ export { app_name_from_title, catalog_lines, domain_problem, find_restorable, missing_fields, parse_inputs, restorable, restorable_lines, wait_for_installation };
package/dist/mcp/http.js CHANGED
@@ -190,7 +190,7 @@ const llms_txt = (base = PUBLIC_URL) => [
190
190
  : `Endpoint: ${base}/mcp (Streamable HTTP). Authenticate with a Faable API key: \`Authorization: Bearer <key>\` (create one in the dashboard, project settings → API keys). The key belongs to one project and only acts there.`,
191
191
  '',
192
192
  `- \`${base}/mcp/<project>\` pins every call to one project.`,
193
- '- `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings). Nothing destructive is exposed.',
193
+ '- `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings, rotate a Challenge secret). Nothing is ever deleted.',
194
194
  '- `?readonly=1` exposes reads only.',
195
195
  '- Local alternative, no key: `npx -y @faable/faable mcp` (uses `faable login`).',
196
196
  '',
@@ -6,12 +6,14 @@ import { TOOLS } from './tools.js';
6
6
 
7
7
  // `faable mcp` — the Faable MCP server over stdio (Fase 1 of
8
8
  // arch/deploy/mcp-server-faable.md). Reads plus `deploy_app` by default;
9
- // the reversible writes only with --writes. Nothing destructive, ever, here.
9
+ // the reversible writes only with --writes. The destructive tools are writes,
10
+ // and all but rotate_challenge_secret are local only.
10
11
  const INSTRUCTIONS = `Faable Deploy (apps, deployments, logs, domains, secrets) and Faable Auth (the users who log in to the user's apps) of the user's Faable projects.
11
12
  - Orient with list_apps (or list_projects when the user has several projects); pass \`project\` to scope a call.
12
13
  - "Why did my deploy fail?": list_deployments → get_deployment (full failure reason, and \`fault\`: \`user\` = their code or config, \`platform\` = Faable's side) → get_build_logs (the cause is at the end).
13
14
  - "Deploy this repository and give me the URL": list_github_repos → create_app with \`wait\` (or deploy_app with \`wait\` for an existing app). A local directory that is not on GitHub: deploy_directory.
14
15
  - "Install WordPress": list_blueprints (what it asks for) → install_blueprint with \`wait\` (Hobby or Pro; it comes with a volume and a billed database).
16
+ - "Bring back the WordPress I uninstalled": restore_installation without \`installation\` (what can be restored), then with it and \`wait\`.
15
17
  - Faable Auth: "who logged in recently?" → list_auth_logins; "how many logged in today / signed up this week?" → count_auth_users; "why can't X log in?" → get_auth_user + list_auth_logs (status failed).
16
18
  - Roles (RBAC): "what can X do?" → get_auth_user_access; "who has role R / what does it grant?" → get_auth_role. A role grants permissions of one API to the users it is assigned to (update_auth_user_roles); team roles grant none.
17
19
  - "Something keeps my app awake / hammers it": get_app_traffic (\`top_ips\`, \`top_endpoints\`) → add_waf_rule (sink answers 404 without waking the app; monitor first when unsure what a rule would catch) → list_waf_rules.
@@ -42,7 +44,7 @@ const NEXT_STEP = {
42
44
  apikey_session: 'The user is logged in with an API key; this needs `faable login` without --apikey.',
43
45
  apikey_invalid: 'The API key this server was given is invalid or was revoked. The user needs a new one from the dashboard (project settings → API Keys).',
44
46
  not_found: 'Check the id or name — list_apps / list_deployments show what exists.',
45
- forbidden: 'This session has no access there — check the project (list_projects). With an API key, Auth tools only reach the tenants of the key\'s own project.',
47
+ forbidden: "This session has no access there — check the project (list_projects). With an API key, Auth tools only reach the tenants of the key's own project.",
46
48
  github_installation_missing: 'The Faable GitHub App is not installed on that repository. Give the user the install link (list_github_repos returns it as install_url); it is a step in their browser.',
47
49
  github_identity_missing: 'The user has not connected GitHub to Faable yet: they connect it once in the dashboard (https://dashboard.faable.com), then retry.',
48
50
  repository_already_linked: 'That repository already has an app: use deploy_app on it (list_apps finds it).',
package/dist/mcp/tools.js CHANGED
@@ -1098,6 +1098,36 @@ const TOOLS = [
1098
1098
  wait: true
1099
1099
  }
1100
1100
  },
1101
+ {
1102
+ name: 'restore_installation',
1103
+ title: 'Restore an uninstalled app',
1104
+ description: 'Bring back an app installed from the catalogue (WordPress…) that the user uninstalled, while its data is kept: 30 days, and only if its database was not deleted with it. It comes back as a new app with its files, a copy of its database, sign-in in the same Faable Auth tenant (same users) and its own domain if it had one (same DNS record). Without its own domain it gets a new faable.link address and the links in its content move there. Without `installation`, lists the uninstalled ones that can be restored. Needs a Hobby or Pro project.',
1105
+ input: {
1106
+ installation: z
1107
+ .string()
1108
+ .optional()
1109
+ .describe('The uninstalled installation, by name or id; omit it to list what can be restored'),
1110
+ wait: z
1111
+ .boolean()
1112
+ .optional()
1113
+ .describe('Wait until it is restored (returns the URL) or fails, up to 10 minutes'),
1114
+ project
1115
+ },
1116
+ command: ['deploy', 'install', 'restore'],
1117
+ flags: a => [
1118
+ ...(a.installation ? [String(a.installation)] : []),
1119
+ ...(a.wait && a.installation ? ['--wait', '--timeout', '600'] : []),
1120
+ ...scope(a)
1121
+ ],
1122
+ timeout_ms: 630_000,
1123
+ write: true,
1124
+ annotations: {
1125
+ readOnlyHint: false,
1126
+ destructiveHint: false,
1127
+ openWorldHint: true
1128
+ },
1129
+ example: { installation: 'my-blog', wait: true }
1130
+ },
1101
1131
  {
1102
1132
  name: 'redeploy',
1103
1133
  title: 'Retry a failed deployment',
@@ -1397,16 +1427,16 @@ const TOOLS = [
1397
1427
  {
1398
1428
  name: 'rotate_challenge_secret',
1399
1429
  title: 'Rotate a Challenge secret',
1400
- description: "Issue a new secret for a Faable Challenge site, e.g. when the old one leaked. The old secret stops working AT ONCE: until the user's server has the new one, its verifications fail. Confirm with the user first. Returns the new `secret`, only this once. Only on the local server with `faable mcp --writes`.",
1430
+ description: "Issue a new secret for a Faable Challenge site, e.g. when the old one leaked. The old secret stops working AT ONCE: until the user's server has the new one, its verifications fail. Confirm with the user first. Returns the new `secret`, only this once.",
1401
1431
  input: { project, site: challenge_site },
1402
1432
  command: ['challenge', 'sites', 'rotate-secret'],
1403
1433
  // --yes: the model was asked to rotate; the CLI prompt has no one to ask.
1404
1434
  flags: a => [a.site, '--yes', ...scope(a)],
1405
1435
  shape: with_secret_note,
1406
1436
  write: true,
1407
- // It breaks the user's verify until their server has the new secret: not
1408
- // on the hosted server, which promises nothing destructive.
1409
- local_only: true,
1437
+ // The one destructive tool on the hosted server (Marc, 18-11): a leaked
1438
+ // secret is urgent and deletes nothing. It breaks the user's verify until
1439
+ // their server has the new one, so destructiveHint makes the client ask.
1410
1440
  annotations: {
1411
1441
  readOnlyHint: false,
1412
1442
  destructiveHint: true,
@@ -1423,7 +1453,7 @@ const TOOLS = [
1423
1453
  command: ['challenge', 'sites', 'delete'],
1424
1454
  flags: a => [a.site, '--yes', ...scope(a)],
1425
1455
  write: true,
1426
- // Like delete_app: the hosted server promises nothing destructive.
1456
+ // Like delete_app: the hosted server deletes nothing.
1427
1457
  local_only: true,
1428
1458
  annotations: {
1429
1459
  readOnlyHint: false,
@@ -1495,9 +1525,9 @@ const TOOLS = [
1495
1525
  command: ['deploy', 'apps', 'rm'],
1496
1526
  flags: a => ['--yes', ...target(a)],
1497
1527
  write: true,
1498
- // The hosted server promises its users nothing destructive (the consent
1499
- // screen and docs/cli.md say so): deleting stays with whoever runs the
1500
- // MCP on their own machine and passed --writes.
1528
+ // The hosted server deletes nothing (docs/cli.md and the landing say so):
1529
+ // deleting stays with whoever runs the MCP on their own machine and
1530
+ // passed --writes.
1501
1531
  local_only: true,
1502
1532
  annotations: {
1503
1533
  readOnlyHint: false,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.46.0",
3
+ "version": "4.48.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",