@faable/faable 4.49.0 → 4.50.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
@@ -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 };
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.49.0",
3
+ "version": "4.50.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",