@swell/cli 2.9.6 → 2.9.8

package/dist/app-command.d.ts

@@ -14,6 +14,7 @@ export declare abstract class AppCommand extends SwellCommand {
     static baseFlags: {
         'app-path': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
+    static requiresSwellConfig: boolean;
     appPath: string;
     swellConfig: LocalApp;
     init(): Promise<void>;

package/dist/app-command.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core';
 import * as path from 'node:path';
-import { default as swellConfig } from './lib/app-config.js';
+import { default as swellConfig, swellConfigFileExists, } from './lib/app-config.js';
+import style from './lib/style.js';
 import { SwellCommand } from './swell-command.js';
 /**
  * A base class for Swell CLI commands that do not require an app to be saved
@@ -20,6 +21,8 @@ export class AppCommand extends SwellCommand {
             description: 'Path to your app directory',
         }),
     };
+    // set to false for commands that may run before an app directory exists (pull)
+    static requiresSwellConfig = true;
     // the local path to the app directory
     appPath = '';
     // local app configuration, what developers define
@@ -35,8 +38,17 @@ export class AppCommand extends SwellCommand {
         // ensure the base flags are available
         klass.flags = { ...klass.flags, ...AppCommand.baseFlags };
         const { flags } = await this.parse(klass);
+        const targetDir = flags['app-path']
+            ? path.resolve(flags['app-path'])
+            : process.cwd();
+        // swell.json is only ever looked up in this exact directory
+        // Searching parent directories (the previous behavior) can silently pick up an unrelated app's config
+        if (klass.requiresSwellConfig &&
+            !(await swellConfigFileExists(path.join(targetDir, 'swell.json')))) {
+            this.error(`No swell.json found in ${style.path(targetDir)}. Run this command from your app's root directory, or pass --app-path.`);
+        }
         // if the user passed an app path, use it: reload the app config
-        this.swellConfig = await swellConfig(flags['app-path']);
+        this.swellConfig = await swellConfig(targetDir);
         this.appPath = path.resolve(this.swellConfig.swDirPath);
     }
 }

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/app/pull.d.ts

@@ -4,6 +4,7 @@ export default class AppPull extends PushAppCommand {
         appId: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
         targetPath: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
     };
+    static requiresSwellConfig: boolean;
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/app/pull.js

@@ -11,6 +11,7 @@ export default class AppPull extends PushAppCommand {
             description: 'path to download app files into',
         }),
     };
+    static requiresSwellConfig = false;
     static description = `Pull all app files, a specific file, or a specific configuration
 type from an app in your store's test environment to your local machine.
 

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';
@@ -208,12 +209,11 @@ export class CreateAppCommand extends SwellCommand {
         await fs.writeFile(configFilePath, content, 'utf8');
     }
     async createAppConfigFolders(swellConfig) {
+        const configPath = path.dirname(swellConfig.path);
         for (const type of getAllConfigPaths(swellConfig.get('type'))) {
             // Create a config folder
             // eslint-disable-next-line no-await-in-loop
-            await execAsync(`mkdir -p ${type}`, {
-                cwd: path.dirname(swellConfig.path),
-            });
+            await fs.mkdir(path.join(configPath, type), { recursive: true });
         }
     }
     async createFrontendApp(swellConfig, flags, directCreate, kind) {
@@ -287,7 +287,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 {
@@ -295,14 +299,31 @@ export class CreateAppCommand extends SwellCommand {
             }
             spinner.start(`Creating ${projectType?.name} frontend app (this may take a while)...`);
             try {
-                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,
+                await fs.mkdir(path.join(configPath, 'frontend'), {
+                    recursive: true,
                 });
+                // 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 +338,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 +371,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();
@@ -369,16 +416,14 @@ export class CreateAppCommand extends SwellCommand {
                 this.log();
                 spinner.start(`Creating theme template...`);
                 try {
-                    await execAsync(`mkdir -p theme`, {
-                        cwd: configPath,
-                    });
+                    await fs.mkdir(path.join(configPath, 'theme'), { recursive: true });
                     for (const themeConfig of defaultThemeConfigs.results) {
                         const filePath = themeConfig.file_path.replace(/^frontend\/theme-template\//, '');
                         const fileContent = themeConfig.file_data;
                         const isJson = filePath.endsWith('.json');
                         // eslint-disable-next-line no-await-in-loop
-                        await execAsync(`mkdir -p ${path.dirname(filePath)}`, {
-                            cwd: configPath,
+                        await fs.mkdir(path.join(configPath, path.dirname(filePath)), {
+                            recursive: true,
                         });
                         // eslint-disable-next-line no-await-in-loop
                         await (isJson

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

@@ -2,7 +2,7 @@
 /// <reference types="node" resolution-mode="require"/>
 import { AppConfig } from './app-config.js';
 export { AppConfig, FunctionProcessingError, IgnoringFileError, } from './app-config.js';
-export { allBaseFilesInDir, allConfigDirsPaths, allConfigFilesInDir, allConfigFilesPaths, allConfigFilesPathsByType, getAllConfigPaths, globAllFilesByPath, isPathDirectory, } from './paths.js';
+export { allBaseFilesInDir, allConfigDirsPaths, allConfigFilesInDir, allConfigFilesPaths, allConfigFilesPathsByType, getAllConfigPaths, globAllFilesByPath, isPathDirectory, toPosixPath, } from './paths.js';
 export declare const PUSH_CONCURRENCY = 3;
 /**
  * An app as defined by the Swell API. This is different than an app
@@ -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

@@ -5,7 +5,7 @@ import * as path from 'node:path';
 import { detectPackageManager, transformCommand } from '../package-manager.js';
 import { AppConfig } from './app-config.js';
 export { AppConfig, FunctionProcessingError, IgnoringFileError, } from './app-config.js';
-export { allBaseFilesInDir, allConfigDirsPaths, allConfigFilesInDir, allConfigFilesPaths, allConfigFilesPathsByType, getAllConfigPaths, globAllFilesByPath, isPathDirectory, } from './paths.js';
+export { allBaseFilesInDir, allConfigDirsPaths, allConfigFilesInDir, allConfigFilesPaths, allConfigFilesPathsByType, getAllConfigPaths, globAllFilesByPath, isPathDirectory, toPosixPath, } from './paths.js';
 export const PUSH_CONCURRENCY = 3;
 export var SwellJsonFields;
 (function (SwellJsonFields) {
@@ -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/paths.d.ts

@@ -1,5 +1,6 @@
 import { type GlobbyFilterFunction } from 'globby';
 import { ConfigType } from './index.js';
+export declare function toPosixPath(inputPath: string): string;
 export declare function globAllFilesByPath(appPath: string, dirPath?: string): Promise<string[]>;
 export declare function getGlobIgnorePathsChecker(appPath: string): Promise<GlobbyFilterFunction>;
 export declare function allConfigDirsPaths(appPath: string): Generator<{

package/dist/lib/apps/paths.js

@@ -27,11 +27,15 @@ function globOptions(appPath, options) {
         ],
     };
 }
+// use forward slashes to support Windows
+export function toPosixPath(inputPath) {
+    return inputPath.split(path.sep).join('/');
+}
 function globFilesSync(pattern, appPath, dirPath = '.', options = {}) {
-    return globbySync(`${dirPath}${path.sep}${pattern}`, globOptions(appPath, options));
+    return globbySync(`${toPosixPath(dirPath)}/${pattern}`, globOptions(appPath, options));
 }
 function globFiles(pattern, appPath, dirPath = '.', options = {}) {
-    return globby(`${dirPath}${path.sep}${pattern}`, globOptions(appPath, options));
+    return globby(`${toPosixPath(dirPath)}/${pattern}`, globOptions(appPath, options));
 }
 export function globAllFilesByPath(appPath, dirPath) {
     return globFiles('**', appPath, dirPath);

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/dist/push-app-command.js

@@ -6,7 +6,7 @@ import * as path from 'node:path';
 import Stream from 'node:stream';
 import ora from 'ora';
 import { default as swellConfig } from './lib/app-config.js';
-import { ConfigType, getFrontendProjectValidValues, allConfigFilesInDir, CUSTOM_FRAMEWORK_SLUG, appConfigFromFile, filePathExistsAsync, findAppConfig, getConfigTypeFromPath, getConfigTypeKeyFromValue, getFrontendProjectType, getProjectCommands, globAllFilesByPath, hashString, isPathDirectory, } from './lib/apps/index.js';
+import { ConfigType, getFrontendProjectValidValues, allConfigFilesInDir, CUSTOM_FRAMEWORK_SLUG, appConfigFromFile, filePathExistsAsync, findAppConfig, getConfigTypeFromPath, getConfigTypeKeyFromValue, getFrontendProjectType, getProjectCommands, globAllFilesByPath, hashString, isPathDirectory, toPosixPath, } from './lib/apps/index.js';
 import { getGlobIgnorePathsChecker } from './lib/apps/paths.js';
 import { slugFromApp } from './lib/apps/slug.js';
 import { default as localConfig } from './lib/config.js';
@@ -32,14 +32,12 @@ export class PushAppCommand extends RemoteAppCommand {
         if (!filename) {
             return;
         }
-        if (this.watchingIgnoreFilter && this.watchingIgnoreFilter(filename)) {
+        const configFile = toPosixPath(filename);
+        if (this.watchingIgnoreFilter && this.watchingIgnoreFilter(configFile)) {
             return;
         }
-        const configFile = filename;
-        const pathParsed = path.parse(configFile);
-        const fileDirs = pathParsed.dir.split(path.sep);
         // only the first directory is relevant for us
-        const configDir = fileDirs[0];
+        const configDir = configFile.split('/')[0];
         // we only want to watch files in the root of the app directory
         // and ignore build files etc
         // TODO: renaming a folder doesn't seem to work
@@ -433,7 +431,7 @@ export class PushAppCommand extends RemoteAppCommand {
     async getFrontendDeploymentHash() {
         const localConfigs = await this.getLocalAppConfigs();
         let frontendHashes = localConfigs
-            .filter((config) => config.filePath?.startsWith(`frontend${path.sep}`))
+            .filter((config) => config.filePath?.startsWith('frontend/'))
             .map((config) => config.hash)
             .sort()
             .join('|');
@@ -675,16 +673,18 @@ export class PushAppCommand extends RemoteAppCommand {
         this.log(`View your storefront at ${style.link(this.storefrontFrontendUrl(currentStore, storefront, branchId))}.`);
     }
     async pushFile(relativePath) {
-        const basePath = relativePath.split(path.sep)[0];
+        const relativePathPosix = toPosixPath(relativePath);
+        const basePath = relativePathPosix.split('/')[0];
         const configType = getConfigTypeFromPath(basePath) || ConfigType.FILE;
-        const config = await appConfigFromFile(relativePath, configType, this.appPath);
+        const config = await appConfigFromFile(relativePathPosix, configType, this.appPath);
         await this.pushRemoteFile(config);
     }
     async pushFilePath(relativePath, force) {
         const topDir = relativePath.split(path.sep)[0];
         const configType = getConfigTypeFromPath(topDir) || ConfigType.FILE;
         const configTypeKey = getConfigTypeKeyFromValue(configType) || ConfigType.FILE;
-        const exAppConfigs = (this.app?.configs || []).filter((config) => config.filePath?.startsWith(`${relativePath}/`));
+        const relativePathPosix = toPosixPath(relativePath);
+        const exAppConfigs = (this.app?.configs || []).filter((config) => config.filePath?.startsWith(`${relativePathPosix}/`));
         const promises = [];
         for (const { configFile } of allConfigFilesInDir(this.appPath, relativePath, configTypeKey)) {
             promises.push(appConfigFromFile(configFile, configType, this.appPath));

package/oclif.manifest.json

@@ -708,6 +708,7 @@
       "pluginType": "core",
       "strict": true,
       "enableJsonFlag": false,
+      "requiresSwellConfig": true,
       "delayOrientation": false,
       "orientation": {
         "env": "test"
@@ -779,6 +780,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)",
@@ -844,6 +852,7 @@
       "strict": true,
       "summary": "Show information about your Swell app.",
       "enableJsonFlag": false,
+      "requiresSwellConfig": true,
       "delayOrientation": false,
       "isESM": true,
       "relativePath": [
@@ -976,6 +985,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "json": {
+          "description": "Output the command result as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1088,6 +1103,7 @@
       "strict": true,
       "summary": "Install an existing app in another store environment.",
       "enableJsonFlag": false,
+      "requiresSwellConfig": true,
       "delayOrientation": false,
       "orientation": {
         "env": "test"
@@ -1144,6 +1160,7 @@
       "pluginType": "core",
       "strict": true,
       "summary": "Pull app files from Swell to your local machine.",
+      "requiresSwellConfig": false,
       "orientation": {
         "env": "test"
       },
@@ -1536,6 +1553,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "json": {
+          "description": "Output the command result as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -2279,6 +2302,7 @@
       "strict": true,
       "summary": "Create tests scaffolding for your Swell app.",
       "enableJsonFlag": false,
+      "requiresSwellConfig": true,
       "helpMeta": {
         "usageDirect": "[-y]"
       },
@@ -3215,6 +3239,12 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "json": {
+          "description": "Output the command result as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -3301,6 +3331,7 @@
       "pluginName": "@swell/cli",
       "pluginType": "core",
       "summary": "Pull theme files from Swell to your local machine.",
+      "requiresSwellConfig": false,
       "orientation": {
         "env": "test"
       },
@@ -3514,6 +3545,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 +3594,5 @@
       ]
     }
   },
-  "version": "2.9.6"
+  "version": "2.9.8"
 }

package/package.json

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