@swell/cli 2.2.0 → 2.3.0

package/dist/commands/create/setting.d.ts

@@ -0,0 +1,21 @@
+import { CreateConfigCommand } from '../../create-config-command.js';
+import { HelpMeta } from '../../help/types.js';
+import { ConfigType } from '../../lib/apps/index.js';
+export default class CreateSetting extends CreateConfigCommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static helpMeta: HelpMeta;
+    static flags: {
+        label: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        description: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        fields: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        overwrite: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    createType: ConfigType;
+    run(): Promise<void>;
+}

package/dist/commands/create/setting.js

@@ -0,0 +1,120 @@
+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';
+import { toFileName } from '../../lib/create/index.js';
+import { SCHEMAS } from '../../lib/create/schemas.js';
+import { parseFields, toSettingLabel, } from '../../lib/create/setting.js';
+export default class CreateSetting extends CreateConfigCommand {
+    static args = {
+        name: Args.string({
+            default: '',
+            description: 'Setting name (e.g., api-config)',
+        }),
+    };
+    static description = 'Create a setting configuration in the settings folder.';
+    static examples = [
+        '$ swell create setting',
+        '$ swell create setting api-config -y',
+        '$ swell create setting api-config -f api_key:short_text,enabled:boolean -l "API Config" -y',
+    ];
+    static helpMeta = {
+        usageDirect: '<name> [...] -y',
+    };
+    static flags = {
+        label: Flags.string({
+            char: 'l',
+            default: '',
+            description: 'Display label (default: titleized name)',
+        }),
+        description: Flags.string({
+            char: 'd',
+            default: '',
+            description: 'Description',
+        }),
+        fields: Flags.string({
+            char: 'f',
+            default: '',
+            description: 'Fields as id:type pairs (e.g., api_key:short_text,enabled:boolean)',
+        }),
+        overwrite: Flags.boolean({
+            default: false,
+            description: 'Overwrite existing file',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Skip prompts, require all arguments',
+        }),
+    };
+    static summary = 'Create a setting configuration in the settings folder.';
+    createType = ConfigType.SETTING;
+    async run() {
+        const { args, flags } = await this.parse(CreateSetting);
+        const confirmYes = Boolean(flags.yes);
+        // NON-INTERACTIVE PATH
+        if (confirmYes) {
+            const argName = args.name;
+            if (!argName) {
+                this.error('Missing required argument for non-interactive mode: NAME\n\nExample: swell create setting api-config -y', { exit: 1 });
+            }
+            const name = toFileName(argName);
+            const label = flags.label || toSettingLabel(name);
+            const description = flags.description || '';
+            const fieldsRaw = (flags.fields || '');
+            const fieldPairs = fieldsRaw
+                ? fieldsRaw
+                    .split(',')
+                    .map((v) => v.trim())
+                    .filter(Boolean)
+                : [];
+            const fileName = toFileName(name);
+            const fileBody = {
+                $schema: SCHEMAS.SETTING,
+                description,
+                fields: parseFields(fieldPairs),
+                label,
+            };
+            await this.createFile({ fileBody, fileName }, flags.overwrite, 
+            /* shouldConfirm */ false);
+            return;
+        }
+        // INTERACTIVE PATH
+        let name = args.name;
+        if (!name) {
+            name = await input({
+                default: 'my-setting',
+                message: 'Setting name',
+            });
+        }
+        name = toFileName(name);
+        let { label, description } = flags;
+        const { fields: fieldsFlag, overwrite } = flags;
+        if (!label) {
+            label = await input({
+                default: toSettingLabel(name),
+                message: 'Setting label',
+            });
+        }
+        if (!description) {
+            description = await input({
+                default: '',
+                message: 'Describe what this setting is for',
+            });
+        }
+        const fieldsRaw = (fieldsFlag || '');
+        const fieldPairs = fieldsRaw
+            ? fieldsRaw
+                .split(',')
+                .map((v) => v.trim())
+                .filter(Boolean)
+            : [];
+        const fileName = toFileName(name);
+        const fileBody = {
+            $schema: SCHEMAS.SETTING,
+            description,
+            fields: parseFields(fieldPairs),
+            label,
+        };
+        await this.createFile({ fileBody, fileName }, overwrite);
+    }
+}

package/dist/commands/create/tests.d.ts

@@ -0,0 +1,14 @@
+import { AppCommand } from '../../app-command.js';
+import { HelpMeta } from '../../help/types.js';
+export default class CreateTests extends AppCommand {
+    static description: string;
+    static examples: string[];
+    static helpMeta: HelpMeta;
+    static flags: {
+        overwrite: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+    private logScaffoldResult;
+}

package/dist/commands/create/tests.js

@@ -0,0 +1,76 @@
+import { Flags } from '@oclif/core';
+import { AppCommand } from '../../app-command.js';
+import { toAppId } from '../../lib/create/index.js';
+import { createTestsScaffold, } from '../../lib/create/tests.js';
+export default class CreateTests extends AppCommand {
+    static description = 'Initialize a vitest + Cloudflare Workers test setup that reuses swell-cli authentication.';
+    static examples = [
+        '$ swell create tests',
+        '$ swell create tests --overwrite',
+    ];
+    static helpMeta = {
+        usageDirect: '[-y]',
+    };
+    static flags = {
+        overwrite: Flags.boolean({
+            default: false,
+            description: 'Overwrite existing test files',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            default: false,
+            description: 'Skip prompts, require all arguments',
+        }),
+    };
+    static summary = 'Create tests scaffolding for your Swell app.';
+    async run() {
+        const { flags } = await this.parse(CreateTests);
+        const appIdFromConfig = (this.swellConfig.get('id') ||
+            this.swellConfig.get('private_id') ||
+            this.swellConfig.get('public_id'));
+        const appId = appIdFromConfig ||
+            toAppId(this.swellConfig.get('name')) ||
+            'app';
+        const result = await createTestsScaffold({
+            appPath: this.appPath,
+            appId,
+            overwrite: Boolean(flags.overwrite),
+        });
+        this.logScaffoldResult(result);
+    }
+    logScaffoldResult(result) {
+        const hasChanges = result.createdFiles.length > 0 || result.packageJsonUpdated;
+        if (hasChanges) {
+            this.log('');
+            this.log('✓ Created test scaffolding');
+        }
+        if (result.createdFiles.length > 0) {
+            this.log('');
+            this.log('Created:');
+            for (const file of result.createdFiles) {
+                this.log(`  ${file}`);
+            }
+        }
+        if (result.skippedFiles.length > 0) {
+            this.log('');
+            this.log('Skipped (already exist):');
+            for (const file of result.skippedFiles) {
+                this.log(`  ${file}`);
+            }
+        }
+        if (result.packageJsonUpdated) {
+            this.log('');
+            this.log('Updated package.json with test scripts and devDependencies.');
+        }
+        for (const warning of result.warnings) {
+            this.warn(warning);
+        }
+        if (hasChanges) {
+            this.log('');
+            this.log('Next steps:');
+            this.log('  1. npm install');
+            this.log('  2. npm test');
+        }
+        this.log('');
+    }
+}

package/dist/commands/create/webhook.d.ts

@@ -0,0 +1,22 @@
+import { CreateConfigCommand } from '../../create-config-command.js';
+import { HelpMeta } from '../../help/types.js';
+import { ConfigType } from '../../lib/apps/index.js';
+export default class CreateWebhook extends CreateConfigCommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static helpMeta: HelpMeta;
+    static flags: {
+        url: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        events: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        description: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        enabled: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        overwrite: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    createType: ConfigType;
+    run(): Promise<void>;
+}

package/dist/commands/create/webhook.js

@@ -0,0 +1,176 @@
+import { confirm, input } from '@inquirer/prompts';
+import { Args, Flags } from '@oclif/core';
+import { CreateConfigCommand } from '../../create-config-command.js';
+import { ConfigType } from '../../lib/apps/index.js';
+import { toFileName } from '../../lib/create/index.js';
+import { SCHEMAS } from '../../lib/create/schemas.js';
+import { parseEvents, validateEventFormat, validateUrl, } from '../../lib/create/webhook.js';
+export default class CreateWebhook extends CreateConfigCommand {
+    static args = {
+        name: Args.string({
+            default: '',
+            description: 'Webhook name (e.g., order-sync)',
+        }),
+    };
+    static description = 'Create a webhook configuration in the webhooks folder.';
+    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',
+    ];
+    static helpMeta = {
+        usageDirect: '<name> -u <url> -e <events> [...] -y',
+    };
+    static flags = {
+        url: Flags.string({
+            char: 'u',
+            default: '',
+            description: 'Endpoint URL (required with -y)',
+        }),
+        events: Flags.string({
+            char: 'e',
+            default: '',
+            description: 'Events to listen for (e.g., order.created,payment.succeeded)',
+        }),
+        description: Flags.string({
+            char: 'd',
+            default: '',
+            description: 'Description',
+        }),
+        enabled: Flags.boolean({
+            default: false,
+            description: 'Enable webhook (default: false)',
+        }),
+        overwrite: Flags.boolean({
+            default: false,
+            description: 'Overwrite existing file',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Skip prompts, require all arguments',
+        }),
+    };
+    static summary = 'Create a webhook configuration in the webhooks folder.';
+    createType = ConfigType.WEBHOOK;
+    async run() {
+        const { args, flags } = await this.parse(CreateWebhook);
+        const confirmYes = Boolean(flags.yes);
+        // NON-INTERACTIVE PATH
+        if (confirmYes) {
+            const argName = args.name;
+            if (!argName) {
+                this.error('Missing required argument for non-interactive mode: NAME\n\nExample: swell create webhook payment-handler -u https://example.com/hook -e order.created -y', { exit: 1 });
+            }
+            if (!flags.url) {
+                this.error('Missing required flag for non-interactive mode: --url\n\nExample: swell create webhook payment-handler -u https://example.com/hook -e order.created -y', { exit: 1 });
+            }
+            if (!flags.events) {
+                this.error('Missing required flag for non-interactive mode: --events\n\nExample: swell create webhook payment-handler -u https://example.com/hook -e order.created -y', { exit: 1 });
+            }
+            // Validate URL format
+            validateUrl(flags.url, this.error.bind(this));
+            // Parse and validate events
+            const events = parseEvents(flags.events);
+            if (events.length === 0) {
+                this.error('At least one event is required.\n\nExample: swell create webhook payment-handler -u https://example.com/hook -e order.created -y', { exit: 1 });
+            }
+            validateEventFormat(events, this.error.bind(this));
+            const name = toFileName(argName);
+            const fileName = toFileName(name);
+            const fileBody = {
+                $schema: SCHEMAS.WEBHOOK,
+                description: flags.description || '',
+                enabled: flags.enabled,
+                events,
+                url: flags.url,
+            };
+            await this.createFile({ fileBody, fileName }, flags.overwrite, 
+            /* shouldConfirm */ false);
+            return;
+        }
+        // INTERACTIVE PATH
+        let name = args.name;
+        if (!name) {
+            name = await input({
+                default: 'my-webhook',
+                message: 'Webhook name',
+            });
+        }
+        name = toFileName(name);
+        // URL prompt (required)
+        let { url } = flags;
+        if (url) {
+            validateUrl(url, this.error.bind(this));
+        }
+        else {
+            url = await input({
+                message: 'Webhook endpoint URL',
+                validate(value) {
+                    if (!value) {
+                        return 'URL is required';
+                    }
+                    try {
+                        const parsed = new URL(value);
+                        if (!['http:', 'https:'].includes(parsed.protocol)) {
+                            return 'URL must use HTTP or HTTPS protocol';
+                        }
+                    }
+                    catch {
+                        return 'Invalid URL format';
+                    }
+                    return true;
+                },
+            });
+        }
+        // Events prompt (required)
+        let events;
+        if (flags.events) {
+            events = parseEvents(flags.events);
+            validateEventFormat(events, this.error.bind(this));
+        }
+        else {
+            const eventsInput = await input({
+                message: 'Events to subscribe (e.g., order.created,payment.succeeded)',
+                validate(value) {
+                    if (!value) {
+                        return 'At least one event is required';
+                    }
+                    const parsed = parseEvents(value);
+                    for (const event of parsed) {
+                        const parts = event.split('.');
+                        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+                            return `Invalid event format: ${event}. Use model.action pattern.`;
+                        }
+                    }
+                    return true;
+                },
+            });
+            events = parseEvents(eventsInput);
+        }
+        // Description prompt (optional)
+        let { description, enabled } = flags;
+        const { 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,
+            description,
+            enabled,
+            events,
+            url,
+        };
+        await this.createFile({ fileBody, fileName }, overwrite);
+    }
+}

package/dist/commands/inspect/content.js

@@ -132,7 +132,7 @@ With a content ID, it retrieves the configuration for that specific content view
             return resolvedId; // custom IDs don't need reverse resolution
         }
         // Check if identifier is already an app ID (ObjectID format)
-        if (identifier.match(/^[0-9a-f]{24}$/)) {
+        if (/^[\da-f]{24}$/.test(identifier)) {
             return resolvedId; // already unresolved format
         }
         // type === 'app': resolve slug to app ID

package/dist/commands/schema.d.ts

@@ -19,6 +19,7 @@ export default class Schema extends SwellCommand {
     private showSchemaInfo;
     private outputSchema;
     private validate;
+    private validateFunction;
     private getFileInput;
     private readFromStdin;
     private getSchemaUrl;

package/dist/commands/schema.js

@@ -5,6 +5,7 @@ import ajvErrors from 'ajv-errors';
 import addFormats from 'ajv-formats';
 import * as fs from 'node:fs';
 import parseJson from 'parse-json';
+import { bundleFunction } from '../lib/bundle.js';
 import { SCHEMAS_BASE_URL } from '../lib/constants.js';
 import { SwellCommand } from '../swell-command.js';
 const SCHEMA_DEFINITIONS = Object.freeze({
@@ -23,9 +24,13 @@ const SCHEMA_DEFINITIONS = Object.freeze({
     webhook: {
         description: 'Webhook definitions (/webhooks/*.json)',
     },
+    function: {
+        description: 'Function definitions (/functions/*.ts or *.js)',
+        hasJsonSchema: false,
+    },
 });
 export default class Schema extends SwellCommand {
-    static summary = 'View or validate Swell config JSON Schemas.';
+    static summary = 'View or validate Swell config schemas.';
     static examples = [
         {
             description: 'List available schema types',
@@ -44,22 +49,26 @@ export default class Schema extends SwellCommand {
             command: '<%= config.bin %> <%= command.id %> content --format=dts',
         },
         {
-            description: 'Validate a file',
+            description: 'Validate a JSON config file',
             command: '<%= config.bin %> <%= command.id %> content myfile.json',
         },
         {
             description: 'Validate from stdin',
             command: 'cat myfile.json | <%= config.bin %> <%= command.id %> content -',
         },
+        {
+            description: 'Validate a function file',
+            command: '<%= config.bin %> <%= command.id %> function myfunction.ts',
+        },
     ];
     static args = {
         type: Args.string({
             required: false,
-            description: 'Schema type (e.g. model, content, setting, notification, webhook)',
+            description: 'Schema type (e.g. model, content, setting, notification, webhook, function)',
         }),
         file: Args.string({
             required: false,
-            description: 'Path to JSON file to validate (or use "-" for stdin)',
+            description: 'Path to file to validate (or use "-" for stdin)',
         }),
     };
     static flags = {
@@ -90,7 +99,9 @@ export default class Schema extends SwellCommand {
             if (format) {
                 throw new Error('--format cannot be used with file validation');
             }
-            await this.validate(type, file);
+            await (type === 'function'
+                ? this.validateFunction(file)
+                : this.validate(type, file));
             return;
         }
         // Show schema info or output schema
@@ -119,6 +130,13 @@ export default class Schema extends SwellCommand {
         this.log(`Run "swell schema --help" for more information.`);
     }
     async outputSchema(type, format) {
+        const definition = SCHEMA_DEFINITIONS[type];
+        // Guard against json-schema formats for types without JSON Schema
+        if ('hasJsonSchema' in definition &&
+            definition.hasJsonSchema === false &&
+            (format === 'json-schema' || format === 'json-schema-bundle')) {
+            throw new Error(`'${type}' does not have a JSON Schema. Use --format=dts for TypeScript declarations.`);
+        }
         let output;
         switch (format) {
             case 'json-schema': {
@@ -202,6 +220,34 @@ export default class Schema extends SwellCommand {
         }
         this.log('Valid model definition');
     }
+    async validateFunction(file) {
+        if (!fs.existsSync(file)) {
+            throw new Error(`File not found: ${file}`);
+        }
+        const filePath = fs.realpathSync(file);
+        // Attempt to bundle the function (validates syntax, imports, etc.)
+        let bundleResult;
+        try {
+            bundleResult = await bundleFunction(filePath);
+        }
+        catch (error) {
+            throw new Error(`Function compilation failed:\n•  ${error.message}`);
+        }
+        const { config } = bundleResult;
+        // Validate config exists
+        if (!config) {
+            throw new Error('Invalid function:\n•  Function must export a `config` object');
+        }
+        // Validate trigger exclusivity
+        const triggers = ['route', 'model', 'cron'].filter((t) => config[t]);
+        if (triggers.length === 0) {
+            throw new Error('Invalid function config:\n•  Config must specify one of: route, model, cron');
+        }
+        if (triggers.length > 1) {
+            throw new Error(`Invalid function config:\n•  Multiple triggers specified: ${triggers.join(', ')}. Use exactly one.`);
+        }
+        this.log('Valid function definition');
+    }
     getFileInput(file) {
         if (!fs.existsSync(file)) {
             throw new Error(`File not found: ${file}`);

package/dist/commands/theme/init.d.ts

@@ -1,9 +1,13 @@
+import { HelpMeta } from '../../help/types.js';
 import InitApp from '../app/init.js';
 export default class InitTheme extends InitApp {
+    protected commandExample: string;
+    static args: {
+        id: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
     static description: string;
-    static examples: {
-        command: string;
-        description: string;
-    }[];
+    static examples: string[];
+    static helpMeta: HelpMeta;
+    static flags: any;
     appType: string;
 }

package/dist/commands/theme/init.js

@@ -1,15 +1,28 @@
+import { Args } from '@oclif/core';
 import InitApp from '../app/init.js';
 export default class InitTheme extends InitApp {
+    // Override command example for error messages
+    commandExample = 'swell theme init';
+    static args = {
+        id: Args.string({
+            default: '',
+            description: 'Theme identifier (defaults to current directory name)',
+        }),
+    };
     static description = 'Initialize theme swell.json in the current directory.';
     static examples = [
-        {
-            command: 'swell theme init',
-            description: 'Initialize theme following command prompts.',
-        },
-        {
-            command: 'swell theme init -y',
-            description: 'Initialize theme and accept all default values.',
-        },
+        '$ swell theme init',
+        '$ swell theme init my-theme',
+        '$ swell theme init -y',
+        '$ swell theme init my-theme -y',
+        '$ swell theme init my-theme --storefront-app proxima -y',
     ];
+    static helpMeta = {
+        usageDirect: '[id] --storefront-app <app> [...] -y',
+    };
+    // Inherit all flags from InitApp (which inherits from CreateApp)
+    static flags = {
+        ...InitApp.flags,
+    };
     appType = 'theme';
 }

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

@@ -1,5 +1,6 @@
 import { SwellCommand } from './swell-command.js';
 export declare abstract class CreateAppCommand extends SwellCommand {
+    protected commandExample: string;
     static baseFlags: {
         frontend: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'storefront-app': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;