zephyr-cli 0.0.0-canary.65 → 0.0.0-canary.66

package/README.md

@@ -40,6 +40,9 @@ ze-cli NODE_ENV=production webpack
 
 # Mark as SSR build
 ze-cli --ssr pnpm build
+
+# Build and publish a TAP package. CLI options for run appear before the build command.
+ze-cli --target tap-app --metadata ./dist/zephyr-publication.json pnpm build
 ```
 
 ### Deploy Command
@@ -59,17 +62,79 @@ ze-cli deploy ./dist
 # Upload with specific target
 ze-cli deploy ./dist --target ios
 
+# Publish a TAP mini-app artifact
+ze-cli deploy ./dist --target tap-app --metadata ./dist/zephyr-publication.json
+
 # Mark as SSR
 ze-cli deploy ./dist --ssr
 ```
 
+### Watch Command
+
+Publish the initial output and then publish each settled output change without
+rebuilding the TAP host. This command deliberately requires `--target tap-app`:
+
+```bash
+# The Zephyr control plane authorizes the development tag; the CLI never creates one locally.
+ze-cli watch ./dist --target tap-app --metadata ./dist/zephyr-publication.json
+```
+
 ## Options
 
 - `--ssr` - Mark this snapshot as server-side rendered
-- `--target, -t <target>` - Build target: `web`, `ios`, or `android` (default: `web`)
+- `--target, -t <target>` - Build target: `web`, `ios`, `android`, or `tap-app` (default: `web`)
+- `--metadata <path>` - JSON Module Federation sidecar. Required with `--target tap-app`.
+- `--debounce <milliseconds>` - Delay a `watch` publication until output changes settle (default: `250`)
 - `--verbose, -v` - Enable verbose output
 - `--help, -h` - Show help message
 
+### TAP metadata sidecar
+
+TAP SDK builds must pass `--metadata <path>` for `run`, `deploy`, and `watch`.
+The file is JSON emitted by the SDK; it keeps each independently addressable
+container in both the snapshot (`mfConfigs`) and build statistics (`federation`).
+The CLI rejects a TAP upload if the sidecar is missing, malformed, empty, or if
+an entry's `federation.remote` does not match its `mfConfigs.filename`.
+
+```json
+{
+  "mfConfigs": [
+    {
+      "name": "desktop",
+      "filename": "targets/desktop/remoteEntry.mjs",
+      "library": { "type": "module" },
+      "exposes": { "./ui": "./src/desktop.ts" }
+    },
+    {
+      "name": "quickjs",
+      "filename": "targets/quickjs/remoteEntry.mjs",
+      "library": { "type": "module" },
+      "exposes": { "./background": "./src/quickjs.ts" }
+    }
+  ],
+  "federation": [
+    {
+      "name": "desktop",
+      "remote": "targets/desktop/remoteEntry.mjs",
+      "mf_manifest": "targets/desktop/mf-manifest.json",
+      "library_type": "module"
+    },
+    {
+      "name": "quickjs",
+      "remote": "targets/quickjs/remoteEntry.mjs",
+      "library_type": "module"
+    }
+  ]
+}
+```
+
+Both arrays must be non-empty and represent the same containers. A single
+container also gets the legacy `mfConfig` snapshot field; multi-container
+sidecars intentionally do not choose an arbitrary first entry. The CLI accepts
+an explicit `mfConfig` only for a TAP sidecar containing that same one container.
+For `run`, place the options before the build command because the SDK creates the
+sidecar during the build. For `watch`, the sidecar is reread for every snapshot.
+
 ## How It Works
 
 ### Run Command

package/dist/cli.d.mts

@@ -0,0 +1,33 @@
+import { type ZephyrBuildTarget } from 'zephyr-edge-contract';
+export interface CliOptions {
+    command: 'run' | 'deploy' | 'watch';
+    commandLine?: string;
+    directory?: string;
+    target?: ZephyrBuildTarget;
+    verbose?: boolean;
+    ssr?: boolean;
+    debounceMs?: number;
+    /** JSON sidecar containing Module Federation publication metadata. */
+    metadataPath?: string;
+}
+/**
+ * Parse command line arguments.
+ *
+ * Syntax:
+ *
+ * - Ze-cli [options] <command> [args...] - run command (default)
+ * - Ze-cli deploy <directory> [options] - deploy command
+ * - Ze-cli watch <directory> [options] - watch and publish command
+ *
+ * Examples:
+ *
+ * - Ze-cli --ssr pnpm build
+ * - Ze-cli tsc
+ * - Ze-cli NODE_ENV=production webpack
+ * - Ze-cli deploy ./dist
+ * - Ze-cli deploy ./dist --target tap-app --metadata ./dist/zephyr-publication.json
+ * - Ze-cli watch ./dist --target tap-app
+ * - Ze-cli deploy ./dist --ssr
+ */
+export declare function parseArgs(args: string[]): CliOptions;
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.ts

@@ -1,10 +1,14 @@
+import { type ZephyrBuildTarget } from 'zephyr-edge-contract';
 export interface CliOptions {
-    command: 'run' | 'deploy';
+    command: 'run' | 'deploy' | 'watch';
     commandLine?: string;
     directory?: string;
-    target?: 'web' | 'ios' | 'android';
+    target?: ZephyrBuildTarget;
     verbose?: boolean;
     ssr?: boolean;
+    debounceMs?: number;
+    /** JSON sidecar containing Module Federation publication metadata. */
+    metadataPath?: string;
 }
 /**
  * Parse command line arguments.
@@ -13,6 +17,7 @@ export interface CliOptions {
  *
  * - Ze-cli [options] <command> [args...] - run command (default)
  * - Ze-cli deploy <directory> [options] - deploy command
+ * - Ze-cli watch <directory> [options] - watch and publish command
  *
  * Examples:
  *
@@ -20,6 +25,9 @@ export interface CliOptions {
  * - Ze-cli tsc
  * - Ze-cli NODE_ENV=production webpack
  * - Ze-cli deploy ./dist
+ * - Ze-cli deploy ./dist --target tap-app --metadata ./dist/zephyr-publication.json
+ * - Ze-cli watch ./dist --target tap-app
  * - Ze-cli deploy ./dist --ssr
  */
 export declare function parseArgs(args: string[]): CliOptions;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,94 +1,106 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseArgs = parseArgs;
-/**
- * Parse command line arguments.
- *
- * Syntax:
- *
- * - Ze-cli [options] <command> [args...] - run command (default)
- * - Ze-cli deploy <directory> [options] - deploy command
- *
- * Examples:
- *
- * - Ze-cli --ssr pnpm build
- * - Ze-cli tsc
- * - Ze-cli NODE_ENV=production webpack
- * - Ze-cli deploy ./dist
- * - Ze-cli deploy ./dist --ssr
- */
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    parseArgs: ()=>parseArgs
+});
+const external_zephyr_edge_contract_namespaceObject = require("zephyr-edge-contract");
 function parseArgs(args) {
     const options = {
-        command: 'run', // Default to 'run'
+        command: 'run'
     };
-    // Find where flags end and the command/subcommand begins
     let commandStartIndex = -1;
     const flags = [];
-    for (let i = 0; i < args.length; i++) {
+    for(let i = 0; i < args.length; i++){
         const arg = args[i];
-        if (arg === '--help' || arg === '-h') {
+        if ('--help' === arg || '-h' === arg) {
             printHelp();
             process.exit(0);
-        }
-        else if (arg === '--version' || arg === '-v') {
-            // Version is handled by the caller
-            options.verbose = true;
-        }
-        else if (arg === '--ssr') {
+        } else if ('--version' === arg || '-v' === arg) options.verbose = true;
+        else if ('--ssr' === arg) {
             options.ssr = true;
             flags.push(arg);
-        }
-        else if (arg === '--target' || arg === '-t') {
+        } else if ('--target' === arg || '-t' === arg) {
             const value = args[++i];
-            if (value && ['web', 'ios', 'android'].includes(value)) {
-                options.target = value;
-            }
+            if ((0, external_zephyr_edge_contract_namespaceObject.isZephyrBuildTarget)(value)) options.target = value;
+            else throw new Error(`Unsupported Zephyr build target: ${String(value)}`);
             flags.push(arg, value);
-        }
-        else if (arg === '--verbose') {
+        } else if ('--metadata' === arg) {
+            const value = args[++i];
+            if (!value || value.startsWith('-')) throw new Error('--metadata requires a JSON sidecar path.');
+            options.metadataPath = value;
+            flags.push(arg, value);
+        } else if ('--debounce' === arg) {
+            const value = Number(args[++i]);
+            if (!Number.isSafeInteger(value) || value < 0) throw new Error(`--debounce must be a non-negative integer, received ${String(value)}`);
+            options.debounceMs = value;
+            flags.push(arg, value.toString());
+        } else if ('--verbose' === arg) {
             options.verbose = true;
             flags.push(arg);
-        }
-        else if (!arg.startsWith('-')) {
-            // First non-flag argument
+        } else if (!arg.startsWith('-')) {
             commandStartIndex = i;
             break;
         }
     }
-    if (commandStartIndex === -1) {
+    if (-1 === commandStartIndex) {
         printHelp();
         process.exit(1);
     }
     const firstArg = args[commandStartIndex];
-    // Check if it's a subcommand
-    if (firstArg === 'deploy') {
-        options.command = 'deploy';
+    if ('deploy' === firstArg || 'watch' === firstArg) {
+        options.command = firstArg;
         const directory = args[commandStartIndex + 1];
         if (!directory) {
-            console.error('Error: deploy command requires a directory argument');
-            console.error('Usage: ze-cli deploy <directory> [options]');
+            console.error(`Error: ${firstArg} command requires a directory argument`);
+            console.error(`Usage: ze-cli ${firstArg} <directory> [options]`);
             process.exit(1);
         }
         options.directory = directory;
-        // Parse any additional flags after the directory
-        for (let i = commandStartIndex + 2; i < args.length; i++) {
+        for(let i = commandStartIndex + 2; i < args.length; i++){
             const arg = args[i];
-            if (arg === '--ssr') {
-                options.ssr = true;
-            }
-            else if (arg === '--target' || arg === '-t') {
+            if ('--ssr' === arg) options.ssr = true;
+            else if ('--target' === arg || '-t' === arg) {
                 const value = args[++i];
-                if (value && ['web', 'ios', 'android'].includes(value)) {
-                    options.target = value;
-                }
-            }
-            else if (arg === '--verbose') {
-                options.verbose = true;
-            }
+                if ((0, external_zephyr_edge_contract_namespaceObject.isZephyrBuildTarget)(value)) options.target = value;
+                else throw new Error(`Unsupported Zephyr build target: ${String(value)}`);
+            } else if ('--metadata' === arg) {
+                const value = args[++i];
+                if (!value || value.startsWith('-')) throw new Error('--metadata requires a JSON sidecar path.');
+                options.metadataPath = value;
+            } else if ('--debounce' === arg) {
+                const value = Number(args[++i]);
+                if (!Number.isSafeInteger(value) || value < 0) throw new Error(`--debounce must be a non-negative integer, received ${String(value)}`);
+                options.debounceMs = value;
+            } else if ('--verbose' === arg) options.verbose = true;
         }
-    }
-    else {
-        // It's a run command - everything from commandStartIndex onwards is the command
+    } else {
         options.command = 'run';
         options.commandLine = args.slice(commandStartIndex).join(' ');
     }
@@ -105,10 +117,13 @@ pre-built assets from a directory.
 Commands:
   <command> [args...]      Run a build command and upload (default)
   deploy <directory>       Upload pre-built assets from a directory
+  watch <directory>        Watch pre-built output and publish each settled change
 
 Options:
   --ssr                    Mark this snapshot as server-side rendered
-  --target, -t <target>    Build target: web, ios, or android (default: web)
+  --target, -t <target>    Build target: web, ios, android, or tap-app (default: web)
+  --metadata <path>        JSON sidecar for Module Federation publication metadata
+  --debounce <milliseconds>  Delay output-watch publications after changes (default: 250)
   --verbose                Enable verbose output
   --help, -h               Show this help message
 
@@ -119,16 +134,21 @@ Examples:
   ze-cli tsc
   ze-cli NODE_ENV=production webpack
   ze-cli --ssr pnpm build
+  ze-cli --target tap-app --metadata ./dist/zephyr-publication.json pnpm build
 
   # Deploy pre-built assets
   ze-cli deploy ./dist
   ze-cli deploy ./dist --ssr
   ze-cli deploy ./build --target ios
+  ze-cli deploy ./dist --target tap-app --metadata ./dist/zephyr-publication.json
+  ze-cli watch ./dist --target tap-app
 
 How it works:
   - For run commands, ze-cli executes your build command and automatically
     detects the output directory to upload assets.
   - For deploy commands, ze-cli uploads assets from the specified directory.
+  - For watch commands, ze-cli publishes each settled output change as a new immutable
+    snapshot. The Zephyr control plane authorizes and advances any development tag.
   - All stdout/stderr from build commands are passed through.
   - ze-cli logs are written to stderr only.
 
@@ -138,4 +158,12 @@ application information from your package.json and git repository.
 For more information: https://docs.zephyr-cloud.io/cli
 `);
 }
+exports.parseArgs = __webpack_exports__.parseArgs;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "parseArgs"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});
+
 //# sourceMappingURL=cli.js.map

package/dist/cli.mjs

@@ -0,0 +1,131 @@
+import { isZephyrBuildTarget } from "zephyr-edge-contract";
+function parseArgs(args) {
+    const options = {
+        command: 'run'
+    };
+    let commandStartIndex = -1;
+    const flags = [];
+    for(let i = 0; i < args.length; i++){
+        const arg = args[i];
+        if ('--help' === arg || '-h' === arg) {
+            printHelp();
+            process.exit(0);
+        } else if ('--version' === arg || '-v' === arg) options.verbose = true;
+        else if ('--ssr' === arg) {
+            options.ssr = true;
+            flags.push(arg);
+        } else if ('--target' === arg || '-t' === arg) {
+            const value = args[++i];
+            if (isZephyrBuildTarget(value)) options.target = value;
+            else throw new Error(`Unsupported Zephyr build target: ${String(value)}`);
+            flags.push(arg, value);
+        } else if ('--metadata' === arg) {
+            const value = args[++i];
+            if (!value || value.startsWith('-')) throw new Error('--metadata requires a JSON sidecar path.');
+            options.metadataPath = value;
+            flags.push(arg, value);
+        } else if ('--debounce' === arg) {
+            const value = Number(args[++i]);
+            if (!Number.isSafeInteger(value) || value < 0) throw new Error(`--debounce must be a non-negative integer, received ${String(value)}`);
+            options.debounceMs = value;
+            flags.push(arg, value.toString());
+        } else if ('--verbose' === arg) {
+            options.verbose = true;
+            flags.push(arg);
+        } else if (!arg.startsWith('-')) {
+            commandStartIndex = i;
+            break;
+        }
+    }
+    if (-1 === commandStartIndex) {
+        printHelp();
+        process.exit(1);
+    }
+    const firstArg = args[commandStartIndex];
+    if ('deploy' === firstArg || 'watch' === firstArg) {
+        options.command = firstArg;
+        const directory = args[commandStartIndex + 1];
+        if (!directory) {
+            console.error(`Error: ${firstArg} command requires a directory argument`);
+            console.error(`Usage: ze-cli ${firstArg} <directory> [options]`);
+            process.exit(1);
+        }
+        options.directory = directory;
+        for(let i = commandStartIndex + 2; i < args.length; i++){
+            const arg = args[i];
+            if ('--ssr' === arg) options.ssr = true;
+            else if ('--target' === arg || '-t' === arg) {
+                const value = args[++i];
+                if (isZephyrBuildTarget(value)) options.target = value;
+                else throw new Error(`Unsupported Zephyr build target: ${String(value)}`);
+            } else if ('--metadata' === arg) {
+                const value = args[++i];
+                if (!value || value.startsWith('-')) throw new Error('--metadata requires a JSON sidecar path.');
+                options.metadataPath = value;
+            } else if ('--debounce' === arg) {
+                const value = Number(args[++i]);
+                if (!Number.isSafeInteger(value) || value < 0) throw new Error(`--debounce must be a non-negative integer, received ${String(value)}`);
+                options.debounceMs = value;
+            } else if ('--verbose' === arg) options.verbose = true;
+        }
+    } else {
+        options.command = 'run';
+        options.commandLine = args.slice(commandStartIndex).join(' ');
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`
+Usage: ze-cli [options] <command> [args...]
+       ze-cli deploy <directory> [options]
+
+Run a build command and automatically upload assets to Zephyr, or deploy
+pre-built assets from a directory.
+
+Commands:
+  <command> [args...]      Run a build command and upload (default)
+  deploy <directory>       Upload pre-built assets from a directory
+  watch <directory>        Watch pre-built output and publish each settled change
+
+Options:
+  --ssr                    Mark this snapshot as server-side rendered
+  --target, -t <target>    Build target: web, ios, android, or tap-app (default: web)
+  --metadata <path>        JSON sidecar for Module Federation publication metadata
+  --debounce <milliseconds>  Delay output-watch publications after changes (default: 250)
+  --verbose                Enable verbose output
+  --help, -h               Show this help message
+
+Examples:
+  # Run build commands
+  ze-cli pnpm build
+  ze-cli yarn build
+  ze-cli tsc
+  ze-cli NODE_ENV=production webpack
+  ze-cli --ssr pnpm build
+  ze-cli --target tap-app --metadata ./dist/zephyr-publication.json pnpm build
+
+  # Deploy pre-built assets
+  ze-cli deploy ./dist
+  ze-cli deploy ./dist --ssr
+  ze-cli deploy ./build --target ios
+  ze-cli deploy ./dist --target tap-app --metadata ./dist/zephyr-publication.json
+  ze-cli watch ./dist --target tap-app
+
+How it works:
+  - For run commands, ze-cli executes your build command and automatically
+    detects the output directory to upload assets.
+  - For deploy commands, ze-cli uploads assets from the specified directory.
+  - For watch commands, ze-cli publishes each settled output change as a new immutable
+    snapshot. The Zephyr control plane authorizes and advances any development tag.
+  - All stdout/stderr from build commands are passed through.
+  - ze-cli logs are written to stderr only.
+
+Note: No configuration file is needed. Zephyr will automatically detect
+application information from your package.json and git repository.
+
+For more information: https://docs.zephyr-cloud.io/cli
+`);
+}
+export { parseArgs };
+
+//# sourceMappingURL=cli.mjs.map

package/dist/commands/deploy.d.mts

@@ -0,0 +1,16 @@
+import type { ZephyrBuildTarget } from 'zephyr-edge-contract';
+export interface DeployOptions {
+    directory: string;
+    target?: ZephyrBuildTarget;
+    verbose?: boolean;
+    ssr?: boolean;
+    /** JSON sidecar emitted by a TAP SDK or compatible bundler. */
+    metadataPath?: string;
+    cwd: string;
+}
+/**
+ * Deploy command: Upload pre-built assets from a directory to Zephyr. This is similar to
+ * the standalone zephyr-cli tool.
+ */
+export declare function deployCommand(options: DeployOptions): Promise<void>;
+//# sourceMappingURL=deploy.d.mts.map

package/dist/commands/deploy.d.ts

@@ -1,8 +1,11 @@
+import type { ZephyrBuildTarget } from 'zephyr-edge-contract';
 export interface DeployOptions {
     directory: string;
-    target?: 'web' | 'ios' | 'android';
+    target?: ZephyrBuildTarget;
     verbose?: boolean;
     ssr?: boolean;
+    /** JSON sidecar emitted by a TAP SDK or compatible bundler. */
+    metadataPath?: string;
     cwd: string;
 }
 /**
@@ -10,3 +13,4 @@ export interface DeployOptions {
  * the standalone zephyr-cli tool.
  */
 export declare function deployCommand(options: DeployOptions): Promise<void>;
+//# sourceMappingURL=deploy.d.ts.map