@faable/faable 4.24.0 → 4.26.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.
@@ -341,6 +341,38 @@ class FaableApi {
341
341
  // Rebuild a failed deployment from its recorded source (CAS manifest or
342
342
  // git ref). The API enforces the guards: failed phase only, never older
343
343
  // than what production serves.
344
+ // Tasks (one-off commands in a copy of the app's pod; api `task/`).
345
+ async createTask(team, body) {
346
+ return data(this.client.post(`/task`, body, {
347
+ headers: projectHeader(team)
348
+ }));
349
+ }
350
+ async listTaskSchedules(team, app_id) {
351
+ return data(this.client.get(`/taskschedule`, {
352
+ params: { app_id },
353
+ headers: projectHeader(team)
354
+ }));
355
+ }
356
+ async createTaskSchedule(team, body) {
357
+ return data(this.client.post(`/taskschedule`, body, {
358
+ headers: projectHeader(team)
359
+ }));
360
+ }
361
+ async updateTaskSchedule(team, id, body) {
362
+ return data(this.client.post(`/taskschedule/${id}`, body, {
363
+ headers: projectHeader(team)
364
+ }));
365
+ }
366
+ async deleteTaskSchedule(team, id) {
367
+ return data(this.client.delete(`/taskschedule/${id}`, {
368
+ headers: projectHeader(team)
369
+ }));
370
+ }
371
+ async getTask(task_id, team) {
372
+ return data(this.client.get(`/task/${task_id}`, {
373
+ headers: projectHeader(team)
374
+ }));
375
+ }
344
376
  async redeployDeployment(deployment_id, team) {
345
377
  return data(this.client.post(`/deployment/${deployment_id}/redeploy`, undefined, { headers: projectHeader(team) }));
346
378
  }
@@ -1,7 +1,7 @@
1
- import { github } from './github/index.js';
2
1
  import { link } from '../link/index.js';
3
2
  import { apps, apps_list_legacy } from './apps/index.js';
4
3
  import { domains } from './domains/index.js';
4
+ import { github } from './github/index.js';
5
5
  import { capture_deploy_help } from './help.js';
6
6
  import { cancel } from './inspect/cancel.js';
7
7
  import { deployments } from './inspect/deployments.js';
@@ -9,11 +9,13 @@ import { inspect } from './inspect/inspect.js';
9
9
  import { logs } from './inspect/logs.js';
10
10
  import { open_app } from './inspect/open.js';
11
11
  import { redeploy } from './inspect/redeploy.js';
12
+ import { run } from './inspect/run.js';
12
13
  import { status } from './inspect/status.js';
13
14
  import { traffic } from './inspect/traffic.js';
14
15
  import { trigger } from './inspect/trigger.js';
15
16
  import { launch } from './launch.js';
16
17
  import { usage, quota } from './project_usage.js';
18
+ import { schedule } from './schedule/index.js';
17
19
  import { secrets } from './secrets/index.js';
18
20
  import { waf } from './waf/index.js';
19
21
 
@@ -43,6 +45,8 @@ const deploy = {
43
45
  .command(waf)
44
46
  .command(logs)
45
47
  .command(status)
48
+ .command(run)
49
+ .command(schedule)
46
50
  .command(traffic)
47
51
  .command(usage)
48
52
  .command(quota)
@@ -0,0 +1,78 @@
1
+ import { requireApi } from '../../../api/context.js';
2
+ import { CliError } from '../../../lib/errors.js';
3
+ import { print_json, json_option } from '../../../lib/listing.js';
4
+ import { log } from '../../../log.js';
5
+ import { resolve_app_id } from '../resolve_app_id.js';
6
+ import { waitForTask } from './task_wait.js';
7
+
8
+ const run = {
9
+ command: 'run',
10
+ // Hobby and Pro on code apps; blueprint apps run only their own commands
11
+ // (api deploy/task/task.ts). Published 2026-11-01 with task schedules.
12
+ describe: 'Run a one-off command with the image, variables and volumes of the live deployment',
13
+ builder: yargs => json_option(yargs)
14
+ .parserConfiguration({ 'populate--': true })
15
+ .option('app', {
16
+ alias: 'a',
17
+ type: 'string',
18
+ description: 'App id, name or slug (defaults to the linked app)'
19
+ })
20
+ .option('wait', {
21
+ type: 'boolean',
22
+ default: true,
23
+ description: 'Wait for the result and print its output (--no-wait to only queue it)'
24
+ })
25
+ .option('timeout', {
26
+ type: 'number',
27
+ description: 'Seconds before the task is stopped (default 900, max 3600)'
28
+ })
29
+ .example('$0 deploy run -a my-blog -- wp plugin list', 'wp-cli on a WordPress app')
30
+ .example('$0 deploy run -- node scripts/migrate.js', 'A script of your own app')
31
+ .showHelpOnFail(false),
32
+ handler: async (args) => {
33
+ const argv = (args['--'] ?? []).map(String);
34
+ if (argv.length === 0) {
35
+ throw new CliError('usage', 'Say what to run after --, e.g. faable deploy run -- wp plugin list');
36
+ }
37
+ const ctx = await requireApi();
38
+ const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
39
+ const app = await ctx.api.getApp(app_id);
40
+ const queued = await ctx.api.createTask(app.team, {
41
+ app_id,
42
+ argv,
43
+ ...(args.timeout ? { timeout_s: args.timeout } : {})
44
+ });
45
+ if (!args.wait) {
46
+ if (args.json)
47
+ return print_json(queued);
48
+ log.info(`🧰 Queued ${queued.id} on ${app.name}.`);
49
+ return;
50
+ }
51
+ if (!args.json)
52
+ log.info(`🧰 ${argv.join(' ')} on ${app.name} (${queued.id})`);
53
+ const done = await waitForTask(() => ctx.api.getTask(queued.id, app.team), {
54
+ onStatus: s => {
55
+ if (!args.json && s === 'running')
56
+ log.info('… running');
57
+ }
58
+ });
59
+ if (args.json) {
60
+ print_json(done);
61
+ }
62
+ else {
63
+ if (done.output_tail)
64
+ process.stdout.write(done.output_tail.replace(/\n?$/, '\n'));
65
+ const how = done.status === 'succeeded'
66
+ ? '✅ Done'
67
+ : done.status === 'timed_out'
68
+ ? '⏱️ Timed out'
69
+ : `❌ ${done.reason ?? 'Failed'}`;
70
+ log.info(`${how}${done.exit_code != null ? ` (exit ${done.exit_code})` : ''}`);
71
+ }
72
+ // The command's own exit code, so scripts can branch on it.
73
+ if (done.status !== 'succeeded')
74
+ process.exitCode = done.exit_code || 1;
75
+ }
76
+ };
77
+
78
+ export { run };
@@ -0,0 +1,18 @@
1
+ const DONE = new Set(['succeeded', 'failed', 'timed_out', 'canceled']);
2
+ const POLL_MS = 3000;
3
+ /** Polls a task until it is done (or the caller's patience runs out). */
4
+ const waitForTask = async (get, opts = {}) => {
5
+ const sleep = opts.sleep ?? (ms => new Promise(r => setTimeout(r, ms)));
6
+ let last = '';
7
+ for (;;) {
8
+ const t = await get();
9
+ if (t.status !== last)
10
+ opts.onStatus?.(t.status);
11
+ last = t.status;
12
+ if (DONE.has(t.status))
13
+ return t;
14
+ await sleep(POLL_MS);
15
+ }
16
+ };
17
+
18
+ export { waitForTask };
@@ -0,0 +1,51 @@
1
+ import { CliError } from '../../../lib/errors.js';
2
+ import { print_json, print, json_option } from '../../../lib/listing.js';
3
+ import { log } from '../../../log.js';
4
+ import { format_schedule } from './format.js';
5
+ import { resolve_app, app_option } from './shared.js';
6
+
7
+ const schedule_add = {
8
+ command: 'add',
9
+ describe: 'Run a command of the app on a cron schedule (UTC)',
10
+ builder: yargs => app_option(json_option(yargs))
11
+ .parserConfiguration({ 'populate--': true })
12
+ // No `-c`: it is the global --config.
13
+ .option('cron', {
14
+ type: 'string',
15
+ demandOption: true,
16
+ description: 'Five-field cron expression in UTC (minute hour day month weekday), at most every 5 minutes'
17
+ })
18
+ .option('name', {
19
+ alias: 'n',
20
+ type: 'string',
21
+ description: 'A name to recognise it by'
22
+ })
23
+ .option('timeout', {
24
+ type: 'number',
25
+ description: 'Seconds before each run is stopped (default 900, max 3600)'
26
+ })
27
+ .example('$0 deploy schedule add --cron "*/15 * * * *" -- node scripts/followups.js', 'Every 15 minutes')
28
+ .example('$0 deploy schedule add --cron "0 7 * * 1-5" -n digest -- npm run digest', 'Weekdays at 07:00 UTC')
29
+ .showHelpOnFail(false),
30
+ handler: async (args) => {
31
+ const argv = (args['--'] ?? []).map(String);
32
+ if (argv.length === 0) {
33
+ throw new CliError('usage', 'Say what to run after --, e.g. faable deploy schedule add --cron "*/15 * * * *" -- node job.js');
34
+ }
35
+ const { api, app_id, app, team } = await resolve_app(args.app);
36
+ const s = await api.createTaskSchedule(team, {
37
+ app_id,
38
+ cron: args.cron,
39
+ argv,
40
+ ...(args.name ? { name: args.name } : {}),
41
+ ...(args.timeout ? { timeout_s: args.timeout } : {})
42
+ });
43
+ if (args.json)
44
+ return print_json(s);
45
+ log.info(`⏰ Scheduled on ${app.name}. Each run is a task: faable deploy run shows the same output.`);
46
+ for (const line of format_schedule(s))
47
+ print(line);
48
+ }
49
+ };
50
+
51
+ export { schedule_add };
@@ -0,0 +1,27 @@
1
+ // Why the last due run did not start, in the user's words. Matches the api's
2
+ // `skip_reason` (deploy/task/TaskSchedule.model.ts).
3
+ const SKIP = {
4
+ plan_required: 'paused — the project is not on Hobby or Pro (resumes when it is)',
5
+ previous_running: 'skipped — the previous run was still going',
6
+ app_unavailable: 'skipped — the app has no live deployment',
7
+ enqueue_failed: 'skipped — the task could not be queued'
8
+ };
9
+ const format_schedule = (s) => {
10
+ const lines = [
11
+ `${s.enabled ? '●' : '○'} ${s.id}${s.name ? ` ${s.name}` : ''}`,
12
+ ` ${s.cron} (UTC) → ${s.argv.join(' ')}`
13
+ ];
14
+ if (!s.enabled)
15
+ lines.push(' off');
16
+ else if (s.next_run_at)
17
+ lines.push(` next run ${s.next_run_at}`);
18
+ else
19
+ lines.push(' never runs again');
20
+ if (s.last_run_at)
21
+ lines.push(` last run ${s.last_run_at} (${s.last_task_id ?? '—'})`);
22
+ if (s.skip_reason)
23
+ lines.push(` ${SKIP[s.skip_reason] ?? s.skip_reason}`);
24
+ return lines;
25
+ };
26
+
27
+ export { format_schedule };
@@ -0,0 +1,24 @@
1
+ import { schedule_add } from './add.js';
2
+ import { schedule_list } from './list.js';
3
+ import { schedule_rm } from './rm.js';
4
+ import { schedule_enable, schedule_disable } from './toggle.js';
5
+
6
+ // Task schedules (api `/taskschedule`, Hobby and Pro): a cron expression that
7
+ // runs a task of the app — the same thing `faable deploy run` runs once.
8
+ const schedule = {
9
+ command: 'schedule <command>',
10
+ describe: 'Run a command of the app on a cron schedule (Hobby and Pro)',
11
+ builder: yargs => yargs
12
+ .command(schedule_list)
13
+ .command(schedule_add)
14
+ .command(schedule_enable)
15
+ .command(schedule_disable)
16
+ .command(schedule_rm)
17
+ .demandCommand(1, 'Specify a schedule command: list, add, enable, disable or rm'),
18
+ handler: () => {
19
+ // Unreachable: demandCommand(1) either routes to a subcommand or fails
20
+ // through the global .fail() in src/index.ts.
21
+ }
22
+ };
23
+
24
+ export { schedule };
@@ -0,0 +1,27 @@
1
+ import { print_json, print, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { format_schedule } from './format.js';
4
+ import { resolve_app, app_option } from './shared.js';
5
+
6
+ const schedule_list = {
7
+ command: 'list',
8
+ describe: 'Show the task schedules of the app',
9
+ builder: yargs => app_option(json_option(yargs)).showHelpOnFail(false),
10
+ handler: async (args) => {
11
+ const { api, app_id, app, team } = await resolve_app(args.app);
12
+ const { results } = await api.listTaskSchedules(team, app_id);
13
+ if (args.json)
14
+ return print_json(results);
15
+ if (results.length === 0) {
16
+ log.info(`No schedules on ${app.name}. Add one with: faable deploy schedule add --cron "*/15 * * * *" -- <command>`);
17
+ return;
18
+ }
19
+ log.info(`⏰ Schedules of ${app.name} (${app_id})`);
20
+ log.info('');
21
+ for (const s of results)
22
+ for (const line of format_schedule(s))
23
+ print(line);
24
+ }
25
+ };
26
+
27
+ export { schedule_list };
@@ -0,0 +1,23 @@
1
+ import { print_json, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { resolve_app, app_option } from './shared.js';
4
+
5
+ const schedule_rm = {
6
+ command: 'rm <id>',
7
+ describe: 'Delete a schedule (runs already queued keep going)',
8
+ builder: yargs => app_option(json_option(yargs))
9
+ .positional('id', {
10
+ type: 'string',
11
+ description: 'The schedule id (see `faable deploy schedule list`)'
12
+ })
13
+ .showHelpOnFail(false),
14
+ handler: async (args) => {
15
+ const { api, team } = await resolve_app(args.app);
16
+ const s = await api.deleteTaskSchedule(team, args.id);
17
+ if (args.json)
18
+ return print_json(s);
19
+ log.info(`🗑 Deleted ${s.id}${s.name ? ` (${s.name})` : ''}.`);
20
+ }
21
+ };
22
+
23
+ export { schedule_rm };
@@ -0,0 +1,17 @@
1
+ import { requireApi } from '../../../api/context.js';
2
+ import { resolve_app_id } from '../resolve_app_id.js';
3
+
4
+ const app_option = (yargs) => yargs.option('app', {
5
+ alias: 'a',
6
+ type: 'string',
7
+ description: 'App id, name or slug (defaults to the linked app)'
8
+ });
9
+ /** The app the command acts on, with the project its calls go to. */
10
+ const resolve_app = async (app) => {
11
+ const ctx = await requireApi();
12
+ const app_id = await resolve_app_id(app, ctx.appId, ctx.api);
13
+ const found = await ctx.api.getApp(app_id);
14
+ return { api: ctx.api, app_id, app: found, team: found.team };
15
+ };
16
+
17
+ export { app_option, resolve_app };
@@ -0,0 +1,30 @@
1
+ import { print_json, print, json_option } from '../../../lib/listing.js';
2
+ import { log } from '../../../log.js';
3
+ import { format_schedule } from './format.js';
4
+ import { resolve_app, app_option } from './shared.js';
5
+
6
+ const toggle = (enabled) => ({
7
+ command: `${enabled ? 'enable' : 'disable'} <id>`,
8
+ describe: enabled
9
+ ? 'Turn a schedule back on (it runs from its next slot)'
10
+ : 'Stop a schedule without deleting it',
11
+ builder: yargs => app_option(json_option(yargs))
12
+ .positional('id', {
13
+ type: 'string',
14
+ description: 'The schedule id (see `faable deploy schedule list`)'
15
+ })
16
+ .showHelpOnFail(false),
17
+ handler: async (args) => {
18
+ const { api, team } = await resolve_app(args.app);
19
+ const s = await api.updateTaskSchedule(team, args.id, { enabled });
20
+ if (args.json)
21
+ return print_json(s);
22
+ log.info(enabled ? '⏰ Schedule on.' : '⏸ Schedule off.');
23
+ for (const line of format_schedule(s))
24
+ print(line);
25
+ }
26
+ });
27
+ const schedule_enable = toggle(true);
28
+ const schedule_disable = toggle(false);
29
+
30
+ export { schedule_disable, schedule_enable };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.24.0",
3
+ "version": "4.26.0",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",