@faable/faable 4.27.0 โ†’ 4.29.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.
@@ -384,6 +384,22 @@ class FaableApi {
384
384
  async createVolumeOperation(team, volume_id, kind) {
385
385
  return data(this.client.post(`/volume/${volume_id}/${kind}`, undefined, { headers: projectHeader(team) }));
386
386
  }
387
+ // An export of the whole volume, or of one file or directory of it.
388
+ async exportVolume(team, volume_id, path) {
389
+ return data(this.client.post(`/volume/${volume_id}/export`, undefined, { params: path ? { path } : {}, headers: projectHeader(team) }));
390
+ }
391
+ // Queues a read of one directory; its entries come with the completed op.
392
+ async listVolumeFiles(team, volume_id, path) {
393
+ return data(this.client.post(`/volume/${volume_id}/list-files`, undefined, { params: path ? { path } : {}, headers: projectHeader(team) }));
394
+ }
395
+ // rm: the paths go to the volume's trash (7 days), never deleted at once.
396
+ async removeVolumePaths(team, volume_id, paths) {
397
+ return data(this.client.post(`/volume/${volume_id}/remove`, { paths }, { headers: projectHeader(team) }));
398
+ }
399
+ // rm --undo: what a remove sent to the trash comes back.
400
+ async undoVolumeOperation(team, operation_id) {
401
+ return data(this.client.post(`/volume-operation/${operation_id}/undo`, undefined, { headers: projectHeader(team) }));
402
+ }
387
403
  async restoreVolume(team, volume_id, backup_id) {
388
404
  return data(this.client.post(`/volume/${volume_id}/restore`, { backup_id }, { headers: projectHeader(team) }));
389
405
  }
@@ -1,18 +1,53 @@
1
1
  import axios from 'axios';
2
+ import { execFile } from 'node:child_process';
2
3
  import { createWriteStream } from 'node:fs';
3
- import { rename, rm } from 'node:fs/promises';
4
+ import { stat, mkdtemp, mkdir, rm, rename } from 'node:fs/promises';
5
+ import { tmpdir } from 'node:os';
6
+ import path from 'node:path';
4
7
  import { pipeline } from 'node:stream/promises';
8
+ import { promisify } from 'node:util';
5
9
  import { CliError } from '../../../lib/errors.js';
6
10
  import { print_json, json_option } from '../../../lib/listing.js';
7
11
  import { log } from '../../../log.js';
12
+ import { volume_dest, format_bytes, require_completed, wait_operation, state_label } from './operation.js';
8
13
  import { resolve_volume, volume_option } from './shared.js';
9
- import { require_completed, wait_operation, format_bytes, state_label } from './operation.js';
10
14
  import { app_option } from '../schedule/shared.js';
11
15
 
16
+ const exec_file = promisify(execFile);
17
+ /** Queues an export (of `sub`, or of everything), waits, and saves it to `file`. */
18
+ const export_to_file = async (api, team, volume_id, sub, file, quiet) => {
19
+ const op = await api.exportVolume(team, volume_id, sub);
20
+ const done = require_completed(await wait_operation(api, team, op, {
21
+ onState: s => {
22
+ if (!quiet && s !== 'completed' && s !== 'failed')
23
+ log.info(state_label[s]);
24
+ }
25
+ }));
26
+ // The completed operation read by wait_operation carries a fresh URL.
27
+ const url = done.download_url;
28
+ if (!url) {
29
+ throw new CliError('not_found', `The export ${done.id} finished but has no download link; try again`);
30
+ }
31
+ const part = `${file}.part`;
32
+ const res = await axios.get(url, { responseType: 'stream', timeout: 0 });
33
+ try {
34
+ await pipeline(res.data, createWriteStream(part));
35
+ await rename(part, file);
36
+ }
37
+ catch (error) {
38
+ await rm(part, { force: true });
39
+ throw error;
40
+ }
41
+ return done;
42
+ };
12
43
  const volumes_export = {
13
44
  command: 'export',
14
- describe: 'Download the contents of a volume as a .tar.gz (the app keeps running)',
45
+ describe: 'Download the contents of a volume (or of a path of it) as a .tar.gz; the app keeps running',
15
46
  builder: yargs => volume_option(app_option(json_option(yargs)))
47
+ .option('path', {
48
+ type: 'string',
49
+ description: 'Only this file or directory of the volume (its path inside the archive is the same)'
50
+ })
16
51
  .option('output', {
17
52
  alias: 'o',
18
53
  type: 'string',
@@ -20,37 +55,77 @@ const volumes_export = {
20
55
  })
21
56
  .showHelpOnFail(false),
22
57
  handler: async (args) => {
58
+ const sub = volume_dest(args.path);
23
59
  const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
24
- const op = await api.createVolumeOperation(team, volume.id, 'export');
25
- if (!args.json)
26
- log.info(`๐Ÿ“ฆ Exporting ${app.name}/${volume.name} (${op.id})`);
27
- const done = require_completed(await wait_operation(api, team, op, {
28
- onState: s => {
29
- if (!args.json && s !== 'completed' && s !== 'failed')
30
- log.info(state_label[s]);
31
- }
32
- }));
33
- // The completed operation read by wait_operation carries a fresh URL.
34
- const url = done.download_url;
35
- if (!url) {
36
- throw new CliError('not_found', `The export ${done.id} finished but has no download link; try faable deploy volumes export again`);
37
- }
38
60
  const day = new Date().toISOString().slice(0, 10);
39
61
  const file = args.output ?? `${app.name}-${volume.name}-${day}.tar.gz`;
40
- const part = `${file}.part`;
41
- const res = await axios.get(url, { responseType: 'stream', timeout: 0 });
42
- try {
43
- await pipeline(res.data, createWriteStream(part));
44
- await rename(part, file);
45
- }
46
- catch (error) {
47
- await rm(part, { force: true });
48
- throw error;
49
- }
62
+ if (!args.json)
63
+ log.info(`๐Ÿ“ฆ Exporting ${app.name}/${volume.name}${sub === '.' ? '' : `:${sub}`}`);
64
+ const done = await export_to_file(api, team, volume.id, sub === '.' ? undefined : sub, file, !!args.json);
50
65
  if (args.json)
51
66
  return print_json({ ...done, file });
52
67
  log.info(`โœ… Saved ${file} (${format_bytes(done.size_bytes)}).`);
53
68
  }
54
69
  };
70
+ const volumes_get = {
71
+ command: 'get <path>',
72
+ describe: 'Copy a file or directory of a volume here, like cp: it lands as <output>/<its name>. Existing local files are never overwritten',
73
+ builder: yargs => volume_option(app_option(json_option(yargs)))
74
+ .positional('path', {
75
+ type: 'string',
76
+ demandOption: true,
77
+ description: 'A file or directory of the volume, relative to its root'
78
+ })
79
+ .option('output', {
80
+ alias: 'o',
81
+ type: 'string',
82
+ default: '.',
83
+ description: 'The local directory it goes into'
84
+ })
85
+ .example('$0 deploy volumes get wp-content/mu-plugins/my-plugin -a my-blog', 'A mu-plugin of a WordPress app into ./my-plugin')
86
+ .showHelpOnFail(false),
87
+ handler: async (args) => {
88
+ const sub = volume_dest(args.path);
89
+ if (sub === '.') {
90
+ throw new CliError('usage', 'get copies a file or directory; the whole volume is faable deploy volumes export');
91
+ }
92
+ const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
93
+ const out = args.output ?? '.';
94
+ // Like cp, but never over what is here: GNU tar -k fails on an existing
95
+ // file, macOS tar skips it in silence; say it before downloading.
96
+ const local_target = path.join(out, path.posix.basename(sub));
97
+ if (await stat(local_target).catch(() => null)) {
98
+ throw new CliError('usage', `${local_target} already exists: nothing is overwritten (move it, or --output another directory)`);
99
+ }
100
+ const work = await mkdtemp(path.join(tmpdir(), 'faable-volume-get-'));
101
+ try {
102
+ if (!args.json)
103
+ log.info(`๐Ÿ“ฅ Copying ${app.name}/${volume.name}:${sub} into ${out}`);
104
+ const archive = path.join(work, 'get.tar.gz');
105
+ const done = await export_to_file(api, team, volume.id, sub, archive, !!args.json);
106
+ await mkdir(out, { recursive: true });
107
+ // The archive holds the path as it is in the volume: strip its parents
108
+ // so it lands as <out>/<name>. -k: an existing local file is an error,
109
+ // never overwritten.
110
+ const strip = sub.split('/').length - 1;
111
+ await exec_file('tar', [
112
+ '-xzkf',
113
+ archive,
114
+ '-C',
115
+ out,
116
+ ...(strip ? [`--strip-components=${strip}`] : [])
117
+ ]).catch((error) => {
118
+ throw new CliError('usage', `Could not unpack into ${out}: ${(error.stderr ?? String(error)).trim().split('\n')[0]}`);
119
+ });
120
+ const local = local_target;
121
+ if (args.json)
122
+ return print_json({ ...done, local });
123
+ log.info(`โœ… ${local} (${format_bytes(done.size_bytes)} compressed).`);
124
+ }
125
+ finally {
126
+ await rm(work, { recursive: true, force: true });
127
+ }
128
+ }
129
+ };
55
130
 
56
- export { volumes_export };
131
+ export { volumes_export, volumes_get };
@@ -1,8 +1,10 @@
1
1
  import { volumes_backups, volumes_backup } from './backups.js';
2
- import { volumes_export } from './export.js';
2
+ import { volumes_get, volumes_export } from './export.js';
3
3
  import { volumes_import, volumes_put } from './import.js';
4
4
  import { volumes_list } from './list.js';
5
+ import { volumes_ls } from './ls.js';
5
6
  import { volumes_restore } from './restore.js';
7
+ import { volumes_rm } from './rm.js';
6
8
 
7
9
  // The volumes of an app (api `/volume`, `/volume-operation`): today the ones
8
10
  // a blueprint defines (WordPress: `site` at /faable/app). Hidden until the
@@ -10,17 +12,20 @@ import { volumes_restore } from './restore.js';
10
12
  // describe below. Arch: deploy/volumenes-cli-comparativa.md (backlog ยง460).
11
13
  const volumes = {
12
14
  command: 'volumes <command>',
13
- // 'Manage the volumes of an app: usage, backups, restore, export, import and put'
15
+ // 'Manage the volumes of an app: usage, files (ls, get, put, rm), backups, restore, export and import'
14
16
  describe: false,
15
17
  builder: yargs => yargs
16
18
  .command(volumes_list)
19
+ .command(volumes_ls)
20
+ .command(volumes_get)
21
+ .command(volumes_rm)
17
22
  .command(volumes_backups)
18
23
  .command(volumes_backup)
19
24
  .command(volumes_restore)
20
25
  .command(volumes_export)
21
26
  .command(volumes_import)
22
27
  .command(volumes_put)
23
- .demandCommand(1, 'Specify a volumes command: list, backups, backup, restore, export, import or put'),
28
+ .demandCommand(1, 'Specify a volumes command: list, ls, get, rm, backups, backup, restore, export, import or put'),
24
29
  handler: () => {
25
30
  // Unreachable: demandCommand(1) either routes to a subcommand or fails
26
31
  // through the global .fail() in src/index.ts.
@@ -0,0 +1,38 @@
1
+ import { print_json, print, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { volume_dest, require_completed, wait_operation, format_entry } from './operation.js';
4
+ import { resolve_volume, volume_option } from './shared.js';
5
+ import { app_option } from '../schedule/shared.js';
6
+
7
+ const volumes_ls = {
8
+ command: 'ls [path]',
9
+ describe: 'List a directory of a volume (default its root), with the app serving',
10
+ builder: yargs => volume_option(app_option(json_option(yargs)))
11
+ .positional('path', {
12
+ type: 'string',
13
+ description: 'A directory of the volume, relative to its root'
14
+ })
15
+ .example('$0 deploy volumes ls wp-content/mu-plugins -a my-blog', 'The mu-plugins of a WordPress app')
16
+ .showHelpOnFail(false),
17
+ handler: async (args) => {
18
+ const sub = volume_dest(args.path);
19
+ const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
20
+ const op = await api.listVolumeFiles(team, volume.id, sub === '.' ? undefined : sub);
21
+ const done = require_completed(await wait_operation(api, team, op));
22
+ const entries = done.entries ?? [];
23
+ if (args.json)
24
+ return print_json({ path: sub, entries });
25
+ const where = `${app.name}/${volume.name}:${sub === '.' ? '/' : sub}`;
26
+ if (entries.length === 0) {
27
+ log.info(`๐Ÿ“‚ ${where} is empty.`);
28
+ return;
29
+ }
30
+ log.info(`๐Ÿ“‚ ${where}`);
31
+ for (const e of entries)
32
+ print(` ${format_entry(e)}`);
33
+ if (entries.length >= 1000)
34
+ log.info('Only the first 1000 entries, by name.');
35
+ }
36
+ };
37
+
38
+ export { volumes_ls };
@@ -74,5 +74,13 @@ const volume_dest = (to) => {
74
74
  return norm === '' ? '.' : norm;
75
75
  };
76
76
  const is_archive = (p) => /\.(tar\.gz|tgz)$/i.test(p);
77
+ const TYPE_MARK = { dir: 'd', file: '-', link: 'l', other: '?' };
78
+ /** `d โ€” 2026-11-02 13:32 ferp/` โ€” one line of `volumes ls`. */
79
+ const format_entry = (e) => {
80
+ const size = e.type === 'dir' ? 'โ€”' : format_bytes(e.size);
81
+ const when = e.mtime.slice(0, 16).replace('T', ' ');
82
+ const name = e.type === 'dir' ? `${e.name}/` : e.name;
83
+ return `${TYPE_MARK[e.type] ?? '?'} ${size.padStart(8)} ${when} ${name}`;
84
+ };
77
85
 
78
- export { format_bytes, format_usage, is_archive, require_completed, state_label, volume_dest, wait_operation };
86
+ export { format_bytes, format_entry, format_usage, is_archive, require_completed, state_label, volume_dest, wait_operation };
@@ -0,0 +1,100 @@
1
+ import { CliError } from '../../../lib/errors.js';
2
+ import { confirm } from '../../../lib/interactive.js';
3
+ import { print_json, json_option } from '../../../lib/listing.js';
4
+ import { log } from '../../../log.js';
5
+ import { resolve_app, app_option } from '../schedule/shared.js';
6
+ import { wait_operation, require_completed, volume_dest, state_label } from './operation.js';
7
+ import { resolve_volume, wait_option, volume_option } from './shared.js';
8
+
9
+ // rm never deletes on the spot (backlog ยง460): the paths go to the volume's
10
+ // trash, `--undo <rm id>` brings them back, and they are emptied 7 days later.
11
+ const volumes_rm = {
12
+ command: 'rm [paths..]',
13
+ describe: 'Move files or directories of a volume to its trash, with the app serving: --undo brings them back for 7 days, then they are emptied',
14
+ builder: yargs => wait_option(volume_option(app_option(json_option(yargs))))
15
+ .positional('paths', {
16
+ type: 'string',
17
+ array: true,
18
+ description: 'Files or directories of the volume, relative to its root'
19
+ })
20
+ .option('undo', {
21
+ type: 'string',
22
+ description: 'Bring back what an rm moved to the trash (its id)'
23
+ })
24
+ .option('yes', {
25
+ alias: 'y',
26
+ type: 'boolean',
27
+ default: false,
28
+ description: 'Skip the confirmation prompt'
29
+ })
30
+ .check(a => {
31
+ const n = (a.paths ?? []).length;
32
+ if (a.undo && n)
33
+ throw new Error('Either paths to rm, or --undo <rm id>');
34
+ if (!a.undo && !n)
35
+ throw new Error('Say what to rm, or --undo <rm id>');
36
+ return true;
37
+ })
38
+ .example('$0 deploy volumes rm wp-content/plugins/old-plugin -a my-blog', 'A plugin directory, to the trash')
39
+ .example('$0 deploy volumes rm --undo volumeop_โ€ฆ -a my-blog', 'Back from the trash')
40
+ .showHelpOnFail(false),
41
+ handler: async (args) => {
42
+ const onState = (s) => {
43
+ if (!args.json && s !== 'completed' && s !== 'failed')
44
+ log.info(state_label[s]);
45
+ };
46
+ if (args.undo) {
47
+ const { api, team, app } = await resolve_app(args.app);
48
+ const op = await api.undoVolumeOperation(team, args.undo);
49
+ if (!args.wait) {
50
+ if (args.json)
51
+ return print_json(op);
52
+ log.info(`โ™ป๏ธ Undo ${op.id} queued.`);
53
+ return;
54
+ }
55
+ if (!args.json)
56
+ log.info(`โ™ป๏ธ Bringing back ${(op.paths ?? []).join(', ')} in ${app.name}`);
57
+ const done = await wait_operation(api, team, op, { onState });
58
+ if (args.json)
59
+ print_json(done);
60
+ require_completed(done);
61
+ if (!args.json)
62
+ log.info('โœ… Back where they were.');
63
+ return;
64
+ }
65
+ const paths = (args.paths ?? []).map(p => {
66
+ const d = volume_dest(p);
67
+ if (d === '.') {
68
+ throw new CliError('usage', 'rm takes files or directories, not the whole volume');
69
+ }
70
+ return d;
71
+ });
72
+ const { api, team, app, volume } = await resolve_volume(args.app, args.volume);
73
+ const go = await confirm({
74
+ message: `Move ${paths.join(', ')} of ${app.name}/${volume.name} to the trash? They can be brought back for 7 days.`,
75
+ yes: args.yes
76
+ });
77
+ if (!go) {
78
+ log.info('Cancelled.');
79
+ return;
80
+ }
81
+ const op = await api.removeVolumePaths(team, volume.id, paths);
82
+ const undo = `faable deploy volumes rm --undo ${op.id} -a ${app.name}`;
83
+ if (!args.wait) {
84
+ if (args.json)
85
+ return print_json(op);
86
+ log.info(`๐Ÿ—‘ rm ${op.id} queued. To undo it: ${undo}`);
87
+ return;
88
+ }
89
+ const done = await wait_operation(api, team, op, { onState });
90
+ if (args.json)
91
+ print_json(done);
92
+ require_completed(done);
93
+ if (!args.json) {
94
+ log.info(`๐Ÿ—‘ Moved to the trash: ${paths.join(', ')}.`);
95
+ log.info(`To bring them back (7 days): ${undo}`);
96
+ }
97
+ }
98
+ };
99
+
100
+ export { volumes_rm };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.27.0",
3
+ "version": "4.29.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",