@faable/faable 4.49.0 → 4.51.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
@@ -94,6 +94,23 @@ directory, and `faable deploy launch` needs `--app`, `--workdir` and `--yes`.
94
94
  Pass secret values on stdin (`faable deploy secrets set -f -`), never as
95
95
  arguments.
96
96
 
97
+ To find a command, search the catalog instead of walking `--help`:
98
+
99
+ ```sh
100
+ faable commands domain add --json # usage, positionals, flags, effect
101
+ faable commands --effect read # everything that changes nothing
102
+ ```
103
+
104
+ Each command carries its `effect`: `read`, `write`, `destructive` (deletes or
105
+ overwrites what cannot be brought back) or `local` (only this machine's
106
+ session). A few depend on their arguments and say when they are a read
107
+ (`read_when`).
108
+
109
+ `FAABLE_READONLY=1` (or `--read-only`) refuses every `write` and
110
+ `destructive` command before it sends anything — `{"error":{"code":"read_only"}}`,
111
+ exit 1 — and lets reads through. Turn it on for an agent you let run the CLI
112
+ on its own; `faable commands --json` says whether it is on (`read_only`).
113
+
97
114
  ### Deploy
98
115
 
99
116
  ```bash
@@ -174,9 +174,14 @@ class FaableApi {
174
174
  // One page of apps, scoped to `project` (default: the active project).
175
175
  // `null` = unscoped. The api filters by the header, so an admin session
176
176
  // doesn't page through the whole platform.
177
- async listApps(params, project = this.project ?? null) {
177
+ // `latest`: each app with its newest deployment, serving or not
178
+ // (`?expand=latest_deployment`, api ≥ the release that added it).
179
+ async listApps(params, project = this.project ?? null, { latest = false } = {}) {
178
180
  return data(this.client.get(`/app`, {
179
- params: page_params(params),
181
+ params: {
182
+ ...page_params(params),
183
+ ...(latest ? { expand: 'latest_deployment' } : {})
184
+ },
180
185
  ...(project ? { headers: projectHeader(project) } : {})
181
186
  }));
182
187
  }
@@ -0,0 +1,142 @@
1
+ import { version } from '../../config.js';
2
+ import { walk, matches } from '../../lib/catalog.js';
3
+ import { EFFECTS } from '../../lib/effects.js';
4
+ import { CliError } from '../../lib/errors.js';
5
+ import { print_json, print, json_option } from '../../lib/listing.js';
6
+ import { is_read_only } from '../../lib/read_only.js';
7
+
8
+ // What a program needs to call a command, and nothing it would pay tokens
9
+ // for: no empty fields, and `--json` as a boolean rather than one more flag.
10
+ const compact_arg = (a) => {
11
+ const out = { name: a.name };
12
+ if (a.aliases.length)
13
+ out.aliases = a.aliases;
14
+ if (a.type)
15
+ out.type = a.type;
16
+ if (a.required)
17
+ out.required = true;
18
+ if (a.array)
19
+ out.array = true;
20
+ if (a.choices)
21
+ out.choices = a.choices;
22
+ if (a.default !== undefined && a.default !== false)
23
+ out.default = a.default;
24
+ if (a.describe)
25
+ out.describe = a.describe;
26
+ return out;
27
+ };
28
+ const describe_command = (c) => {
29
+ const rule = EFFECTS[c.path];
30
+ const out = {
31
+ object: 'command',
32
+ path: c.path,
33
+ usage: [
34
+ 'faable',
35
+ c.path,
36
+ ...c.positionals.map(p => p.required
37
+ ? `<${p.name}${p.array ? '..' : ''}>`
38
+ : `[${p.name}${p.array ? '..' : ''}]`)
39
+ ].join(' '),
40
+ describe: c.describe,
41
+ effect: rule?.effect,
42
+ json: c.options.some(o => o.name === 'json')
43
+ };
44
+ if (rule?.read_when)
45
+ out.read_when = rule.read_when;
46
+ if (c.aliases.length)
47
+ out.aliases = c.aliases;
48
+ if (c.default_of_group)
49
+ out.default_of_group = true;
50
+ if (c.hidden)
51
+ out.hidden = true;
52
+ if (c.positionals.length)
53
+ out.positionals = c.positionals.map(compact_arg);
54
+ const options = c.options.filter(o => o.name !== 'json').map(compact_arg);
55
+ if (options.length)
56
+ out.options = options;
57
+ return out;
58
+ };
59
+ // The flags every command takes (src/index.ts), said once rather than 130
60
+ // times.
61
+ const GLOBAL_OPTIONS = [
62
+ {
63
+ name: 'project',
64
+ aliases: ['p'],
65
+ type: 'string',
66
+ describe: 'Project to act on, id or name (env FAABLE_PROJECT)'
67
+ },
68
+ {
69
+ name: 'non-interactive',
70
+ type: 'boolean',
71
+ describe: 'Never prompt nor infer the app from the working directory; errors as JSON (env FAABLE_NONINTERACTIVE=1)'
72
+ },
73
+ {
74
+ name: 'read-only',
75
+ type: 'boolean',
76
+ describe: 'Refuse every write or destructive command before it sends anything (env FAABLE_READONLY=1)'
77
+ },
78
+ {
79
+ name: 'config',
80
+ aliases: ['c'],
81
+ type: 'string',
82
+ describe: 'Path to the local `faable.json` file'
83
+ }
84
+ ];
85
+ // `faable commands` — the CLI described as data, for agents: search it, then
86
+ // call what it found. Read from the same command tree the CLI runs
87
+ // (src/lib/catalog.ts), with what each command does to Faable
88
+ // (src/lib/effects.ts).
89
+ const commands = {
90
+ command: 'commands [query..]',
91
+ describe: 'List the CLI commands, with their flags and whether they change anything (search: add words)',
92
+ builder: yargs => json_option(yargs)
93
+ .positional('query', {
94
+ type: 'string',
95
+ array: true,
96
+ description: 'Words that must all appear in the command, its description or its flags'
97
+ })
98
+ .option('effect', {
99
+ type: 'string',
100
+ array: true,
101
+ choices: ['read', 'write', 'destructive', 'local'],
102
+ description: 'Only commands with this effect (repeatable)'
103
+ })
104
+ .option('hidden', {
105
+ type: 'boolean',
106
+ default: false,
107
+ description: 'Also list the commands kept out of the help'
108
+ })
109
+ .example('$0 commands domain --json', 'Every command about domains, as JSON')
110
+ .example('$0 commands --effect read', 'What can be run without changing anything'),
111
+ handler: async (args) => {
112
+ // Imported here: the root list registers this very command.
113
+ const { ROOT_COMMANDS } = await import('../root.js');
114
+ const query = (args.query ?? []).join(' ');
115
+ const found = walk(ROOT_COMMANDS)
116
+ .filter(c => args.hidden || !c.hidden)
117
+ .filter(c => !query || matches(c, query))
118
+ .filter(c => !args.effect?.length || args.effect.includes(EFFECTS[c.path]?.effect));
119
+ if (args.json) {
120
+ print_json({
121
+ object: 'list',
122
+ data: found.map(describe_command),
123
+ has_more: false,
124
+ next_cursor: null,
125
+ cli_version: version,
126
+ // Whether `write` and `destructive` commands would be refused now.
127
+ read_only: is_read_only(args),
128
+ global_options: GLOBAL_OPTIONS
129
+ });
130
+ return;
131
+ }
132
+ if (!found.length)
133
+ throw new CliError('not_found', `No command matches "${query}". Try fewer words, or \`faable commands\` for all.`);
134
+ const width = Math.max(...found.map(c => c.path.length));
135
+ for (const c of found) {
136
+ const effect = EFFECTS[c.path]?.effect ?? '?';
137
+ print(`faable ${c.path.padEnd(width)} ${effect.padEnd(11)} ${c.describe}`);
138
+ }
139
+ }
140
+ };
141
+
142
+ export { commands };
@@ -1,7 +1,7 @@
1
1
  import { requireApi } from '../../../api/context.js';
2
2
  import { print_noop, print_json, json_option } from '../../../lib/listing.js';
3
3
  import { log } from '../../../log.js';
4
- import { resolve_app_id } from '../resolve_app_id.js';
4
+ import { resolve_app_for_deployment } from '../resolve_app_id.js';
5
5
 
6
6
  // Mirrors CANCELABLE_PHASES in the api (deployment/api/cancel.ts). Used only
7
7
  // to pick a default target; the api is the one that enforces it, so a phase
@@ -24,7 +24,7 @@ const cancel = {
24
24
  .showHelpOnFail(false),
25
25
  handler: async (args) => {
26
26
  const ctx = await requireApi();
27
- const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
27
+ const app_id = await resolve_app_for_deployment(args.app, args.deployment, ctx.appId, ctx.api);
28
28
  const app = await ctx.api.getApp(app_id);
29
29
  let deployment_id = args.deployment;
30
30
  if (!deployment_id) {
@@ -1,6 +1,6 @@
1
1
  import { requireApi } from '../../../api/context.js';
2
2
  import { log } from '../../../log.js';
3
- import { resolve_app_id } from '../resolve_app_id.js';
3
+ import { resolve_app_for_deployment } from '../resolve_app_id.js';
4
4
  import { deployment_detail } from './detail.js';
5
5
 
6
6
  const inspect = {
@@ -26,7 +26,7 @@ const inspect = {
26
26
  .showHelpOnFail(false),
27
27
  handler: async (args) => {
28
28
  const ctx = await requireApi();
29
- const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
29
+ const app_id = await resolve_app_for_deployment(args.app, args.deployment, ctx.appId, ctx.api);
30
30
  const app = await ctx.api.getApp(app_id);
31
31
  let deployment_id = args.deployment;
32
32
  if (!deployment_id) {
@@ -7,7 +7,14 @@ import { phase_badge } from './format.js';
7
7
  const apps_list = {
8
8
  command: 'list',
9
9
  describe: 'List the apps of the active project',
10
- builder: yargs => list_options(yargs).showHelpOnFail(false),
10
+ builder: yargs => list_options(yargs)
11
+ .option('latest', {
12
+ type: 'boolean',
13
+ default: false,
14
+ description: "Also each app's newest deployment, serving or not (`latest_deployment` with --json): which apps' last deploy failed, in one call"
15
+ })
16
+ .example("$0 deploy apps list --latest --json | jq -r '.data[] | select(.latest_deployment.status.phase == \"BUILD_ERROR\") | .name'", 'The apps whose last deploy failed to build')
17
+ .showHelpOnFail(false),
11
18
  handler: async (args) => {
12
19
  const ctx = await requireApi();
13
20
  // Scoped to the active project when there is one (--project,
@@ -15,7 +22,7 @@ const apps_list = {
15
22
  // which the api only allows a token with a global scope. Anyone else gets
16
23
  // `team_or_scope_required`: then, like `whoami`, the only project they
17
24
  // belong to, or an error that says how to pick one (backlog §374).
18
- const list = () => fetch_page(p => ctx.api.listApps(p), args);
25
+ const list = () => fetch_page(p => ctx.api.listApps(p, undefined, { latest: args.latest }), args);
19
26
  let page;
20
27
  try {
21
28
  page = await list();
@@ -36,7 +43,17 @@ const apps_list = {
36
43
  log.info(`📦 ${page.data.length} app(s)${scope}:`);
37
44
  const width = Math.max(...page.data.map(a => a.name.length));
38
45
  for (const app of page.data) {
39
- print(` ${app.name.padEnd(width)} ${phase_badge(app.status?.phase)} ${app.id} https://${app.url}`);
46
+ // The newest deployment, when asked for and when it is not what serves:
47
+ // a failed build behind a live older version.
48
+ const latest = app.latest_deployment;
49
+ const last = args.latest && latest
50
+ ? latest.id === app.status?.deployment
51
+ ? ' last deploy: live'
52
+ : ` last deploy: ${latest.status?.phase ?? '?'} (${latest.id})`
53
+ : args.latest
54
+ ? ' last deploy: none'
55
+ : '';
56
+ print(` ${app.name.padEnd(width)} ${phase_badge(app.status?.phase)} ${app.id} https://${app.url}${last}`);
40
57
  }
41
58
  const hint = more_hint(page);
42
59
  if (hint)
@@ -3,7 +3,7 @@ import { CliError } from '../../../lib/errors.js';
3
3
  import { print_json, as_list, json_option } from '../../../lib/listing.js';
4
4
  import { log } from '../../../log.js';
5
5
  import { follow_remote_build } from '../remote/follow.js';
6
- import { resolve_app_id } from '../resolve_app_id.js';
6
+ import { resolve_app_for_deployment } from '../resolve_app_id.js';
7
7
  import { tail_lines, log_entries, format_log_lines } from './format.js';
8
8
 
9
9
  // Phases where the build is still producing output; anything else is a frozen
@@ -58,7 +58,7 @@ const logs = {
58
58
  throw new CliError('usage', '--tail must be a positive integer');
59
59
  }
60
60
  const ctx = await requireApi();
61
- const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
61
+ const app_id = await resolve_app_for_deployment(args.app, args.deployment, ctx.appId, ctx.api);
62
62
  const app = await ctx.api.getApp(app_id);
63
63
  if (args.build) {
64
64
  // Build output lives on the deployment. Default to the newest one that
@@ -1,7 +1,7 @@
1
1
  import { requireApi } from '../../../api/context.js';
2
2
  import { print_noop, print_json, json_option } from '../../../lib/listing.js';
3
3
  import { log } from '../../../log.js';
4
- import { resolve_app_id } from '../resolve_app_id.js';
4
+ import { resolve_app_for_deployment } from '../resolve_app_id.js';
5
5
 
6
6
  const FAILED_PHASES = new Set(['ERROR', 'BUILD_ERROR']);
7
7
  const redeploy = {
@@ -21,7 +21,7 @@ const redeploy = {
21
21
  .showHelpOnFail(false),
22
22
  handler: async (args) => {
23
23
  const ctx = await requireApi();
24
- const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
24
+ const app_id = await resolve_app_for_deployment(args.app, args.deployment, ctx.appId, ctx.api);
25
25
  const app = await ctx.api.getApp(app_id);
26
26
  let deployment_id = args.deployment;
27
27
  if (!deployment_id) {
@@ -1,9 +1,9 @@
1
1
  import { requireProject } from '../../api/project.js';
2
2
  import { Configuration } from '../../lib/Configuration.js';
3
3
  import { CliError } from '../../lib/errors.js';
4
+ import { getGitRemoteUrl } from '../../lib/git_remote.js';
4
5
  import { is_non_interactive } from '../../lib/interactive.js';
5
6
  import { fetch_page } from '../../lib/listing.js';
6
- import { getGitRemoteUrl } from '../../lib/git_remote.js';
7
7
  import { log } from '../../log.js';
8
8
 
9
9
  // --app takes an id, a name or a slug. An id (`app_…`) is used as-is — the
@@ -82,5 +82,19 @@ const resolve_app_id = async (explicit, ctxAppId, api, workdir = process.cwd())
82
82
  ? 'Pass the app with --app <app_id> (non-interactive mode never infers it from the working directory).'
83
83
  : 'No app linked to this repository. Link it from the dashboard (or run "faable deploy link"), or pass one with --app <app_id>.');
84
84
  };
85
+ // The app of a command that names one deployment (`inspect`, `logs --build
86
+ // -d`, `redeploy`, `cancel`): a deployment id is globally unique and says
87
+ // whose it is, so without --app the app is the deployment's own — not the
88
+ // linked one, and no app_required. With --app the usual resolution applies,
89
+ // and the caller still checks the two agree. Measured in §555 F0: agents
90
+ // passed a deployment id and paid an extra round trip to learn --app.
91
+ const resolve_app_for_deployment = async (app_ref, deployment_id, linked, api) => {
92
+ if (deployment_id && !app_ref) {
93
+ const deployment = await api.getDeployment(deployment_id);
94
+ if (deployment?.app_id)
95
+ return deployment.app_id;
96
+ }
97
+ return resolve_app_id(app_ref, linked, api);
98
+ };
85
99
 
86
- export { find_app_id, resolve_app_id, resolve_app_ref };
100
+ export { find_app_id, resolve_app_for_deployment, resolve_app_id, resolve_app_ref };
@@ -0,0 +1,31 @@
1
+ import { auth } from './auth/index.js';
2
+ import { challenge } from './challenge/index.js';
3
+ import { commands } from './commands/index.js';
4
+ import { deploy } from './deploy/index.js';
5
+ import { link_deprecated } from './link/index.js';
6
+ import { login } from './login/index.js';
7
+ import { logout } from './logout/index.js';
8
+ import { mcp } from './mcp/index.js';
9
+ import { organization } from './organization/index.js';
10
+ import { project } from './project/index.js';
11
+ import { upgrade } from './upgrade/index.js';
12
+ import { whoami } from './whoami/index.js';
13
+
14
+ // The top level of `faable`, in help order — registered by src/index.ts and
15
+ // walked by `faable commands` (src/lib/catalog.ts), so both see one list.
16
+ const ROOT_COMMANDS = [
17
+ deploy,
18
+ auth,
19
+ challenge,
20
+ project,
21
+ organization,
22
+ login,
23
+ logout,
24
+ whoami,
25
+ commands,
26
+ mcp,
27
+ upgrade,
28
+ link_deprecated
29
+ ];
30
+
31
+ export { ROOT_COMMANDS };
package/dist/index.js CHANGED
@@ -1,23 +1,14 @@
1
1
  import yargs from 'yargs';
2
2
  import { hideBin } from 'yargs/helpers';
3
- import { auth } from './commands/auth/index.js';
4
- import { challenge } from './commands/challenge/index.js';
5
- import { deploy } from './commands/deploy/index.js';
6
- import { link_deprecated } from './commands/link/index.js';
7
- import { login } from './commands/login/index.js';
8
- import { logout } from './commands/logout/index.js';
9
- import { mcp } from './commands/mcp/index.js';
10
- import { organization } from './commands/organization/index.js';
11
- import { project } from './commands/project/index.js';
12
- import { upgrade } from './commands/upgrade/index.js';
13
- import { whoami } from './commands/whoami/index.js';
3
+ import { setProjectFlag, configuredProject } from './api/project.js';
4
+ import { ROOT_COMMANDS } from './commands/root.js';
14
5
  import { version } from './config.js';
15
6
  import { Configuration } from './lib/Configuration.js';
16
- import { setProjectFlag, configuredProject } from './api/project.js';
17
7
  import { ContextStore } from './lib/ContextStore.js';
8
+ import { notifyIfUpdateAvailable } from './lib/UpdateChecker.js';
18
9
  import { CliError, error_json } from './lib/errors.js';
19
10
  import { is_non_interactive } from './lib/interactive.js';
20
- import { notifyIfUpdateAvailable } from './lib/UpdateChecker.js';
11
+ import { guard_read_only } from './lib/read_only.js';
21
12
  import { log } from './log.js';
22
13
 
23
14
  // Where the command acts, on the banner — read locally, never a request.
@@ -75,6 +66,11 @@ yg.scriptName('faable')
75
66
  description: 'Never prompt nor infer the app from the working directory; errors as JSON (env FAABLE_NONINTERACTIVE=1)',
76
67
  boolean: true,
77
68
  global: true
69
+ })
70
+ .option('read-only', {
71
+ description: 'Refuse every command that would change Faable, before it sends anything (env FAABLE_READONLY=1)',
72
+ boolean: true,
73
+ global: true
78
74
  })
79
75
  .option('p', {
80
76
  alias: 'project',
@@ -93,17 +89,9 @@ yg.scriptName('faable')
93
89
  Configuration.instance();
94
90
  }
95
91
  }, true)
96
- .command(deploy)
97
- .command(auth)
98
- .command(challenge)
99
- .command(project)
100
- .command(organization)
101
- .command(login)
102
- .command(logout)
103
- .command(whoami)
104
- .command(mcp)
105
- .command(upgrade)
106
- .command(link_deprecated)
92
+ // The same list `faable commands` describes (src/commands/root.ts), each
93
+ // handler behind the read-only check of its own effect.
94
+ .command(guard_read_only(ROOT_COMMANDS))
107
95
  .demandCommand(1)
108
96
  // Reject unknown (sub)commands loudly. Without this, a typo'd or
109
97
  // not-yet-existing command (`faable secrets list` on a version where it
@@ -0,0 +1,138 @@
1
+ // A stand-in for the yargs instance a builder receives: it keeps what the
2
+ // builder declares (subcommands, options, positionals) and accepts every
3
+ // other call (.example, .check, .conflicts…) without doing anything, so a
4
+ // builder runs to the end whatever else it configures.
5
+ const recorder = (rec) => {
6
+ const proxy = new Proxy({}, {
7
+ get(_t, key) {
8
+ if (key === 'command')
9
+ return (mod) => {
10
+ if (typeof mod === 'object' && mod)
11
+ rec.commands.push(mod);
12
+ return proxy;
13
+ };
14
+ if (key === 'option' || key === 'options')
15
+ return (name, opts = {}) => {
16
+ if (typeof name === 'string')
17
+ rec.options.set(name, opts);
18
+ else
19
+ for (const [k, v] of Object.entries(name ?? {}))
20
+ rec.options.set(k, v);
21
+ return proxy;
22
+ };
23
+ if (key === 'positional')
24
+ return (name, opts = {}) => {
25
+ rec.positionals.set(name, opts);
26
+ return proxy;
27
+ };
28
+ // `then` must stay undefined or `await builder(proxy)` would treat
29
+ // the recorder as a promise.
30
+ if (key === 'then')
31
+ return undefined;
32
+ return () => proxy;
33
+ }
34
+ });
35
+ return proxy;
36
+ };
37
+ const as_list = (v) => v === undefined ? [] : Array.isArray(v) ? v.map(String) : [String(v)];
38
+ // `apps <command>`, `rm <id>`, `logs [app_id]` → name and declared
39
+ // positionals (required for <x>, optional for [x], variadic for ..).
40
+ const parse_command = (mod) => {
41
+ const forms = as_list(mod.command);
42
+ const is_default = forms.some(f => f.split(' ')[0] === '$0');
43
+ const named = forms.filter(f => f.split(' ')[0] !== '$0');
44
+ const [first, ...rest] = named.length ? named : forms;
45
+ const [name, ...params] = first.split(/\s+/);
46
+ const positionals = params.map(p => ({
47
+ name: p.replace(/^[<[]|[>\]]$/g, '').replace(/\.\.$/, ''),
48
+ required: p.startsWith('<'),
49
+ array: p.includes('..')
50
+ }));
51
+ const aliases = [
52
+ ...rest.map(f => f.split(/\s+/)[0]),
53
+ ...as_list(mod.aliases)
54
+ ];
55
+ return { name, positionals, aliases, is_default };
56
+ };
57
+ const arg = (name, opts, base = {}) => {
58
+ const out = {
59
+ name,
60
+ aliases: as_list(opts.alias),
61
+ type: opts.type ??
62
+ (opts.boolean
63
+ ? 'boolean'
64
+ : opts.string
65
+ ? 'string'
66
+ : opts.number
67
+ ? 'number'
68
+ : undefined),
69
+ describe: opts.describe ?? opts.description ?? opts.desc,
70
+ required: Boolean(opts.demandOption ?? opts.required ?? opts.demand ?? base.required),
71
+ array: Boolean(opts.array ?? base.array)
72
+ };
73
+ if (opts.choices)
74
+ out.choices = opts.choices;
75
+ if (opts.default !== undefined && typeof opts.default !== 'function')
76
+ out.default = opts.default;
77
+ return out;
78
+ };
79
+ const visible = (opts) => !opts.hidden;
80
+ // Walks a group: every command, depth first. A command whose builder
81
+ // registers subcommands is a group, not something to call, and is left out;
82
+ // its default subcommand is listed under its own name, flagged. A hidden
83
+ // group hides everything under it.
84
+ const walk = (roots, prefix = [], parent_hidden = false) => {
85
+ const out = [];
86
+ for (const mod of roots) {
87
+ const hidden = parent_hidden || mod.describe === false;
88
+ const { name, positionals, aliases, is_default } = parse_command(mod);
89
+ const rec = {
90
+ commands: [],
91
+ options: new Map(),
92
+ positionals: new Map()
93
+ };
94
+ const builder = mod.builder;
95
+ if (typeof builder === 'function')
96
+ builder(recorder(rec));
97
+ else if (builder && typeof builder === 'object')
98
+ for (const [k, v] of Object.entries(builder))
99
+ rec.options.set(k, v);
100
+ const path = [...prefix, name];
101
+ if (rec.commands.length) {
102
+ out.push(...walk(rec.commands, path, hidden));
103
+ continue;
104
+ }
105
+ out.push({
106
+ path: path.join(' '),
107
+ aliases,
108
+ describe: String(mod.describe ?? ''),
109
+ positionals: positionals.map(p => arg(p.name, rec.positionals.get(p.name) ?? {}, p)),
110
+ options: [...rec.options]
111
+ .filter(([, o]) => visible(o))
112
+ .map(([n, o]) => arg(n, o)),
113
+ default_of_group: is_default,
114
+ hidden,
115
+ module: mod
116
+ });
117
+ }
118
+ return out;
119
+ };
120
+ // Every word of the query has to appear in the command's path, description
121
+ // or one of its flags — `--filter "domain add"` finds `deploy domains add`.
122
+ const matches = (cmd, query) => {
123
+ const hay = [
124
+ cmd.path,
125
+ ...cmd.aliases,
126
+ cmd.describe,
127
+ ...cmd.options.map(o => o.name)
128
+ ]
129
+ .join(' ')
130
+ .toLowerCase();
131
+ return query
132
+ .toLowerCase()
133
+ .split(/\s+/)
134
+ .filter(Boolean)
135
+ .every(w => hay.includes(w.replace(/s$/, '')));
136
+ };
137
+
138
+ export { matches, walk };
@@ -0,0 +1,175 @@
1
+ // What each CLI command does to Faable — the one place it is written down.
2
+ //
3
+ // read only reads (it may write files HERE: `volumes get`, `users export`)
4
+ // write changes something in Faable that can be changed back
5
+ // destructive deletes or overwrites what cannot be brought back, or breaks
6
+ // something at once (a rotated secret)
7
+ // local changes only this machine's CLI state (session, active project)
8
+ //
9
+ // `faable commands` publishes it, the read-only mode refuses everything that
10
+ // is not `read` or `local` before any request (FAABLE_READONLY), and the MCP
11
+ // catalog has to agree with it (src/mcp/effects.test.ts). A command missing
12
+ // from here fails src/lib/effects.test.ts: a new command declares what it does.
13
+ const R = { effect: 'read' };
14
+ const W = { effect: 'write' };
15
+ const D = { effect: 'destructive' };
16
+ const L = { effect: 'local' };
17
+ // `--add` / `--rm` change; without them the command lists.
18
+ const lists_unless_add_rm = {
19
+ effect: 'write',
20
+ of: a => (has(a.add) || has(a.rm) ? 'write' : 'read'),
21
+ read_when: 'without --add or --rm'
22
+ };
23
+ const has = (v) => v !== undefined && v !== false && !(Array.isArray(v) && v.length === 0);
24
+ const EFFECTS = {
25
+ 'deploy launch': W,
26
+ 'deploy apps list': R,
27
+ 'deploy apps get': R,
28
+ 'deploy apps create': W,
29
+ 'deploy apps set': W,
30
+ 'deploy apps rm': D,
31
+ // No app: the catalogue. `restore` with no installation: what can be
32
+ // restored.
33
+ 'deploy install': {
34
+ effect: 'write',
35
+ of: a => !a.app || (a.app === 'restore' && !a.installation) ? 'read' : 'write',
36
+ read_when: 'without <app>, or `restore` without <installation>'
37
+ },
38
+ 'deploy github repos': R,
39
+ 'deploy secrets list': R,
40
+ 'deploy secrets set': W,
41
+ 'deploy secrets rm': D,
42
+ 'deploy domains list': R,
43
+ 'deploy domains add': W,
44
+ 'deploy domains attach': W,
45
+ 'deploy domains check': R,
46
+ 'deploy domains redirect': W,
47
+ 'deploy domains rm': D,
48
+ 'deploy waf list': R,
49
+ 'deploy waf block': W,
50
+ 'deploy waf sink': W,
51
+ 'deploy waf monitor': W,
52
+ 'deploy waf allow': W,
53
+ 'deploy waf limit': W,
54
+ 'deploy waf rm': W,
55
+ 'deploy waf add': W,
56
+ 'deploy logs': R,
57
+ 'deploy status': R,
58
+ // Runs anything, against the live volumes and variables.
59
+ 'deploy run': W,
60
+ 'deploy schedule list': R,
61
+ 'deploy schedule add': W,
62
+ 'deploy schedule enable': W,
63
+ 'deploy schedule disable': W,
64
+ 'deploy schedule rm': D,
65
+ 'deploy volumes list': R,
66
+ 'deploy volumes ls': R,
67
+ 'deploy volumes get': R,
68
+ // To the trash: --undo brings it back for 7 days.
69
+ 'deploy volumes rm': W,
70
+ 'deploy volumes backups': R,
71
+ 'deploy volumes backup': W,
72
+ 'deploy volumes restore': D,
73
+ 'deploy volumes clone': D,
74
+ 'deploy volumes export': R,
75
+ 'deploy volumes import': D,
76
+ 'deploy volumes put': D,
77
+ 'deploy traffic': R,
78
+ 'deploy usage': R,
79
+ 'deploy quota': R,
80
+ 'deploy list': R,
81
+ 'deploy deployments': R,
82
+ 'deploy inspect': R,
83
+ 'deploy open': R,
84
+ 'deploy trigger': W,
85
+ 'deploy redeploy': W,
86
+ 'deploy cancel': W,
87
+ 'deploy link': W,
88
+ 'auth users list': R,
89
+ 'auth users get': R,
90
+ 'auth users diagnose': R,
91
+ 'auth users update': W,
92
+ 'auth users suspend': W,
93
+ 'auth users reinstate': W,
94
+ 'auth users set-password': W,
95
+ 'auth users password-setup': W,
96
+ 'auth users tickets list': R,
97
+ 'auth users tickets revoke': W,
98
+ 'auth users roles': lists_unless_add_rm,
99
+ 'auth users permissions': R,
100
+ 'auth users import': W,
101
+ 'auth users export': R,
102
+ 'auth roles list': R,
103
+ 'auth roles get': R,
104
+ 'auth roles create': W,
105
+ 'auth roles permissions': lists_unless_add_rm,
106
+ 'auth roles rm': D,
107
+ 'auth apis list': R,
108
+ 'auth apis get': R,
109
+ 'auth apis create': W,
110
+ 'auth apis update': W,
111
+ 'auth actions list': R,
112
+ 'auth actions get': R,
113
+ 'auth actions create': W,
114
+ 'auth actions update': W,
115
+ 'auth actions rm': D,
116
+ 'auth clients list': R,
117
+ 'auth clients get': R,
118
+ 'auth clients create': W,
119
+ 'auth clients update': W,
120
+ 'auth clients rm': D,
121
+ 'auth logs list': R,
122
+ 'auth logs get': R,
123
+ 'auth sessions list': R,
124
+ 'auth sessions revoke': W,
125
+ 'auth connections list': R,
126
+ 'auth webhooks list': R,
127
+ 'auth webhooks get': R,
128
+ 'auth webhooks create': W,
129
+ 'auth webhooks update': W,
130
+ 'auth webhooks test': W,
131
+ // The old secret stays valid 24 h.
132
+ 'auth webhooks rotate-secret': W,
133
+ 'auth webhooks rm': D,
134
+ 'auth email-subscriptions list': R,
135
+ 'auth email-subscriptions create': W,
136
+ 'auth email-subscriptions update': W,
137
+ 'auth email-subscriptions rm': D,
138
+ 'auth accounts list': R,
139
+ 'auth use': L,
140
+ 'challenge sites list': R,
141
+ 'challenge sites create': W,
142
+ 'challenge sites update': W,
143
+ 'challenge sites delete': D,
144
+ // The old secret stops working at once.
145
+ 'challenge sites rotate-secret': D,
146
+ 'challenge usage': R,
147
+ 'project list': R,
148
+ 'project use': L,
149
+ 'project clear': L,
150
+ 'project current': R,
151
+ 'organization list': R,
152
+ 'organization get': R,
153
+ 'organization create': W,
154
+ 'organization projects add': W,
155
+ 'organization projects rm': W,
156
+ 'organization admins add': W,
157
+ 'organization admins rm': W,
158
+ login: L,
159
+ logout: L,
160
+ whoami: R,
161
+ commands: R,
162
+ // Serves tools; each tool call is a CLI run of its own, governed by its
163
+ // own command's effect.
164
+ mcp: R,
165
+ upgrade: L,
166
+ link: W
167
+ };
168
+ const effect_of = (path, argv = {}) => {
169
+ const rule = EFFECTS[path];
170
+ if (!rule)
171
+ return undefined;
172
+ return rule.of ? rule.of(argv) : rule.effect;
173
+ };
174
+
175
+ export { EFFECTS, effect_of };
@@ -0,0 +1,46 @@
1
+ import { walk } from './catalog.js';
2
+ import { effect_of } from './effects.js';
3
+ import { CliError } from './errors.js';
4
+
5
+ // Read-only mode: FAABLE_READONLY=1 or --read-only. Every command whose call
6
+ // would change Faable (effect `write` or `destructive`, src/lib/effects.ts)
7
+ // fails with `read_only` before it sends anything; reads and the machine's own
8
+ // state (login, project use) go through.
9
+ //
10
+ // It is what keeps an agent driving the CLI from a shell — with no MCP
11
+ // `--writes` in between — from changing anything the user did not mean it to
12
+ // (arch/deploy/cli-code-mode-plan.md, F3). The Faable skill turns it on; the
13
+ // user turns it off on purpose. A `faable mcp` started in it hands it to every
14
+ // CLI run of its tools, which inherit the environment.
15
+ const truthy = (v) => v !== undefined && !['', '0', 'false', 'no'].includes(v.toLowerCase());
16
+ const is_read_only = (argv = {}) => argv['read-only'] === true || truthy(process.env.FAABLE_READONLY);
17
+ const GUARDED = Symbol('read_only_guarded');
18
+ const refuse = (path, effect) => new CliError('read_only', `\`faable ${path}\` ${effect === 'destructive' ? 'deletes or overwrites' : 'changes'} something in Faable, and the CLI is in read-only mode (FAABLE_READONLY / --read-only). Nothing was sent.`, {
19
+ action: 'Ask the user before running it; it runs once they unset FAABLE_READONLY'
20
+ });
21
+ // Wraps the handler of every command under `roots`, in place, with the check
22
+ // for its own canonical path — so an alias, a group's default command or a
23
+ // hidden one is covered like any other. A command missing from the effects
24
+ // table counts as a write: the guard fails closed.
25
+ const guard_read_only = (roots) => {
26
+ for (const { path, module } of walk(roots)) {
27
+ const mod = module;
28
+ if (mod[GUARDED] || typeof mod.handler !== 'function')
29
+ continue;
30
+ const handler = mod.handler;
31
+ // async: a refusal has to reject, not throw — a synchronous throw from a
32
+ // handler skips the global .fail() and dies as a Node stack trace.
33
+ mod.handler = async (argv) => {
34
+ if (is_read_only(argv)) {
35
+ const effect = effect_of(path, argv) ?? 'write';
36
+ if (effect === 'write' || effect === 'destructive')
37
+ throw refuse(path, effect);
38
+ }
39
+ return handler(argv);
40
+ };
41
+ mod[GUARDED] = true;
42
+ }
43
+ return roots;
44
+ };
45
+
46
+ export { guard_read_only, is_read_only };
package/dist/mcp/tools.js CHANGED
@@ -233,18 +233,41 @@ const TOOLS = [
233
233
  {
234
234
  name: 'list_apps',
235
235
  title: 'List apps',
236
- description: 'The apps of a project, with their live phase, URL and linked repository. Start here to find the app the user means.',
237
- input: { project, cursor },
236
+ description: "The apps of a project, with their live phase, URL and linked repository. Start here to find the app the user means. With latest, also each app's newest deployment (serving or not): which apps' last deploy failed, in one call.",
237
+ input: {
238
+ project,
239
+ cursor,
240
+ latest: z
241
+ .boolean()
242
+ .optional()
243
+ .describe("Also each app's newest deployment — id, phase, when — even when an older one is what serves")
244
+ },
238
245
  command: ['deploy', 'apps', 'list'],
239
246
  flags: a => [
240
247
  '--limit',
241
248
  '100',
242
249
  ...scope(a),
243
- ...opt('--starting-after', a.cursor)
250
+ ...opt('--starting-after', a.cursor),
251
+ ...(a.latest ? ['--latest'] : [])
244
252
  ],
245
- shape: page(app_row),
253
+ // No failure message: that text is the deployer's (get_deployment).
254
+ shape: page((a) => ({
255
+ ...app_row(a),
256
+ ...(a.latest_deployment !== undefined
257
+ ? {
258
+ latest_deployment: a.latest_deployment
259
+ ? {
260
+ id: a.latest_deployment.id,
261
+ phase: a.latest_deployment.status?.phase,
262
+ created_at: a.latest_deployment.createdAt,
263
+ commit: a.latest_deployment.github_commit
264
+ }
265
+ : null
266
+ }
267
+ : {})
268
+ })),
246
269
  annotations: READ,
247
- example: { project: 'p', cursor: 'abc' }
270
+ example: { project: 'p', cursor: 'abc', latest: true }
248
271
  },
249
272
  {
250
273
  name: 'list_blueprints',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.49.0",
3
+ "version": "4.51.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",