@ubox-tools/deploy-xperience 1.0.0 → 1.1.0

package/README.md

@@ -27,6 +27,8 @@ npx @ubox-tools/deploy-xperience [app1 app2 ...] [options]
 | `--project-name <name>` | Override the project name (default: parent directory name) |
 | `--noassets` | Skip uploading assets (images, fonts, files) |
 | `--noplayer` | Skip Phase 3 — deploy apps only, do not create/update Uboxes |
+| `--ubox-id <id>` | Use a pre-existing Ubox by ID — skips search/create (single-app deployments) |
+| `--ubox-id <app>:<id>` | Scoped form for multi-app deployments (repeatable) |
 | `--show` | Show the browser window (default: headless) |
 | `--help` | Print usage and exit |
 
@@ -47,6 +49,8 @@ npx @ubox-tools/deploy-xperience mobile                 # Deploy only the mobile
 npx @ubox-tools/deploy-xperience main --noassets        # Deploy main app, skip asset uploads
 npx @ubox-tools/deploy-xperience --noplayer             # Deploy apps only, skip Uboxes
 npx @ubox-tools/deploy-xperience --project-name "MyProject"
+npx @ubox-tools/deploy-xperience mobile --ubox-id 42   # Use existing Ubox #42 for mobile
+npx @ubox-tools/deploy-xperience --ubox-id mobile:42 --ubox-id main:99
 ```
 
 ## Deployment Phases
@@ -76,6 +80,8 @@ Runs once per app:
 
 If the Ubox already exists, installation and parameter changes are skipped; the mobile virtual link is still retrieved so the main Ubox can use it.
 
+When `--ubox-id` is provided, the search/create step is skipped entirely and the script navigates directly to `https://studio.ubox.world/#/ubox/<id>`. The same "already exists" logic then applies.
+
 ## Proxy / Source Transformation
 
 Before injecting source files, `generateProxy()` applies three transforms to each file:

package/deploy.js

@@ -52,6 +52,8 @@ Options:
   --project-name <name>  Override project name (default: directory name)
   --noassets             Skip uploading assets (resources)
   --noplayer             Skip Ubox creation (Phase 3) — only deploy applications
+  --ubox-id <id>         Use a pre-existing Ubox by ID (skips search/create)
+  --ubox-id <app>:<id>   Scoped form when deploying multiple apps
   --show                 Show the browser window (default: headless)
   --help                 Show this help
 
@@ -61,6 +63,8 @@ Examples:
   npx @ubox-tools/deploy-xperience main              # Deploy only main
   npx @ubox-tools/deploy-xperience --noassets        # Deploy without re-uploading assets
   npx @ubox-tools/deploy-xperience --noplayer        # Deploy apps only, skip Uboxes
+  npx @ubox-tools/deploy-xperience --ubox-id 42      # Use existing Ubox #42 (single-app)
+  npx @ubox-tools/deploy-xperience --ubox-id mobile:42 --ubox-id main:99
   UBOX_EMAIL=me@x.com npx @ubox-tools/deploy-xperience
 `.trim());
     process.exit(0);
@@ -73,6 +77,8 @@ Examples:
   let noPlayer    = false;
   let show        = false;
   const appArgs   = [];
+  const uboxIds   = {};
+  let   bareUboxId = null;
 
   for (let i = 0; i < args.length; i++) {
     if      (args[i] === '--email')        { email = args[++i]; }
@@ -81,6 +87,15 @@ Examples:
     else if (args[i] === '--noassets')     { noAssets = true; }
     else if (args[i] === '--noplayer')     { noPlayer = true; }
     else if (args[i] === '--show')         { show = true; }
+    else if (args[i] === '--ubox-id') {
+      const val = args[++i];
+      if (val.includes(':')) {
+        const colon = val.indexOf(':');
+        uboxIds[val.slice(0, colon)] = val.slice(colon + 1);
+      } else {
+        bareUboxId = val;
+      }
+    }
     else if (!args[i].startsWith('--'))    { appArgs.push(args[i]); }
   }
 
@@ -101,7 +116,15 @@ Examples:
     ...selected.filter(a => !DEPLOY_ORDER.includes(a)),
   ];
 
-  return { apps: ordered, email, password, projectName, noAssets, noPlayer, show };
+  if (bareUboxId !== null) {
+    if (ordered.length !== 1) {
+      console.error('Error: bare --ubox-id <id> requires exactly one app to be selected.\nUse --ubox-id <app>:<id> form when deploying multiple apps (e.g. --ubox-id mobile:42 --ubox-id main:99).');
+      process.exit(1);
+    }
+    uboxIds[ordered[0]] = bareUboxId;
+  }
+
+  return { apps: ordered, email, password, projectName, noAssets, noPlayer, show, uboxIds };
 }
 
 // ─── Credentials ──────────────────────────────────────────────────────────────
@@ -943,11 +966,20 @@ async function setMobileLink(page, appFullName, mobileVirtualLink) {
   console.log(`  [ubox] mobileLink = ${mobileVirtualLink}`);
 }
 
-async function deployUbox(page, appName, projectName, appParams, mobileVirtualLink) {
+async function deployUbox(page, appName, projectName, appParams, mobileVirtualLink, targetUboxId = null) {
   const fullName = `${projectName} ${appName}`;
   console.log(`\n[Phase 3] Ubox: ${fullName}`);
 
-  const { url: uboxUrl, created } = await findOrCreateUbox(page, fullName);
+  let uboxUrl, created;
+  if (targetUboxId) {
+    uboxUrl = `${BASE_URL}/#/ubox/${targetUboxId}`;
+    console.log(`  [ubox] Using pre-existing Ubox ID ${targetUboxId} — navigating directly...`);
+    await page.goto(uboxUrl, { waitUntil: 'networkidle2' });
+    await sleep(2000);
+    created = false;
+  } else {
+    ({ url: uboxUrl, created } = await findOrCreateUbox(page, fullName));
+  }
 
   let virtualLink = null;
 
@@ -990,7 +1022,7 @@ async function deployUbox(page, appName, projectName, appParams, mobileVirtualLi
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 async function main() {
-  const { apps, email: emailArg, password: passwordArg, projectName: projectNameArg, noAssets, noPlayer, show } = parseArgs();
+  const { apps, email: emailArg, password: passwordArg, projectName: projectNameArg, noAssets, noPlayer, show, uboxIds } = parseArgs();
 
   if (apps.length === 0) {
     console.error('No apps found in apps/ directory. Nothing to deploy.');
@@ -1039,7 +1071,8 @@ async function main() {
       let mobileVirtualLink = null;
       for (const appName of apps) {
         const { uboxId, virtualLink } = await deployUbox(
-          page, appName, projectName, appParamsMap[appName], mobileVirtualLink
+          page, appName, projectName, appParamsMap[appName], mobileVirtualLink,
+          uboxIds[appName] ?? null
         );
         state[appName].uboxId = uboxId;
         if (appName === 'mobile' && virtualLink) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubox-tools/deploy-xperience",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Deploy a Ubox experience to studio.ubox.world",
   "bin": { "deploy-xperience": "./deploy.js" },
   "dependencies": { "puppeteer": "*" },