@swell/cli 2.9.6 → 2.9.7

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

@@ -11,6 +11,7 @@ export default class AppDev extends PushAppCommand {
         function: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'storefront-id': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'storefront-select': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'json-events': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
     };
     static orientation: {
@@ -24,10 +25,12 @@ export default class AppDev extends PushAppCommand {
     tmpDir: string;
     frontendPort: number | null;
     isCleaningUp: boolean;
+    jsonEvents: boolean;
     run(): Promise<void>;
     private cleanupOnExit;
     runAppFrontendDevIfApplicable(frontendPort?: number): Promise<number | undefined>;
     private createFunctionRouter;
+    private emitLifecycleEvent;
     private createTmpDirectory;
     private generateWranglerConfig;
     private getAppFunctions;

package/dist/commands/app/dev.js

@@ -42,6 +42,10 @@ export default class AppDev extends PushAppCommand {
             default: false,
             description: 'for storefront apps, prompt to select a storefront to preview',
         }),
+        'json-events': Flags.boolean({
+            description: 'emit machine-readable dev server lifecycle events',
+            hidden: true,
+        }),
         // Declared here so oclif accepts -y; passed through to app:frontend:dev via this.argv
         yes: Flags.boolean({
             char: 'y',
@@ -65,10 +69,12 @@ export default class AppDev extends PushAppCommand {
     frontendPort = null;
     // Guard against multiple cleanup calls
     isCleaningUp = false;
+    jsonEvents = false;
     async run() {
         const { flags } = await this.parse(AppDev);
         const { port, 'frontend-port': frontendPort } = flags;
         const noPush = flags['no-push'];
+        this.jsonEvents = flags['json-events'];
         this.functionFilter = flags.function ?? null;
         if (!(await this.ensureAppExists(undefined, false))) {
             return;
@@ -88,6 +94,10 @@ export default class AppDev extends PushAppCommand {
         process.on('SIGTERM', this.cleanupOnExit.bind(this));
         const serverPort = await this.startProxyServer(port);
         await this.startAppFunctionServer(spinner, serverPort);
+        this.emitLifecycleEvent('preview:proxy-ready', {
+            proxyPort: serverPort,
+            storefrontId: this.storefront?.id ?? null,
+        });
         await this.runAppFrontendDevIfApplicable(frontendPort);
     }
     async cleanupOnExit() {
@@ -103,6 +113,9 @@ export default class AppDev extends PushAppCommand {
         catch {
             // Ignore errors during cleanup
         }
+        this.emitLifecycleEvent('preview:stopped', {
+            storefrontId: this.storefront?.id ?? null,
+        });
         this.log();
         // eslint-disable-next-line no-process-exit, unicorn/no-process-exit
         process.exit();
@@ -199,7 +212,18 @@ export default class AppDev extends PushAppCommand {
                         : ''}`);
             }
         });
-        server.listen(serverPort);
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(serverPort, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+    }
+    emitLifecycleEvent(type, data) {
+        if (!this.jsonEvents)
+            return;
+        this.log(JSON.stringify({ type, ...data }));
     }
     async createTmpDirectory() {
         const tmpBase = path.join(os.tmpdir(), 'swell-cli');

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

@@ -11,6 +11,7 @@ export default class AppFrontendDev extends PushAppCommand {
         port: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'frontend-port': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         function: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'json-events': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
     };
     static orientation: {
         env: string;

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

@@ -14,6 +14,8 @@ export default class CreateApp extends CreateAppCommand {
     static helpMeta: HelpMeta;
     static flags: any;
     appType: string;
+    private jsonOutput;
+    log(message?: string, ...args: any[]): void;
     createSwellConfig({ allowOverwrite, inputId, inputStorefrontApp, inputType, inputName, inputVersion, inputDescription, inputFrontend, inputIntegrationType, inputIntegrationId, inputYes, nestedPath, }: {
         allowOverwrite?: boolean;
         inputDescription?: string;

package/dist/commands/create/app.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import ora from 'ora';
 import { CreateAppCommand } from '../../create-app-command.js';
 import { newConfig, swellConfigFileExists } from '../../lib/app-config.js';
+import { buildCreateAppResult } from '../../lib/apps/create-app-result.js';
 import { toAppId, toAppName } from '../../lib/create/index.js';
 import style from '../../lib/style.js';
 /**
@@ -90,8 +91,16 @@ export default class CreateApp extends CreateAppCommand {
             char: 'd',
             description: 'Description',
         }),
+        json: Flags.boolean({
+            description: 'Output the command result as JSON',
+        }),
     };
     appType = '';
+    jsonOutput = false;
+    log(message, ...args) {
+        if (!this.jsonOutput)
+            super.log(message, ...args);
+    }
     async createSwellConfig({ allowOverwrite = true, inputId = '', inputStorefrontApp, inputType, inputName, inputVersion, inputDescription, inputFrontend, inputIntegrationType, inputIntegrationId, inputYes, nestedPath = true, }) {
         const confirmYes = inputYes;
         let appId = toAppId(inputId || '');
@@ -352,7 +361,8 @@ export default class CreateApp extends CreateAppCommand {
     async run() {
         const { args, flags } = await this.parse(CreateApp);
         const { id } = args;
-        const { pkg, yes, name, type, version, description, frontend } = flags;
+        const { pkg, yes, name, type, version, description, frontend, json } = flags;
+        this.jsonOutput = Boolean(json);
         const confirmYes = Boolean(yes);
         const createParams = await this.createSwellConfig({
             inputId: id,
@@ -369,7 +379,7 @@ export default class CreateApp extends CreateAppCommand {
         if (!createParams) {
             return;
         }
-        const { appId, config, installedStorefrontApp } = createParams;
+        const { appId, config, installedStorefrontApp, swellConfigJson } = createParams;
         !confirmYes && this.log();
         const spinner = ora();
         spinner.start('Creating app...');
@@ -378,21 +388,37 @@ export default class CreateApp extends CreateAppCommand {
         }
         await this.createAppConfigFolders(config);
         spinner.succeed(`${style.appConfigValue(config.get('name'))} app created.\n`);
-        let createdFrontend;
+        let frontendResult;
+        let resources;
         let createdTheme;
         if (installedStorefrontApp) {
             createdTheme = await this.createThemeApp(config, flags, installedStorefrontApp);
         }
         else if (config.get('type') === 'storefront') {
-            createdFrontend = await this.createStorefrontApp(config, flags);
+            const storefrontResult = await this.createStorefrontApp(config, flags, {
+                provisionResources: true,
+            });
+            frontendResult = storefrontResult;
+            resources = storefrontResult.resources;
         }
         else {
-            createdFrontend = await this.createFrontendApp(config, flags);
+            frontendResult = await this.createFrontendApp(config, flags);
+        }
+        if (json) {
+            super.log(JSON.stringify(buildCreateAppResult({
+                privateId: swellConfigJson.id,
+                resources,
+                name: swellConfigJson.name,
+                type: swellConfigJson.type,
+                frontend: frontendResult?.framework ?? null,
+                path: path.dirname(config.path),
+            })));
+            return;
         }
         this.log('\nNext steps:');
         this.log(`Run ${style.command('swell app push')} to push configurations to your test store.`);
         this.log(`Run ${style.command('swell app install')} to install the app in another store or environment.`);
-        if (createdFrontend) {
+        if (frontendResult?.created) {
             this.log(`Run ${style.command('swell app frontend dev')} to start a local dev server for your frontend app.`);
         }
         else if (createdTheme) {

package/dist/commands/create/frontend.js

@@ -32,7 +32,9 @@ export default class CreateFrontend extends CreateAppCommand {
             return;
         }
         await (appType === 'storefront'
-            ? this.createStorefrontApp(newSwellConfig, flags, true)
+            ? this.createStorefrontApp(newSwellConfig, flags, {
+                directCreate: true,
+            })
             : this.createFrontendApp(newSwellConfig, flags, true));
     }
 }

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

@@ -1,5 +1,18 @@
+import { type StorefrontResourceResult } from './lib/apps/storefront-resources.js';
 import { PackageManager } from './lib/package-manager.js';
 import { SwellCommand } from './swell-command.js';
+export interface FrontendCreationResult {
+    created: boolean;
+    framework: string | null;
+    provisionsStorefront: boolean;
+}
+export interface StorefrontCreationResult extends FrontendCreationResult {
+    resources?: StorefrontResourceResult;
+}
+export interface StorefrontCreationOptions {
+    directCreate?: boolean;
+    provisionResources?: boolean;
+}
 export declare abstract class CreateAppCommand extends SwellCommand {
     protected commandExample: string;
     static baseFlags: {
@@ -25,8 +38,8 @@ export declare abstract class CreateAppCommand extends SwellCommand {
      */
     private addViteAllowedHosts;
     createAppConfigFolders(swellConfig: any): Promise<void>;
-    createFrontendApp(swellConfig: any, flags: any, directCreate?: boolean, kind?: string): Promise<boolean>;
-    createStorefrontApp(swellConfig: any, flags: any, directCreate?: boolean): Promise<boolean>;
+    createFrontendApp(swellConfig: any, flags: any, directCreate?: boolean, kind?: string): Promise<FrontendCreationResult>;
+    createStorefrontApp(swellConfig: any, flags: any, options?: StorefrontCreationOptions): Promise<StorefrontCreationResult>;
     createThemeApp(config: any, flags: any, installedStorefrontApp: any): Promise<boolean>;
     doesPackageManagerExist(packageManager: string): Promise<boolean>;
     execWithStdio(cwd: string, command: string, onOutput?: (string: string) => any | false): Promise<void>;
@@ -40,6 +53,7 @@ export declare abstract class CreateAppCommand extends SwellCommand {
         displayOrder?: number | undefined;
         mainPackage: string;
         name: string;
+        provisionsStorefront?: boolean | undefined;
         slug: string;
     };
     setupPackage(name: string, config: any, pkg: PackageManager): Promise<void>;

package/dist/create-app-command.js

@@ -9,6 +9,7 @@ import { promisify } from 'node:util';
 import ora from 'ora';
 import Api from './lib/api.js';
 import { FrontendProjectTypes, getFrontendProjectValidValues, getAllConfigPaths, getFrontendProjectSlugs, writeFile, writeJsonFile, } from './lib/apps/index.js';
+import { ensureStorefrontResources, } from './lib/apps/storefront-resources.js';
 import { getPackageManagerCommands, transformCreateCommand, } from './lib/package-manager.js';
 import style from './lib/style.js';
 import { SwellCommand } from './swell-command.js';
@@ -287,7 +288,11 @@ export class CreateAppCommand extends SwellCommand {
                 const files = await fs.readdir(frontendPath);
                 if (files.length > 0) {
                     spinner.fail('frontend/ folder is not empty. Please remove existing files before scaffolding.');
-                    return false;
+                    return {
+                        created: false,
+                        framework: projectType.slug,
+                        provisionsStorefront: Boolean(projectType.provisionsStorefront),
+                    };
                 }
             }
             catch {
@@ -298,11 +303,28 @@ export class CreateAppCommand extends SwellCommand {
                 await execAsync(`mkdir -p frontend`, {
                     cwd: configPath,
                 });
-                // Transform install command for the selected package manager
-                const installCommand = transformCreateCommand(projectType.installCommand, pkg);
-                await execAsync(installCommand, {
-                    cwd: configPath,
-                });
+                // SWELL_LOCAL_TEMPLATE_PATH overrides the scaffold for local dev — copies
+                // the directory at the path into frontend/ instead of running the install
+                // command. Used to iterate on the canonical template repo without pushing.
+                const localTemplatePath = process.env.SWELL_LOCAL_TEMPLATE_PATH;
+                if (localTemplatePath) {
+                    const source = path.resolve(localTemplatePath);
+                    const dest = path.join(configPath, 'frontend');
+                    await fs.cp(source, dest, {
+                        recursive: true,
+                        filter: (src) => !src.includes('/node_modules') &&
+                            !src.endsWith('/.git') &&
+                            !src.includes('/dist') &&
+                            !src.includes('/.wrangler'),
+                    });
+                }
+                else {
+                    // Transform install command for the selected package manager
+                    const installCommand = transformCreateCommand(projectType.installCommand, pkg);
+                    await execAsync(installCommand, {
+                        cwd: configPath,
+                    });
+                }
                 // Use this command to debug output, i.e.e when command becomes non-responsive
                 /* await this.execWithStdio(
                   configPath,
@@ -317,7 +339,11 @@ export class CreateAppCommand extends SwellCommand {
                     .join('\n') || (error.message ?? '').trim();
                 if (detail)
                     this.log(detail);
-                return false;
+                return {
+                    created: false,
+                    framework: projectType.slug,
+                    provisionsStorefront: Boolean(projectType.provisionsStorefront),
+                };
             }
             // Ensure frontend package.json has correct name for workspace
             try {
@@ -346,12 +372,34 @@ export class CreateAppCommand extends SwellCommand {
             if (directCreate) {
                 this.log();
             }
-            return true;
+            return {
+                created: true,
+                framework: projectType.slug,
+                provisionsStorefront: Boolean(projectType.provisionsStorefront),
+            };
         }
-        return false;
+        return {
+            created: false,
+            framework: null,
+            provisionsStorefront: false,
+        };
     }
-    async createStorefrontApp(swellConfig, flags, directCreate) {
-        return this.createFrontendApp(swellConfig, flags, directCreate, 'storefront');
+    async createStorefrontApp(swellConfig, flags, options = {}) {
+        const frontend = await this.createFrontendApp(swellConfig, flags, options.directCreate, 'storefront');
+        if (!options.provisionResources ||
+            !frontend.created ||
+            !frontend.provisionsStorefront) {
+            return frontend;
+        }
+        const resources = await ensureStorefrontResources(this.api, {
+            description: swellConfig.get('description'),
+            name: swellConfig.get('name'),
+            privateId: swellConfig.get('id'),
+            type: 'storefront',
+            version: swellConfig.get('version'),
+        });
+        this.log(`Storefront ${style.appConfigValue(resources.storefront.id)} created for app ${style.appConfigValue(resources.app.id)}.`);
+        return { ...frontend, resources };
     }
     async createThemeApp(config, flags, installedStorefrontApp) {
         const spinner = ora();

package/dist/lib/apps/create-app-result.d.ts

@@ -0,0 +1,31 @@
+import type { StorefrontResourceResult } from './storefront-resources.js';
+export interface CreateAppResultInput {
+    frontend: string | null;
+    name: string;
+    path: string;
+    privateId: string;
+    resources?: StorefrontResourceResult;
+    type: string;
+}
+export interface CreateAppResult {
+    app: {
+        name: string;
+        privateId: string;
+        resourceId: string | null;
+        type: string;
+    };
+    frontend: string | null;
+    path: string;
+    storefront: {
+        resourceId: string;
+    } | null;
+}
+/**
+ * Build the stable JSON contract for every `swell create app` variant.
+ * Remote resource IDs are nullable because only provisioning frontends create
+ * them; the shape itself never changes by app type or frontend.
+ *
+ * @param input completed local and optional remote creation result
+ * @returns serializable command result
+ */
+export declare function buildCreateAppResult(input: CreateAppResultInput): CreateAppResult;

package/dist/lib/apps/create-app-result.js

@@ -0,0 +1,23 @@
+/**
+ * Build the stable JSON contract for every `swell create app` variant.
+ * Remote resource IDs are nullable because only provisioning frontends create
+ * them; the shape itself never changes by app type or frontend.
+ *
+ * @param input completed local and optional remote creation result
+ * @returns serializable command result
+ */
+export function buildCreateAppResult(input) {
+    return {
+        app: {
+            privateId: input.privateId,
+            resourceId: input.resources?.app.id ?? null,
+            name: input.name,
+            type: input.type,
+        },
+        storefront: input.resources
+            ? { resourceId: input.resources.storefront.id }
+            : null,
+        frontend: input.frontend,
+        path: input.path,
+    };
+}

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

@@ -128,6 +128,7 @@ export interface FrontendProjectType {
     installCommand?: string;
     mainPackage: string;
     name: string;
+    provisionsStorefront?: boolean;
     slug: string;
 }
 export declare const CUSTOM_FRAMEWORK_SLUG = "custom";

package/dist/lib/apps/index.js

@@ -130,6 +130,7 @@ export const FrontendProjectTypes = [
         installCommand: 'npm create cloudflare@latest -- frontend --template=swellstores/storefront-react-ai-template#main --deploy=false --git=false --no-agents',
         mainPackage: '@swell/storefront-app-sdk-react',
         name: 'Swell React Storefront',
+        provisionsStorefront: true,
         slug: 'react-storefront',
     },
     {

package/dist/lib/apps/storefront-resources.d.ts

@@ -0,0 +1,28 @@
+import Api from '../api.js';
+export interface StorefrontResourceInput {
+    description?: string;
+    name: string;
+    privateId: string;
+    type: 'storefront';
+    version: string;
+}
+export interface StorefrontResourceResult {
+    app: {
+        id: string;
+        privateId: string;
+    };
+    storefront: {
+        id: string;
+    };
+}
+/**
+ * Ensure the remote development app and its storefront exist.
+ *
+ * `swell create app --frontend react-storefront` calls this after the local
+ * scaffold succeeds. Retrying is safe: existing resources are reused.
+ *
+ * @param api authenticated Swell API client
+ * @param input storefront app identity from the generated swell.json
+ * @returns the stable remote app and storefront IDs
+ */
+export declare function ensureStorefrontResources(api: Api, input: StorefrontResourceInput): Promise<StorefrontResourceResult>;

package/dist/lib/apps/storefront-resources.js

@@ -0,0 +1,60 @@
+import config from '../config.js';
+/**
+ * Ensure the remote development app and its storefront exist.
+ *
+ * `swell create app --frontend react-storefront` calls this after the local
+ * scaffold succeeds. Retrying is safe: existing resources are reused.
+ *
+ * @param api authenticated Swell API client
+ * @param input storefront app identity from the generated swell.json
+ * @returns the stable remote app and storefront IDs
+ */
+export async function ensureStorefrontResources(api, input) {
+    const storeId = config.getDefaultStore();
+    await api.setStoreEnv(storeId, 'test');
+    let app;
+    try {
+        const existing = await api.get({
+            adminPath: `/apps/${input.privateId}`,
+        });
+        if (existing?.client_id === storeId) {
+            app = existing;
+        }
+    }
+    catch {
+        // App not found — create it below.
+    }
+    if (!app) {
+        app = await api.post({ adminPath: '/apps' }, {
+            body: {
+                description: input.description,
+                name: input.name,
+                private_id: input.privateId,
+                type: input.type,
+                version: input.version,
+                permissions: [],
+            },
+        });
+    }
+    const storefronts = await api.get({
+        adminPath: `/apps/${app.id}/storefronts`,
+    });
+    let storefront = storefronts?.results?.[0];
+    if (!storefront) {
+        storefront = await api.post({ adminPath: '/storefronts' }, {
+            body: {
+                app_id: app.id,
+                name: input.name,
+            },
+        });
+    }
+    return {
+        app: {
+            id: app.id,
+            privateId: input.privateId,
+        },
+        storefront: {
+            id: storefront.id,
+        },
+    };
+}

package/oclif.manifest.json

@@ -779,6 +779,13 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "json-events": {
+          "description": "emit machine-readable dev server lifecycle events",
+          "hidden": true,
+          "name": "json-events",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "yes": {
           "char": "y",
           "description": "skip prompts (non-interactive mode)",
@@ -976,6 +983,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "json": {
+          "description": "Output the command result as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1536,6 +1549,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "json": {
+          "description": "Output the command result as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -3215,6 +3234,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "json": {
+          "description": "Output the command result as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -3514,6 +3539,13 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "json-events": {
+          "description": "emit machine-readable dev server lifecycle events",
+          "hidden": true,
+          "name": "json-events",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "yes": {
           "char": "y",
           "description": "skip prompts (non-interactive mode)",
@@ -3556,5 +3588,5 @@
       ]
     }
   },
-  "version": "2.9.6"
+  "version": "2.9.7"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/cli",
-  "version": "2.9.6",
+  "version": "2.9.7",
   "type": "module",
   "description": "Swell's command line interface/utility",
   "keywords": [