@swell/cli 2.9.31 → 2.9.32

package/dist/commands/app/action.d.ts

@@ -0,0 +1,25 @@
+import { RemoteAppCommand } from '../../remote-app-command.js';
+export default class AppAction extends RemoteAppCommand {
+    static args: {
+        id: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        all: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        collection: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        ids: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        live: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        record: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        settings: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        source: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        values: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        view: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+    private findAction;
+    private findFunctionId;
+    private getActionParams;
+    private parseValues;
+}

package/dist/commands/app/action.js

@@ -0,0 +1,233 @@
+import { Args, Flags } from '@oclif/core';
+import ora from 'ora';
+import { functionSlug, getContentActions, getModalFieldIds, getSettingsActions, } from '../../lib/apps/actions.js';
+import style from '../../lib/style.js';
+import { RemoteAppCommand } from '../../remote-app-command.js';
+const UNAVAILABLE_CODES = new Set([
+    'notfound',
+    'connrefused',
+    'proxy_notfound',
+]);
+export default class AppAction extends RemoteAppCommand {
+    static args = {
+        id: Args.string({
+            description: 'id of the action, as declared in content or settings',
+            required: true,
+        }),
+    };
+    static description = `Runs a function action of the app as the logged-in dashboard user, the way a click in the dashboard does. The action is looked up in the app's content and settings as pushed.
+
+A record action or action field needs ${style.command('--record')}, and a bulk action ${style.command('--ids')} or ${style.command('--all')}. Pass the values of the action's modal with ${style.command('--values')}. When the same id is declared in more than one place, pick one with ${style.command('--collection')}, ${style.command('--view')}, ${style.command('--settings')} or ${style.command('--source')}.`;
+    static examples = [
+        'swell app action sync_now',
+        'swell app action ship --record 64e8dfb633c44a0039477251',
+        `swell app action ship --record 64e8dfb633c44a0039477251 --values '{"carrier":"ups"}'`,
+        'swell app action ship-selected --ids 64e8dfb633c44a0039477251,64e8dfb633c44a0039477252',
+        'swell app action ship --collection shipments --view edit --record 64e8dfb633c44a0039477251',
+        'swell app action export --source bulk --all',
+    ];
+    static flags = {
+        all: Flags.boolean({
+            description: 'run a bulk action on all records its view lists with no filters set, as selecting all in the dashboard does',
+            exclusive: ['ids'],
+        }),
+        collection: Flags.string({
+            description: "collection of the content that declares the action, or the model's name for a collection of the app",
+        }),
+        ids: Flags.string({
+            description: 'comma-separated ids of the records a bulk action runs on',
+            exclusive: ['all'],
+        }),
+        live: Flags.boolean({
+            default: false,
+            description: 'run in the live environment instead of test',
+        }),
+        record: Flags.string({
+            description: 'id of the record a record action or action field runs on',
+        }),
+        settings: Flags.string({
+            description: 'name of the settings that declare the action',
+        }),
+        source: Flags.string({
+            description: "where the action is declared: list or record (a view's actions), bulk (a view's bulk actions), field (an action field) or settings (a settings action)",
+            options: ['list', 'record', 'bulk', 'field', 'settings'],
+        }),
+        values: Flags.string({
+            description: "values of the action's modal fields, as JSON",
+        }),
+        view: Flags.string({
+            description: 'id of the content view that declares the action',
+        }),
+    };
+    static summary = 'Run an app action from the command line.';
+    async run() {
+        const { args, flags } = await this.parse(AppAction);
+        const values = flags.values === undefined ? undefined : this.parseValues(flags.values);
+        if (!flags.live) {
+            await this.api.setEnv('test');
+        }
+        this.app = await this.getAppWithConfig();
+        const action = await this.findAction(args.id, flags);
+        const $action = this.getActionParams(action, { ...flags, values });
+        const functionId = await this.findFunctionId(action.function);
+        const name = style.appConfigValue(action.id);
+        const spinner = ora();
+        spinner.start(`Running action ${name}...`);
+        const result = await this.handleRequestErrors(async () => this.api.put({ adminPath: `/data/:functions/${functionId}` }, { body: { $action } }), () => spinner.fail(`Action ${action.id} failed`));
+        if (!(result?.status >= 200 && result.status < 300)) {
+            spinner.fail(`Action ${name} failed`);
+            this.error(getErrorMessage(result, name));
+        }
+        // A workflow runs in the background, so the platform answers with the run
+        // it started
+        const run = result.response?.run;
+        if (result.status === 202 && run?.id && run.workflow_name) {
+            spinner.succeed(`Started run ${style.appConfigValue(run.id)} of workflow ${style.appConfigValue(run.workflow_name)}`);
+            return;
+        }
+        spinner.succeed(`Ran action ${name}`);
+        if (result.response !== undefined) {
+            this.log(JSON.stringify(result.response, null, 2));
+        }
+    }
+    async findAction(id, flags) {
+        const [contents, settings] = await Promise.all([
+            this.api.get({ adminPath: '/data/:content' }, { query: { app_id: this.app.id, limit: 1000 } }),
+            this.api.get({ adminPath: `/data/:settings/${this.app.id}` }),
+        ]);
+        const actions = [
+            ...(contents?.results || []).flatMap((content) => getContentActions(content).map((action) => ({
+                ...action,
+                collection: content.collection,
+                content_id: content.id,
+            }))),
+            ...Object.entries(settings?.content || {}).flatMap(([name, values]) => getSettingsActions(values, name)),
+        ];
+        // Content of the app's own model has the collection apps/<app id>/<model>
+        const appCollection = `apps/${this.app.id}/`;
+        const matches = actions.filter((action) => action.id === id &&
+            (!flags.collection ||
+                action.collection === flags.collection ||
+                action.collection === `${appCollection}${flags.collection}`) &&
+            (!flags.view || action.view === flags.view) &&
+            (!flags.settings || action.settings === flags.settings) &&
+            (!flags.source || action.source === flags.source));
+        if (matches.length === 0) {
+            this.error(`Action ${style.appConfigValue(id)} not found in the app's content or settings. Push the app first if it is new.`);
+        }
+        if (matches.length > 1) {
+            this.error(`Action ${style.appConfigValue(id)} is declared in more than one place:\n${matches
+                .map((action) => `  ${describePlace(action, appCollection)}`)
+                .join('\n')}\nPick one with --collection, --view, --settings or --source.`);
+        }
+        return matches[0];
+    }
+    async findFunctionId(name) {
+        const functions = await this.api.get({ adminPath: '/data/:functions' }, { query: { app_id: this.app.id, fields: 'id, name', limit: 1000 } });
+        const record = (functions?.results || []).find((record) => functionSlug(record.name) === functionSlug(name));
+        if (!record) {
+            this.error(`Function ${style.appConfigValue(name)} of the action is not installed. Push the app first.`);
+        }
+        return record.id;
+    }
+    getActionParams(action, flags) {
+        const name = style.appConfigValue(action.id);
+        const isBulk = action.source === 'bulk';
+        const needsRecord = action.source === 'record' ||
+            (action.source === 'field' && !action.settings);
+        if (needsRecord && !flags.record) {
+            this.error(`Action ${name} runs on a record: pass --record.`);
+        }
+        if (!needsRecord && flags.record) {
+            this.error(isBulk
+                ? `Action ${name} is a bulk action, which runs on --ids or --all: leave out --record.`
+                : `Action ${name} does not run on a record: leave out --record.`);
+        }
+        if (isBulk && !flags.ids && !flags.all) {
+            this.error(`Action ${name} is a bulk action: pass --ids or --all.`);
+        }
+        if (!isBulk && (flags.ids || flags.all)) {
+            this.error(`Action ${name} is not a bulk action: leave out ${flags.ids ? '--ids' : '--all'}.`);
+        }
+        // The platform passes on only the values of the modal's fields
+        if (flags.values) {
+            if (!action.modal) {
+                this.error(`Action ${name} has no modal: leave out --values.`);
+            }
+            const fieldIds = getModalFieldIds(action.modal);
+            const unknownKeys = Object.keys(flags.values).filter((key) => !fieldIds.includes(key));
+            if (unknownKeys.length > 0) {
+                this.error(`--values names fields that the modal of action ${name} does not have: ${unknownKeys.join(', ')}.`);
+            }
+        }
+        return {
+            id: action.id,
+            source: action.source,
+            ...(action.settings
+                ? { settings: action.settings }
+                : { content_id: action.content_id }),
+            ...(action.view ? { view: action.view } : undefined),
+            ...(needsRecord ? { record_id: flags.record } : undefined),
+            ...(isBulk
+                ? { selection: getSelection(flags.ids, action.query) }
+                : undefined),
+            ...(flags.values ? { values: flags.values } : undefined),
+        };
+    }
+    parseValues(values) {
+        let parsed;
+        try {
+            parsed = JSON.parse(values);
+        }
+        catch {
+            // ignore
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            this.error('--values must be a JSON object of the modal field values, like \'{"carrier":"ups"}\'');
+        }
+        return parsed;
+    }
+}
+// The function answers as it likes, so only a string is a message
+function resultMessage(message) {
+    return typeof message === 'string' ? message : '';
+}
+// As the dashboard reads a result that did not succeed
+function getErrorMessage(result, name) {
+    const { code, response } = result || {};
+    if (code === 'timeout') {
+        return `Action ${name} did not finish within the time limit. It may still be running; check before running it again.`;
+    }
+    if (UNAVAILABLE_CODES.has(code)) {
+        return 'The app function is unavailable.';
+    }
+    return (resultMessage(response?.$reject?.message) ||
+        resultMessage(response?.error?.message) ||
+        resultMessage(response?.error) ||
+        `Action ${name} failed`);
+}
+function describePlace(action, appCollection) {
+    const collection = action.collection?.startsWith(appCollection)
+        ? action.collection.slice(appCollection.length)
+        : action.collection;
+    return action.settings
+        ? `settings ${action.settings} (${action.source})`
+        : `content ${collection}${action.view ? `, view ${action.view}` : ''} (${action.source})`;
+}
+// As the dashboard selects records: by their ids, or all of them that the
+// view lists with no filters set
+function getSelection(ids, viewQuery = {}) {
+    if (!ids) {
+        return { all: true, count: null, query: viewQuery };
+    }
+    const list = ids
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+    return {
+        all: false,
+        count: list.length,
+        ids: list,
+        query: { $and: [{ id: { $in: list } }] },
+    };
+}

package/dist/commands/app/frontend/deploy.d.ts

@@ -12,5 +12,6 @@ export default class AppFrontendDeploy extends PushAppCommand {
         env: string;
     };
     static summary: string;
+    protected pushesSwellJson(): boolean;
     run(): Promise<void>;
 }

package/dist/commands/app/frontend/deploy.js

@@ -31,6 +31,10 @@ If deployment fails, correct any reported errors and run this command again.`;
         env: 'test',
     };
     static summary = `Push frontend files to your Swell app.`;
+    // A deploy pushes no app files, so it applies nothing of the listing
+    pushesSwellJson() {
+        return false;
+    }
     async run() {
         const { flags } = await this.parse(AppFrontendDeploy);
         const { force } = flags;

package/dist/commands/app/push.d.ts

@@ -28,5 +28,7 @@ export default class AppPush extends PushAppCommand {
      */
     confirmPushConflicts(conflictsFlag?: string, file?: string): Promise<boolean>;
     run(): Promise<void>;
+    protected pushesSwellJson(file?: string): boolean;
+    private checkActionFunctions;
     private exitIfFilesFailed;
 }

package/dist/commands/app/push.js

@@ -1,6 +1,8 @@
 import { Args, Flags } from '@oclif/core';
 import * as path from 'node:path';
-import { affectsFrontendDeployment, AllConfigPaths, filePathExistsAsync, isPathDirectory, sameIntegrations, } from '../../lib/apps/index.js';
+import ora from 'ora';
+import { functionSlug, getContentActions, getSettingsActions, } from '../../lib/apps/actions.js';
+import { affectsFrontendDeployment, AllConfigPaths, filePathExistsAsync, isPathDirectory, sameIntegrations, toPosixPath, } from '../../lib/apps/index.js';
 import { default as localConfig } from '../../lib/config.js';
 import style from '../../lib/style.js';
 import { PushAppCommand } from '../../push-app-command.js';
@@ -19,7 +21,7 @@ If the app does not exist, it will be created and its global ID saved to a .swel
 
 - If no file is specified, all configuration files will be pushed to the store.
   This includes the app icon (assets/icon.png), screenshots (assets/screenshots/),
-  README.md, and swell.json.
+  DESCRIPTION.md, and swell.json.
 - If a file is specified, only that file will be pushed to the store.
 - If a directory is specified, only files in that directory will be pushed.
 
@@ -151,6 +153,7 @@ ${Object.values(AllConfigPaths)
                 if (!noDeploy && affectsFrontendDeployment(relativePath)) {
                     await this.deployAppFrontend(force);
                 }
+                await this.checkActionFunctions(toPosixPath(relativePath));
                 this.log();
                 this.logDashboardUrl(flags);
                 this.exitIfFilesFailed();
@@ -158,6 +161,7 @@ ${Object.values(AllConfigPaths)
             }
         }
         await this.pushAppConfigs(force);
+        await this.checkActionFunctions();
         if (!noDeploy) {
             await this.deployAppFrontend(force);
             this.log();
@@ -165,6 +169,63 @@ ${Object.values(AllConfigPaths)
         this.logDashboardUrl(flags);
         this.exitIfFilesFailed();
     }
+    // The app path is the working directory unless --app-path names it, so a
+    // scoped push's file resolves here as in resolvePushPaths
+    pushesSwellJson(file) {
+        if (!file) {
+            return true;
+        }
+        const relativePath = path.relative(this.appPath, path.resolve(this.appPath, file));
+        return relativePath === '' || relativePath === 'swell.json';
+    }
+    // Content and settings are installed before functions, so their actions
+    // are checked against the app's functions once the push is done. A scoped
+    // push fails only for the files it pushed, and for the files whose action
+    // function it pushed or removed.
+    async checkActionFunctions(scope) {
+        const configs = await this.api
+            .getAll({ adminPath: `/apps/${this.app.id}/configs` }, { query: { type: { $in: ['function', 'content', 'setting'] } } })
+            .catch((error) => {
+            ora().warn(`Skipped checking the actions against the app functions: ${error.message}`);
+            return null;
+        });
+        if (!configs) {
+            return;
+        }
+        const { results } = configs;
+        const actionFunctions = new Set(results
+            .filter((config) => config.type === 'function' && config.values?.action)
+            .map((config) => functionSlug(config.name)));
+        const inScope = (filePath) => !scope || filePath === scope || filePath?.startsWith(`${scope}/`);
+        // The app's configs from before the push still name the functions it
+        // removed
+        const pushedFunctions = new Set([...results, ...(this.app.configs || [])]
+            .filter((config) => config.type === 'function' && inScope(config.file_path))
+            .map((config) => functionSlug(config.name)));
+        for (const config of results) {
+            const actions = config.type === 'content'
+                ? getContentActions(config.values)
+                : config.type === 'setting'
+                    ? getSettingsActions(config.values, config.name)
+                    : [];
+            const missing = actions.filter((action) => !actionFunctions.has(functionSlug(action.function)));
+            let failed = false;
+            for (const action of missing) {
+                const message = `${config.file_path}: action "${action.id}" runs function "${action.function}", which the app does not have as an action function`;
+                if (inScope(config.file_path) ||
+                    pushedFunctions.has(functionSlug(action.function))) {
+                    ora().fail(message);
+                    failed = true;
+                }
+                else {
+                    ora().warn(message);
+                }
+            }
+            if (failed && !this.failedFiles.includes(config.file_path)) {
+                this.failedFiles.push(config.file_path);
+            }
+        }
+    }
     // A skipped file is a failed push, for scripts and CI too
     exitIfFilesFailed() {
         if (this.failedFiles.length > 0) {

package/dist/commands/create/webhook.js

@@ -1,4 +1,4 @@
-import { confirm, input } from '@inquirer/prompts';
+import { input } from '@inquirer/prompts';
 import { Args, Flags } from '@oclif/core';
 import { CreateConfigCommand } from '../../create-config-command.js';
 import { ConfigType } from '../../lib/apps/index.js';
@@ -16,7 +16,7 @@ export default class CreateWebhook extends CreateConfigCommand {
     static examples = [
         '$ swell create webhook',
         '$ swell create webhook order-sync -u https://example.com/hook -e order.created -y',
-        '$ swell create webhook payment-handler -u https://api.example.com/payments -e payment.succeeded,payment.failed --enabled -y',
+        '$ swell create webhook payment-handler -u https://api.example.com/payments -e payment.succeeded,payment.failed --no-enabled -y',
     ];
     static helpMeta = {
         usageDirect: '<name> -u <url> -e <events> [...] -y',
@@ -38,8 +38,9 @@ export default class CreateWebhook extends CreateConfigCommand {
             description: 'Description',
         }),
         enabled: Flags.boolean({
-            default: false,
-            description: 'Enable webhook (default: false)',
+            allowNo: true,
+            default: true,
+            description: 'Enable webhook (default: true)',
         }),
         overwrite: Flags.boolean({
             default: false,
@@ -148,21 +149,14 @@ export default class CreateWebhook extends CreateConfigCommand {
             events = parseEvents(eventsInput);
         }
         // Description prompt (optional)
-        let { description, enabled } = flags;
-        const { overwrite } = flags;
+        let { description } = flags;
+        const { enabled, overwrite } = flags;
         if (!description) {
             description = await input({
                 default: '',
                 message: 'Describe what this webhook does',
             });
         }
-        // Enabled prompt (optional)
-        if (!enabled) {
-            enabled = await confirm({
-                default: false,
-                message: 'Enable webhook now?',
-            });
-        }
         const fileName = toFileName(name);
         const fileBody = {
             $schema: SCHEMAS.WEBHOOK,

package/dist/commands/schema.js

@@ -6,6 +6,7 @@ import * as fs from 'node:fs/promises';
 import parseJson from 'parse-json';
 import { bundleFunction } from '../lib/bundle.js';
 import { SCHEMAS_BASE_URL } from '../lib/constants.js';
+import { getFunctionDeclarations } from '../lib/function-declarations.js';
 import { analyzeFunctionSource, getFunctionTriggers, hasKindDiagnostic, workflowStaticConfigError, } from '../lib/function-source-analysis.js';
 import { SwellCommand } from '../swell-command.js';
 const SCHEMA_DEFINITIONS = Object.freeze({
@@ -164,6 +165,10 @@ export default class Schema extends SwellCommand {
                 break;
             }
             case 'dts': {
+                if (type === 'function') {
+                    output = await getFunctionDeclarations(process.cwd());
+                    break;
+                }
                 const dtsUrl = this.getTypeScriptDeclarationsUrl(type);
                 const response = await fetch(dtsUrl);
                 if (!response.ok) {

package/dist/help/custom-help.js

@@ -280,7 +280,11 @@ export default class CustomHelp extends Help {
             const value = ('helpValue' in flag && flag.helpValue) ||
                 ('options' in flag && flag.options ? 'option' : 'value');
             const suffix = flag.type === 'boolean' ? '' : `=<${value}>`;
-            return [name, `${shortChar}--${name}${suffix}`];
+            const negatable = flag.type === 'boolean' && flag.allowNo;
+            return [
+                name,
+                `${shortChar}--${negatable ? '[no-]' : ''}${name}${suffix}`,
+            ];
         }));
         const flagWidth = Math.max(30, ...[...flagLabels.values()].map((label) => label.length));
         for (const [name, flag] of flagEntries) {

package/dist/lib/apps/actions.d.ts

@@ -0,0 +1,45 @@
+type Values = Record<string, any>;
+export type ActionSource = 'bulk' | 'field' | 'list' | 'record' | 'settings';
+/** An app function action, with what the dashboard sends to run it */
+export interface DeclaredAction {
+    function: string;
+    id: string;
+    modal?: Values;
+    /** The query of the view whose records a bulk action runs on */
+    query?: Values;
+    /** The name of the settings config, for a settings action or action field */
+    settings?: string;
+    source: ActionSource;
+    view?: string;
+}
+/**
+ * The function actions a content config declares.
+ *
+ * @param values the values of the content config
+ * @returns the actions
+ */
+export declare function getContentActions(values: Values): DeclaredAction[];
+/**
+ * The function actions a settings config declares.
+ *
+ * @param values the values of the settings config
+ * @param settings the name of the settings config
+ * @returns the actions
+ */
+export declare function getSettingsActions(values: Values, settings: string): DeclaredAction[];
+/**
+ * The ids of the fields of an action's modal, as the platform finds them to
+ * pass on only their values.
+ *
+ * @param modal the modal of the action
+ * @returns the field ids
+ */
+export declare function getModalFieldIds(modal: Values): string[];
+/**
+ * A function name as the platform compares an action's `function` with it.
+ *
+ * @param name a function name
+ * @returns the name in the form the platform compares
+ */
+export declare function functionSlug(name: string): string;
+export {};

package/dist/lib/apps/actions.js

@@ -0,0 +1,114 @@
+function isFunctionAction(item) {
+    return (typeof item?.id === 'string' &&
+        typeof item?.function === 'string');
+}
+// The dashboard renders the fields of rows and groups in place
+function flattenFields(fields) {
+    if (!Array.isArray(fields)) {
+        return [];
+    }
+    return fields.flatMap((field) => field?.type === 'field_row' || field?.type === 'field_group'
+        ? flattenFields(field.fields)
+        : [field]);
+}
+function getActionFields(fields) {
+    return flattenFields(fields).filter((field) => field?.type === 'action');
+}
+/**
+ * The function actions a content config declares.
+ *
+ * @param values the values of the content config
+ * @returns the actions
+ */
+export function getContentActions(values) {
+    const views = Array.isArray(values?.views) ? values.views : [];
+    const actions = [];
+    for (const view of views) {
+        const source = view.type || (view.id === 'list' ? 'list' : 'record');
+        for (const action of [
+            ...(view.actions || []),
+            ...(view.extra_actions || []),
+        ]) {
+            if (isFunctionAction(action)) {
+                actions.push({ ...pickAction(action), source, view: view.id });
+            }
+        }
+        for (const action of view.bulk_actions || []) {
+            if (isFunctionAction(action)) {
+                actions.push({
+                    ...pickAction(action),
+                    ...(view.query ? { query: view.query } : undefined),
+                    source: 'bulk',
+                    view: view.id,
+                });
+            }
+        }
+    }
+    const fields = [
+        ...(values?.fields || []),
+        ...views.flatMap((view) => [
+            ...(view.fields || []),
+            ...(view.tabs || []).flatMap((tab) => tab?.fields || []),
+        ]),
+    ];
+    for (const field of getActionFields(fields)) {
+        if (isFunctionAction(field)) {
+            actions.push({ ...pickAction(field), source: 'field' });
+        }
+    }
+    return actions;
+}
+/**
+ * The function actions a settings config declares.
+ *
+ * @param values the values of the settings config
+ * @param settings the name of the settings config
+ * @returns the actions
+ */
+export function getSettingsActions(values, settings) {
+    const actions = [];
+    for (const action of values?.actions || []) {
+        if (isFunctionAction(action)) {
+            actions.push({ ...pickAction(action), settings, source: 'settings' });
+        }
+    }
+    for (const field of getActionFields(values?.fields)) {
+        if (isFunctionAction(field)) {
+            actions.push({ ...pickAction(field), settings, source: 'field' });
+        }
+    }
+    return actions;
+}
+/**
+ * The ids of the fields of an action's modal, as the platform finds them to
+ * pass on only their values.
+ *
+ * @param modal the modal of the action
+ * @returns the field ids
+ */
+export function getModalFieldIds(modal) {
+    return flattenFields(modal.fields)
+        .map((field) => field?.id)
+        .filter((id) => typeof id === 'string');
+}
+/**
+ * A function name as the platform compares an action's `function` with it.
+ *
+ * @param name a function name
+ * @returns the name in the form the platform compares
+ */
+export function functionSlug(name) {
+    return name
+        .replaceAll(/[^\s\w./:-]/g, '')
+        .replaceAll(/[\s./:_-]+/g, '-')
+        .replaceAll(/^-+|-+$/g, '')
+        .replaceAll(/([a-z])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}
+function pickAction(action) {
+    return {
+        function: action.function,
+        id: action.id,
+        ...(action.modal ? { modal: action.modal } : undefined),
+    };
+}

package/dist/lib/apps/listing.d.ts

@@ -0,0 +1 @@
+export declare function warnListingSources(appPath: string, config: Record<string, any>, warn: (message: string) => void): void;

package/dist/lib/apps/listing.js

@@ -0,0 +1,41 @@
+import { statSync } from 'node:fs';
+import * as path from 'node:path';
+const LISTING_SOURCE_FIELDS = ['logo_src', 'preview_src', 'preview_mobile_src'];
+const LISTING_SOURCE_LISTS = ['images', 'highlights'];
+// The listing takes its full description from DESCRIPTION.md and each image
+// from the asset whose path from the app root is the swell.json value as
+// written, so values that point elsewhere do nothing. The platform takes an
+// empty value as unset.
+export function warnListingSources(appPath, config, warn) {
+    if (config.full_description !== undefined) {
+        warn('swell.json sets full_description, which push does not apply: the full description is the content of DESCRIPTION.md at the app root.');
+    }
+    const sources = [
+        ...LISTING_SOURCE_FIELDS.map((field) => [
+            field,
+            config[field],
+        ]),
+        ...LISTING_SOURCE_LISTS.flatMap((list) => (Array.isArray(config[list]) ? config[list] : []).map((item, index) => [
+            `${list}[${index}].image_src`,
+            item?.image_src,
+        ])),
+    ];
+    for (const [field, source] of sources) {
+        if (typeof source !== 'string' || source === '') {
+            continue;
+        }
+        const filePath = path.posix.normalize(source.replaceAll('\\', '/'));
+        const stats = statSync(path.join(appPath, filePath), {
+            throwIfNoEntry: false,
+        });
+        if (!stats?.isFile()) {
+            warn(`swell.json ${field} names ${source}, which the app does not have: the listing gets no image from it.`);
+        }
+        else if (!filePath.startsWith('assets/')) {
+            warn(`swell.json ${field} names ${source}, which is not in assets/: the listing gets no image from it. Move the file to assets/ and write assets/${path.posix.basename(filePath)}.`);
+        }
+        else if (filePath !== source) {
+            warn(`swell.json ${field} names ${source}, which is not the file's path from the app root: the listing gets no image from it. Write ${filePath}.`);
+        }
+    }
+}

package/dist/lib/bundle.js

@@ -60,7 +60,7 @@ export async function bundleFunction(filePath) {
 }
 export async function bundleWorkflow(filePath, analysis) {
     try {
-        const entrySource = getSwellWorkflowEntrypoint(filePath);
+        const entrySource = await getSwellWorkflowEntrypoint(filePath);
         const buildResult = await esbuild.build({
             bundle: true,
             stdin: {
@@ -130,13 +130,22 @@ async function getSwellFunctionWrapper() {
     const __dirname = path.dirname(__filename);
     return fs.readFile(path.join(__dirname, './swell-function-wrapper.js'), 'utf8');
 }
-function getSwellWorkflowEntrypoint(filePath) {
+// The entry defines these functions itself, so the bundle names no file of
+// the CLI and the workflow module exports only its entrypoint
+async function getSwellWorkflowRequest() {
+    const source = await fs.readFile(path.join(path.dirname(fileURLToPath(import.meta.url)), './swell-workflow-request.js'), 'utf8');
+    return source.replaceAll(/^export /gm, '');
+}
+async function getSwellWorkflowEntrypoint(filePath) {
     const workflowImport = `./${path.basename(filePath)}`;
+    const workflowRequest = await getSwellWorkflowRequest();
     return `
 import { WorkflowEntrypoint } from 'cloudflare:workers';
 import { NonRetryableError } from 'cloudflare:workflows';
 import UserWorkflow from ${JSON.stringify(workflowImport)};
 
+${workflowRequest}
+
 const RUNTIME_PROXY_PATH = '/:workflows/runtime/request';
 const RUNTIME_TOKEN_PATTERN = /\\bwf_rt_[0-9A-Za-z]+_[0-9A-Za-z]{12,}\\b/g;
 
@@ -210,38 +219,6 @@ function getInvocation(event) {
   return payload;
 }
 
-function buildWorkflowRequest(invocation, proxy) {
-  const runtime = invocation.runtime;
-
-  return {
-    id: runtime.request_id,
-    appId: runtime.app_slug || runtime.app_id,
-    environmentId: runtimeEnvironmentId(runtime),
-    store: {
-      id: runtime.store_id,
-    },
-    app: {
-      admin_url: runtime.app_admin_url,
-    },
-    data: invocation.data,
-    workflow: {
-      workflow_id: runtime.workflow_id,
-      workflow_name: runtime.workflow_name,
-      workflow_instance_id: runtime.workflow_instance_id,
-      trigger: runtime.trigger,
-      request_id: runtime.request_id,
-    },
-    isLocalDev: false,
-    swell: {
-      get: (path, data) => proxy.api('get', path, data),
-      post: (path, data) => proxy.api('post', path, data),
-      put: (path, data) => proxy.api('put', path, data),
-      delete: (path, data) => proxy.api('delete', path, data),
-      settings: () => proxy.settings(),
-    },
-  };
-}
-
 function buildWorkflowStep(cloudflareStep, proxy) {
   return Object.freeze({
     do(name, optionsOrCallback, maybeCallback) {
@@ -361,11 +338,6 @@ function getRuntimeApiHost(runtime) {
   return apiHost.replace(/\\/$/, '');
 }
 
-// 'test' in the test environment, null in live
-function runtimeEnvironmentId(runtime) {
-  return runtime.environment_id || null;
-}
-
 function runtimeIdentity(runtime) {
   return {
     app_id: runtime.app_id,

package/dist/lib/function-declarations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The types an app's functions type-check against: the app's own
+ * @swell/app-types when it has the package, otherwise the CLI's.
+ *
+ * @param directory a directory of the app
+ * @returns the declarations, after a line naming the package version
+ */
+export declare function getFunctionDeclarations(directory: string): Promise<string>;

package/dist/lib/function-declarations.js

@@ -0,0 +1,27 @@
+import * as fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+/**
+ * The types an app's functions type-check against: the app's own
+ * @swell/app-types when it has the package, otherwise the CLI's.
+ *
+ * @param directory a directory of the app
+ * @returns the declarations, after a line naming the package version
+ */
+export async function getFunctionDeclarations(directory) {
+    const file = resolveAppTypes(path.join(directory, 'package.json')) ??
+        resolveAppTypes(import.meta.url);
+    if (!file) {
+        throw new Error('@swell/app-types is not installed');
+    }
+    const { version } = JSON.parse(await fs.readFile(path.join(path.dirname(file), 'package.json'), 'utf8'));
+    return `// @swell/app-types ${version}\n${await fs.readFile(file, 'utf8')}`;
+}
+function resolveAppTypes(from) {
+    try {
+        return createRequire(from).resolve('@swell/app-types/index.d.ts');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/swell-function-wrapper.js

@@ -30,7 +30,13 @@ async function request(originalRequest, _env, context) {
             ...(error.body ?? { error: error.message }),
             retry: error.retry === false ? false : undefined,
         };
-        response = new SwellResponse(errorBody, { status: error.status || 500 });
+        const retryAfter = Number(error.retryAfter);
+        response = new SwellResponse(errorBody, {
+            status: error.status || 500,
+            ...(retryAfter > 0
+                ? { headers: { 'Retry-After': String(Math.ceil(retryAfter)) } }
+                : {}),
+        });
     }
     return SwellResponse._respond(req, response, context);
 }
@@ -447,6 +453,7 @@ class SwellError extends Error {
         this.body = body;
         this.code = options.code || body?.error?.code;
         this.retry = options.retry;
+        this.retryAfter = options.retryAfter;
     }
     get isRetryable() {
         return RETRYABLE_CODES.has(this.code);

package/dist/lib/swell-workflow-request.d.ts

@@ -0,0 +1,34 @@
+export function runtimeEnvironmentId(runtime: any): any;
+export function buildWorkflowRequest(invocation: any, proxy: any): {
+    id: any;
+    appId: any;
+    environmentId: any;
+    store: {
+        id: any;
+    };
+    app: {
+        admin_url: any;
+        frontend_url: any;
+    };
+    data: any;
+    workflow: {
+        workflow_id: any;
+        workflow_name: any;
+        workflow_instance_id: any;
+        trigger: any;
+        request_id: any;
+    };
+    isLocalDev: boolean;
+    swell: {
+        get: (path: any, data: any) => any;
+        post: (path: any, data: any) => any;
+        put: (path: any, data: any) => any;
+        delete: (path: any, data: any) => any;
+        settings: () => any;
+    };
+    appValues(idOrValues: any, values: any): {
+        $app: {
+            [x: number]: any;
+        };
+    };
+};

package/dist/lib/swell-workflow-request.js

@@ -0,0 +1,58 @@
+// The request a workflow's run(req, step) gets, built from the invocation the
+// platform starts the run with. Every workflow bundle includes this module.
+// 'test' in the test environment, null in live
+export function runtimeEnvironmentId(runtime) {
+    return runtime.environment_id || null;
+}
+export function buildWorkflowRequest(invocation, proxy) {
+    const { data, runtime } = invocation;
+    const appId = runtime.app_slug || runtime.app_id;
+    return {
+        id: runtime.request_id,
+        appId,
+        environmentId: runtimeEnvironmentId(runtime),
+        store: {
+            id: runtime.store_id,
+        },
+        app: {
+            admin_url: runtime.app_admin_url,
+            frontend_url: runtime.app_frontend_url,
+        },
+        data,
+        workflow: {
+            workflow_id: runtime.workflow_id,
+            workflow_name: runtime.workflow_name,
+            workflow_instance_id: runtime.workflow_instance_id,
+            trigger: runtime.trigger,
+            request_id: runtime.request_id,
+        },
+        isLocalDev: false,
+        swell: {
+            get: (path, data) => proxy.api('get', path, data),
+            post: (path, data) => proxy.api('post', path, data),
+            put: (path, data) => proxy.api('put', path, data),
+            delete: (path, data) => proxy.api('delete', path, data),
+            settings: () => proxy.settings(),
+        },
+        appValues(idOrValues, values) {
+            const targetAppId = typeof idOrValues === 'string' ? idOrValues : appId;
+            const appValues = typeof idOrValues === 'string' ? values : idOrValues;
+            if (!targetAppId) {
+                throw new Error('appValues: missing app id (req.appId is empty)');
+            }
+            if (!isOrdinaryObject(appValues)) {
+                throw new Error('appValues: values must be a plain object (arrays, class instances, null, and primitives are not allowed)');
+            }
+            return {
+                $app: {
+                    [targetAppId]: appValues,
+                },
+            };
+        },
+    };
+}
+function isOrdinaryObject(val) {
+    return (typeof val === 'object' &&
+        val !== null &&
+        Object.getPrototypeOf(val) === Object.prototype);
+}

package/dist/push-app-command.d.ts

@@ -21,13 +21,14 @@ export declare abstract class PushAppCommand extends RemoteAppCommand {
     watchingIgnoreFilter: GlobbyFilterFunction | null;
     watchingTimer: NodeJS.Timeout | null;
     watchListener: (eventType: fs.WatchEventType, filename: null | string) => Promise<void>;
+    protected pushesSwellJson(file?: string): boolean;
     protected showFrontendMigrationError(): never;
     buildFrontend(projectType?: FrontendProjectType): Promise<void>;
     chooseAppToPull(query?: any): Promise<App>;
     createAppStorefront(hasOtherStorefronts?: boolean, nonInteractive?: boolean): Promise<any>;
     deployAppFrontend(force?: boolean, log?: boolean): Promise<void>;
     deployFrontend(projectType: FrontendProjectType): Promise<string>;
-    ensureAppExists(file?: string, shouldCreate?: boolean, force?: boolean): Promise<boolean>;
+    ensureAppExists(file?: string, shouldCreate?: boolean): Promise<boolean>;
     ensureLoggedIn(): Promise<void>;
     exec(command: string, cwd?: string, onOutput?: (string: string) => any | false): Promise<void>;
     execFrontend(command: string, onOutput?: (string: string) => any | false): Promise<void>;

package/dist/push-app-command.js

@@ -10,6 +10,7 @@ import { componentsToRebuild } from './lib/apps/components.js';
 import { buildFrontendPackage, getManagedFrontendFramework, } from './lib/apps/frontend-package.js';
 import { warnFrontendRouteCollisions } from './lib/apps/frontend-routes.js';
 import { ConfigType, getFrontendProjectValidValues, allConfigFilesInDir, CUSTOM_FRAMEWORK_SLUG, appConfigFromFile, filePathExistsAsync, findAppConfig, getConfigTypeFromPath, getConfigTypeKeyFromValue, getFrontendProjectType, getProjectCommands, globAllFilesByPath, hashFile, hashString, isPathDirectory, toPosixPath, } from './lib/apps/index.js';
+import { warnListingSources } from './lib/apps/listing.js';
 import { getGlobIgnorePathsChecker } from './lib/apps/paths.js';
 import { slugFromApp } from './lib/apps/slug.js';
 import { getLocalInputs } from './lib/bundle.js';
@@ -119,6 +120,10 @@ export class PushAppCommand extends RemoteAppCommand {
             }
         }
     };
+    // The platform applies the listing in swell.json when the file is pushed
+    pushesSwellJson(file) {
+        return !file;
+    }
     showFrontendMigrationError() {
         return this.error(style.funcWarn(`⚠️  Your frontend directory exists but appears to use an older structure.\n` +
             `Swell CLI v2.1.0+ requires a Workers-based frontend with package.json.\n\n` +
@@ -330,7 +335,7 @@ export class PushAppCommand extends RemoteAppCommand {
             this.error(`Error deploying frontend: ${error.message}`);
         }
     }
-    async ensureAppExists(file, shouldCreate = true, force = false) {
+    async ensureAppExists(file, shouldCreate = true) {
         const klass = this.ctor;
         const currentStore = localConfig.getDefaultStore();
         await this.ensureLoggedIn();
@@ -356,10 +361,13 @@ export class PushAppCommand extends RemoteAppCommand {
             this.app = app;
             return true;
         }
+        if (this.pushesSwellJson(file)) {
+            warnListingSources(this.appPath, this.swellConfig.store, (message) => this.warn(message));
+        }
         // If app exists but owned by another client, create a new instance
         if (app?.client_id && app.client_id !== currentStore) {
             // Create a new app
-            this.app = await this.getCreateUpdateApp(undefined, force);
+            this.app = await this.getCreateUpdateApp();
             if (!this.app) {
                 return false;
             }
@@ -373,7 +381,7 @@ export class PushAppCommand extends RemoteAppCommand {
         }
         else {
             // Update existing app if not targeting a file
-            this.app = await this.getCreateUpdateApp(app, force);
+            this.app = await this.getCreateUpdateApp(app);
         }
         return true;
     }

package/dist/remote-app-command.d.ts

@@ -26,7 +26,7 @@ export declare abstract class RemoteAppCommand extends AppCommand {
     protected getApp(id?: string): Promise<App>;
     protected getAppWithConfig(id?: string): Promise<App>;
     getConfigData(configId: string): Promise<any>;
-    protected getCreateUpdateApp(updateApp?: App | null, force?: boolean): Promise<App>;
+    protected getCreateUpdateApp(updateApp?: App | null): Promise<App>;
     protected getInstalledApp(): Promise<any>;
     /**
      * Anything on the target store already using the services named by

package/dist/remote-app-command.js

@@ -176,7 +176,7 @@ export class RemoteAppCommand extends AppCommand {
             adminPath: `/apps/${this.app.id}/configs/${configId}/data`,
         }, { query: { ...(themeId ? { theme_id: themeId } : undefined) } });
     }
-    async getCreateUpdateApp(updateApp, force = false) {
+    async getCreateUpdateApp(updateApp) {
         const spinner = ora();
         let sourceApp;
         try {
@@ -205,9 +205,6 @@ export class RemoteAppCommand extends AppCommand {
                 ? { private_id: this.swellConfig.store.id }
                 : undefined),
             ...(sourceApp?.id ? { source_id: sourceApp.id } : undefined),
-            // Overwrite name/description/logo_icon on the server
-            // instead of only filling them in when empty
-            ...(force ? { $force_meta: true } : undefined),
         };
         const appLabel = this.app.type === 'theme' ? 'theme' : 'app';
         let app = updateApp || {};

package/oclif.manifest.json

@@ -721,6 +721,126 @@
         "_uninstall.js"
       ]
     },
+    "app:action": {
+      "aliases": [],
+      "args": {
+        "id": {
+          "description": "id of the action, as declared in content or settings",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Runs a function action of the app as the logged-in dashboard user, the way a click in the dashboard does. The action is looked up in the app's content and settings as pushed.\n\nA record action or action field needs --record, and a bulk action --ids or --all. Pass the values of the action's modal with --values. When the same id is declared in more than one place, pick one with --collection, --view, --settings or --source.",
+      "examples": [
+        "swell app action sync_now",
+        "swell app action ship --record 64e8dfb633c44a0039477251",
+        "swell app action ship --record 64e8dfb633c44a0039477251 --values '{\"carrier\":\"ups\"}'",
+        "swell app action ship-selected --ids 64e8dfb633c44a0039477251,64e8dfb633c44a0039477252",
+        "swell app action ship --collection shipments --view edit --record 64e8dfb633c44a0039477251",
+        "swell app action export --source bulk --all"
+      ],
+      "flags": {
+        "app-path": {
+          "description": "Path to your app directory",
+          "name": "app-path",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "all": {
+          "description": "run a bulk action on all records its view lists with no filters set, as selecting all in the dashboard does",
+          "exclusive": [
+            "ids"
+          ],
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "collection": {
+          "description": "collection of the content that declares the action, or the model's name for a collection of the app",
+          "name": "collection",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ids": {
+          "description": "comma-separated ids of the records a bulk action runs on",
+          "exclusive": [
+            "all"
+          ],
+          "name": "ids",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "live": {
+          "description": "run in the live environment instead of test",
+          "name": "live",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "record": {
+          "description": "id of the record a record action or action field runs on",
+          "name": "record",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "settings": {
+          "description": "name of the settings that declare the action",
+          "name": "settings",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "source": {
+          "description": "where the action is declared: list or record (a view's actions), bulk (a view's bulk actions), field (an action field) or settings (a settings action)",
+          "name": "source",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "list",
+            "record",
+            "bulk",
+            "field",
+            "settings"
+          ],
+          "type": "option"
+        },
+        "values": {
+          "description": "values of the action's modal fields, as JSON",
+          "name": "values",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "view": {
+          "description": "id of the content view that declares the action",
+          "name": "view",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "app:action",
+      "pluginAlias": "@swell/cli",
+      "pluginName": "@swell/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Run an app action from the command line.",
+      "enableJsonFlag": false,
+      "requiresSwellConfig": true,
+      "delayOrientation": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "app",
+        "action.js"
+      ]
+    },
     "app:delete": {
       "aliases": [],
       "args": {},
@@ -1237,7 +1357,7 @@
           "name": "file"
         }
       },
-      "description": "Push all app files, a specific file, or a specific configuration\ntype to an app in your store's test environment.\n\nIf the app does not exist, it will be created and its global ID saved to a .swellrc file.\n\n- If no file is specified, all configuration files will be pushed to the store.\n  This includes the app icon (assets/icon.png), screenshots (assets/screenshots/),\n  README.md, and swell.json.\n- If a file is specified, only that file will be pushed to the store.\n- If a directory is specified, only files in that directory will be pushed.\n\nPushing anything under frontend/ also builds and deploys the app frontend, so\nthe deployed frontend matches what was pushed. Use --no-deploy to skip it.\n\nApp file directories:\nassets/\ncontent/\nfrontend/\ncomponents/\nfunctions/\nmodels/\nnotifications/\nsettings/\ntheme/\nwebhooks/",
+      "description": "Push all app files, a specific file, or a specific configuration\ntype to an app in your store's test environment.\n\nIf the app does not exist, it will be created and its global ID saved to a .swellrc file.\n\n- If no file is specified, all configuration files will be pushed to the store.\n  This includes the app icon (assets/icon.png), screenshots (assets/screenshots/),\n  DESCRIPTION.md, and swell.json.\n- If a file is specified, only that file will be pushed to the store.\n- If a directory is specified, only files in that directory will be pushed.\n\nPushing anything under frontend/ also builds and deploys the app frontend, so\nthe deployed frontend matches what was pushed. Use --no-deploy to skip it.\n\nApp file directories:\nassets/\ncontent/\nfrontend/\ncomponents/\nfunctions/\nmodels/\nnotifications/\nsettings/\ntheme/\nwebhooks/",
       "examples": [
         "swell app push",
         "swell app push content",
@@ -2475,7 +2595,7 @@
       "examples": [
         "$ swell create webhook",
         "$ swell create webhook order-sync -u https://example.com/hook -e order.created -y",
-        "$ swell create webhook payment-handler -u https://api.example.com/payments -e payment.succeeded,payment.failed --enabled -y"
+        "$ swell create webhook payment-handler -u https://api.example.com/payments -e payment.succeeded,payment.failed --no-enabled -y"
       ],
       "flags": {
         "app-path": {
@@ -2513,9 +2633,9 @@
           "type": "option"
         },
         "enabled": {
-          "description": "Enable webhook (default: false)",
+          "description": "Enable webhook (default: true)",
           "name": "enabled",
-          "allowNo": false,
+          "allowNo": true,
           "type": "boolean"
         },
         "overwrite": {
@@ -3738,5 +3858,5 @@
       ]
     }
   },
-  "version": "2.9.31"
+  "version": "2.9.32"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/cli",
-  "version": "2.9.31",
+  "version": "2.9.32",
   "type": "module",
   "description": "Swell's command line interface/utility",
   "keywords": [
@@ -30,6 +30,7 @@
     "@npmcli/git": "5.0.3",
     "@oclif/core": "3.7.1",
     "@oclif/plugin-help": "6.0.4",
+    "@swell/app-types": "1.3.0",
     "ajv": "8.20.0",
     "ajv-errors": "3.0.0",
     "ajv-formats": "3.0.1",