@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 +2 -1
- package/dist/api/FaableApi.js +10 -0
- package/dist/commands/deploy/install.js +78 -3
- package/dist/commands/deploy/install_lib.js +47 -1
- package/dist/mcp/http.js +1 -1
- package/dist/mcp/server.js +4 -2
- package/dist/mcp/tools.js +38 -8
- package/package.json +1 -1
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
|
|
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
|
package/dist/api/FaableApi.js
CHANGED
|
@@ -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
|
|
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
|
'',
|
package/dist/mcp/server.js
CHANGED
|
@@ -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.
|
|
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:
|
|
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.
|
|
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
|
-
//
|
|
1408
|
-
//
|
|
1409
|
-
|
|
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
|
|
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
|
|
1499
|
-
//
|
|
1500
|
-
//
|
|
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,
|