@genex-ai/cli-demo 0.17.0 → 0.18.0

package/README.md

@@ -5,6 +5,7 @@ This is the `cli` app of the [genex monorepo](../../README.md).
 
 ```bash
 genex init <name>          # authorize + create the draft project
+genex link <slug>          # re-link this folder to an existing game of yours (recovery)
 genex preview              # build + push to the hosted draft URL (unlisted)
 genex publish              # build + push, then list the game in the gallery
 genex model "<prompt>"     # generate a 3D model  → assets/models/
@@ -39,6 +40,15 @@ genex controller <type>    # install a tuned character|car|drone controller →
    `sshUrl`, urls) in `./.genex/project.json`. The game shows up in your
    dashboard's **My games** immediately.
 
+`genex link <slug>` is the recovery counterpart of step 4 for a game that
+already exists: run it inside a fresh clone of the game's source repo (or any
+folder that lost its link) and it re-authorizes if needed, reuses or generates
+`genex_key`, registers the public half via `POST /api/projects/:id/deploy-key`
+(keys are added, never replaced), and rewrites `./.genex/project.json` — after
+which `preview`/`publish` update the **same** live game. It never creates a
+project; the dashboard's "Continue building" flow uses it when the original
+folder can't be found.
+
 `genex preview` and `genex publish` share a build-aware deploy core: each runs
 `npm run build` (when the project has a build script), then uploads the built
 `dist/` to R2 through a short-lived scoped upload token and flips a live pointer;

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import path13 from "path";
+import path14 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/init.ts
@@ -806,16 +806,185 @@ async function runInit(opts) {
   log.success("All set. \u{1F680}");
 }
 
-// src/commands/publish.ts
-import fs8 from "fs/promises";
-import path9 from "path";
+// src/commands/link.ts
+import fs7 from "fs/promises";
+import path8 from "path";
+async function runLink(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  log.plain(c.bold("genex link"));
+  log.plain("");
+  const slug = opts.name?.trim();
+  if (!slug) {
+    log.error("Which game? Usage: genex link <slug> (the name in your play URL).");
+    process.exitCode = 1;
+    return;
+  }
+  const existing = await readProject();
+  if (existing && existing.slug !== slug && !opts.force) {
+    log.error(
+      `This folder is already linked to ${c.cyan(existing.slug)}. Run link inside the right folder, or pass --force to re-link it to ${c.cyan(slug)}.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const authBaseUrl = getAuthUrl(opts.authUrl);
+  let token = await readUserToken(opts.envPath);
+  if (!token) {
+    token = await authorize(authBaseUrl, {
+      log,
+      timeoutMs: opts.timeoutSec ? opts.timeoutSec * 1e3 : void 0
+    });
+    const { path: tokenPath } = await writeUserToken(token, opts.envPath);
+    log.success(`Authorized. Saved your token to ${c.cyan(tokenPath)}.`);
+    log.plain("");
+  }
+  const apiUrl = getApiUrl(opts.apiUrl);
+  log.step(`Looking up ${c.cyan(slug)}\u2026`);
+  const project = await fetchOwnProject(apiUrl, token, slug, log);
+  if (!project) {
+    process.exitCode = 1;
+    return;
+  }
+  const key = await generateSshKeypair(process.cwd(), log);
+  if (!key) {
+    log.error("No deploy key \u2014 install ssh-keygen (OpenSSH) and re-run `genex link`.");
+    process.exitCode = 1;
+    return;
+  }
+  await writeGitignore(process.cwd(), log);
+  log.step("Registering this folder's deploy key\u2026");
+  const linked = await registerDeployKey(apiUrl, token, project.id, key.publicKey, log);
+  if (!linked) {
+    process.exitCode = 1;
+    return;
+  }
+  const meta = {
+    id: project.id,
+    slug: project.slug,
+    sshUrl: linked.sshUrl,
+    apiUrl,
+    colyseusUrl: getColyseusUrl(opts.colyseusUrl),
+    playUrl: project.playUrl ?? void 0,
+    status: project.status ?? "draft",
+    dashboardOrigins: [new URL(authBaseUrl).origin]
+  };
+  const { path: metaPath } = await writeProject(meta);
+  log.dim(`  saved ${c.cyan(metaPath)}`);
+  await writeGameConfigFiles(meta, log);
+  await ensureSlugEnv(project.slug, log);
+  log.plain("");
+  log.success(
+    `Linked. This folder now updates ${c.cyan(project.slug)} \u2014 \`npx genex preview\` / \`publish\` ship to the same live game.`
+  );
+  if (project.playUrl) log.dim(`  play URL: ${project.playUrl}`);
+}
+async function ensureSlugEnv(slug, log, cwd = process.cwd()) {
+  const file = path8.join(cwd, ".env");
+  let content;
+  try {
+    content = await fs7.readFile(file, "utf8");
+  } catch {
+    return;
+  }
+  const re = /^(\s*VITE_GENEX_SLUG=)(.*)$/m;
+  const m = content.match(re);
+  if (!m) {
+    await fs7.appendFile(file, `${content.endsWith("\n") ? "" : "\n"}VITE_GENEX_SLUG=${slug}
+`);
+    log.dim(`  added VITE_GENEX_SLUG=${slug} to .env`);
+    return;
+  }
+  if (m[2].trim() === slug) return;
+  await fs7.writeFile(file, content.replace(re, `$1${slug}`));
+  log.dim(`  updated .env: VITE_GENEX_SLUG=${slug} (was ${m[2].trim()})`);
+}
+async function fetchOwnProject(apiUrl, token, slug, log) {
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/api/projects/by-slug/${encodeURIComponent(slug)}`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+  } catch (err) {
+    log.error(`Couldn't reach the API at ${apiUrl}.`);
+    log.dim(`  ${String(err)}`);
+    return null;
+  }
+  if (res.status === 401) {
+    log.error(
+      "Not authorized (token rejected). Delete ~/.genex/env and re-run `genex link` to sign in again."
+    );
+    return null;
+  }
+  if (res.status === 404) {
+    log.error(`No game of yours is named ${c.cyan(slug)}.`);
+    await listOwnSlugs(apiUrl, token, log);
+    return null;
+  }
+  if (!res.ok) {
+    log.error(`Couldn't look up the project (HTTP ${res.status}).`);
+    return null;
+  }
+  const data = await res.json().catch(() => null);
+  if (!data?.project) {
+    log.error("Unexpected API response while looking up the project.");
+    return null;
+  }
+  return data.project;
+}
+async function listOwnSlugs(apiUrl, token, log) {
+  try {
+    const res = await fetch(`${apiUrl}/api/projects`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) return;
+    const data = await res.json().catch(() => null);
+    const slugs = (data?.projects ?? []).map((p) => p.slug);
+    if (slugs.length === 0) {
+      log.dim("  You have no projects yet \u2014 `genex init <name>` creates one.");
+      return;
+    }
+    log.dim(`  Your games: ${slugs.map((s) => c.cyan(s)).join(", ")}`);
+  } catch {
+  }
+}
+async function registerDeployKey(apiUrl, token, projectId, deployKey, log) {
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/api/projects/${projectId}/deploy-key`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify({ deployKey })
+    });
+  } catch (err) {
+    log.error(`Couldn't reach the API at ${apiUrl}.`);
+    log.dim(`  ${String(err)}`);
+    return null;
+  }
+  if (res.status === 429) {
+    log.error("Rate limited \u2014 too many link attempts. Try again in a bit.");
+    return null;
+  }
+  if (!res.ok) {
+    log.error(`Couldn't register the deploy key (HTTP ${res.status}).`);
+    return null;
+  }
+  const data = await res.json().catch(() => null);
+  if (!data?.sshUrl) {
+    log.error("Unexpected API response while registering the deploy key.");
+    return null;
+  }
+  return { sshUrl: data.sshUrl };
+}
 
 // src/lib/deploy.ts
 import { spawn as spawn4 } from "child_process";
 import crypto3 from "crypto";
-import fs7 from "fs/promises";
+import fs8 from "fs/promises";
 import os2 from "os";
-import path8 from "path";
+import path9 from "path";
 function run(cmd, args, env) {
   return new Promise((resolve) => {
     let child;
@@ -847,9 +1016,9 @@ async function deployGame(ctx, opts, log) {
     }
     log.success("Built.");
   }
-  const distDir = path8.join(cwd, "dist");
+  const distDir = path9.join(cwd, "dist");
   const siteDir = await isDir2(distDir) ? distDir : cwd;
-  const rel = path8.relative(cwd, siteDir) || ".";
+  const rel = path9.relative(cwd, siteDir) || ".";
   if (siteDir === cwd) await writeGitignore(cwd, log);
   const files = await collectFiles(siteDir);
   if (files.some((f) => /(^|\/)genex_key(\.pub)?$/.test(f.relPath))) {
@@ -888,21 +1057,21 @@ async function deployGame(ctx, opts, log) {
     log.error("Couldn't upload your game \u2014 please try again.");
     return false;
   }
-  const keyPath = path8.resolve(cwd, KEY_NAME);
+  const keyPath = path9.resolve(cwd, KEY_NAME);
   if (!await fileExists(keyPath)) {
     log.error(`No deploy key (${KEY_NAME}) here \u2014 run \`genex init\` in this folder first.`);
     return false;
   }
   if (!await pushSource(cwd, ctx.sshUrl, keyPath, log)) return false;
   log.step("Publishing\u2026");
-  if (!await callPublish(ctx, commit, log)) return false;
+  if (!await callPublish(ctx, commit, opts.matchmaking ?? null, log)) return false;
   const index = files.find((f) => f.relPath === "index.html");
   await waitUntilLive(grant.playUrl, fingerprintOf(index.bytes.toString("utf8")), opts.liveTimeoutMs ?? 2e4, log);
   return true;
 }
 async function hasBuildScript(cwd) {
   try {
-    const pkg = JSON.parse(await fs7.readFile(path8.join(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(await fs8.readFile(path9.join(cwd, "package.json"), "utf8"));
     return Boolean(pkg.scripts?.build);
   } catch {
     return false;
@@ -911,12 +1080,12 @@ async function hasBuildScript(cwd) {
 async function collectFiles(root) {
   const out = [];
   const walk2 = async (dir, prefix) => {
-    for (const e of await fs7.readdir(dir, { withFileTypes: true })) {
+    for (const e of await fs8.readdir(dir, { withFileTypes: true })) {
       const relPath = prefix ? `${prefix}/${e.name}` : e.name;
       if (e.isDirectory()) {
-        if (!EXCLUDE_DIRS.has(e.name)) await walk2(path8.join(dir, e.name), relPath);
+        if (!EXCLUDE_DIRS.has(e.name)) await walk2(path9.join(dir, e.name), relPath);
       } else if (e.isFile() && e.name !== KEY_NAME && e.name !== `${KEY_NAME}.pub`) {
-        out.push({ relPath, bytes: await fs7.readFile(path8.join(dir, e.name)) });
+        out.push({ relPath, bytes: await fs8.readFile(path9.join(dir, e.name)) });
       }
     }
   };
@@ -979,13 +1148,15 @@ async function uploadAll(uploadUrl, uploadToken, files, log) {
   await Promise.all(Array.from({ length: Math.min(8, files.length) }, () => worker()));
   return !failed;
 }
-async function callPublish(ctx, commit, log) {
+async function callPublish(ctx, commit, matchmaking, log) {
   let res;
   try {
     res = await fetch(`${ctx.apiUrl}/api/games/${ctx.projectId}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${ctx.token}` },
-      body: JSON.stringify({ commit })
+      // matchmaking rides every go-live (preview AND publish): object = upsert,
+      // null = clear — so a draft's declared preset reaches the relay immediately.
+      body: JSON.stringify({ commit, matchmaking: matchmaking ?? null })
     });
   } catch (err) {
     log.error(`Couldn't reach the API at ${ctx.apiUrl}: ${String(err)}`);
@@ -1004,7 +1175,7 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
   };
-  const gitDir = await fs7.mkdtemp(path8.join(os2.tmpdir(), "genex-source-"));
+  const gitDir = await fs8.mkdtemp(path9.join(os2.tmpdir(), "genex-source-"));
   const base = { GIT_DIR: gitDir };
   const ident = {
     GIT_AUTHOR_NAME: "genex",
@@ -1014,11 +1185,11 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
   };
   try {
     if ((await run("git", ["init", "-q"], base)).code !== 0) return failed();
-    await fs7.writeFile(
-      path8.join(gitDir, "info", "exclude"),
+    await fs8.writeFile(
+      path9.join(gitDir, "info", "exclude"),
       ["node_modules/", "dist/", ".git/", KEY_NAME, `${KEY_NAME}.pub`, ".genex/", ""].join("\n")
     );
-    const env = { ...base, GIT_WORK_TREE: cwd, GIT_INDEX_FILE: path8.join(gitDir, "index-source") };
+    const env = { ...base, GIT_WORK_TREE: cwd, GIT_INDEX_FILE: path9.join(gitDir, "index-source") };
     await run("git", ["add", "-A"], env);
     const tracked = await run("git", ["ls-files"], env);
     if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) {
@@ -1042,20 +1213,20 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
   } catch {
     return failed();
   } finally {
-    await fs7.rm(gitDir, { recursive: true, force: true }).catch(() => {
+    await fs8.rm(gitDir, { recursive: true, force: true }).catch(() => {
     });
   }
 }
 async function isDir2(p) {
   try {
-    return (await fs7.stat(p)).isDirectory();
+    return (await fs8.stat(p)).isDirectory();
   } catch {
     return false;
   }
 }
 async function fileExists(p) {
   try {
-    await fs7.access(p);
+    await fs8.access(p);
     return true;
   } catch {
     return false;
@@ -1088,10 +1259,12 @@ async function waitUntilLive(playUrl, fingerprint, timeoutMs, log) {
   log.dim("  (If the previous build shows, hard-refresh in a few seconds.)");
 }
 
-// src/commands/publish.ts
+// src/lib/detect-features.ts
+import fs9 from "fs/promises";
+import path10 from "path";
 async function detectEmbedSdkVersion(cwd = process.cwd()) {
   try {
-    const raw = await fs8.readFile(path9.join(cwd, "package.json"), "utf8");
+    const raw = await fs9.readFile(path10.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(raw);
     const version = pkg.dependencies?.["@genex-ai/embed-sdk"] ?? pkg.devDependencies?.["@genex-ai/embed-sdk"];
     return typeof version === "string" && version ? version : null;
@@ -1101,7 +1274,7 @@ async function detectEmbedSdkVersion(cwd = process.cwd()) {
 }
 async function detectMultiplayer(cwd = process.cwd()) {
   try {
-    const raw = await fs8.readFile(path9.join(cwd, "package.json"), "utf8");
+    const raw = await fs9.readFile(path10.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(raw);
     return Boolean(
       pkg.dependencies?.["@genex-ai/multiplayer"] ?? pkg.devDependencies?.["@genex-ai/multiplayer"]
@@ -1113,7 +1286,7 @@ async function detectMultiplayer(cwd = process.cwd()) {
 async function detectMatchmaking(log, cwd = process.cwd()) {
   let pkg;
   try {
-    pkg = JSON.parse(await fs8.readFile(path9.join(cwd, "package.json"), "utf8"));
+    pkg = JSON.parse(await fs9.readFile(path10.join(cwd, "package.json"), "utf8"));
   } catch (err) {
     log.dim(`  (skipping matchmaking \u2014 couldn't read package.json: ${String(err)})`);
     return null;
@@ -1128,6 +1301,53 @@ async function detectMatchmaking(log, cwd = process.cwd()) {
   }
   return null;
 }
+var GAME_STATE_CALLS = /savePlayerState|saveWorldState|submitScore/;
+async function detectGameStateUsage(cwd = process.cwd()) {
+  const srcDir = path10.join(cwd, "src");
+  let entries;
+  try {
+    entries = await fs9.readdir(srcDir, { recursive: true });
+  } catch {
+    return false;
+  }
+  for (const rel of entries) {
+    if (rel.includes("node_modules")) continue;
+    if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(rel)) continue;
+    try {
+      const content = await fs9.readFile(path10.join(srcDir, rel), "utf8");
+      if (GAME_STATE_CALLS.test(content)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+async function detectFeatures(log, cwd = process.cwd()) {
+  return {
+    embedSdkVersion: await detectEmbedSdkVersion(cwd),
+    multiplayer: await detectMultiplayer(cwd),
+    matchmaking: await detectMatchmaking(log, cwd),
+    gameStateUsed: await detectGameStateUsage(cwd)
+  };
+}
+function advisoryNudges(log, d) {
+  if (!d.embedSdkVersion) {
+    log.warn(
+      "This game has no player identity or saves \u2014 players lose everything on refresh. The genex-threejs-embed-auth skill wires it with one call (initEmbed) \u2014 load it before publishing."
+    );
+  }
+  if (d.multiplayer && !d.embedSdkVersion) {
+    log.warn(
+      "Multiplayer will NOT work: @genex-ai/multiplayer needs the embed-sdk token (getColyseusAuth) \u2014 the relay rejects tokenless joins. Wire genex-threejs-embed-auth first."
+    );
+  }
+  if (d.matchmaking && !d.multiplayer) {
+    log.warn(
+      "package.json declares genex.matchmaking but @genex-ai/multiplayer is not installed \u2014 matchmaking cannot work. Install the SDK and use matchmake() (see genex-threejs-multiplayer)."
+    );
+  }
+}
+
+// src/commands/publish.ts
 async function runPublish(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex publish"));
@@ -1145,10 +1365,12 @@ async function runPublish(opts) {
     return;
   }
   const apiUrl = getApiUrl(opts.apiUrl ?? meta.apiUrl);
+  const detections = await detectFeatures(log);
+  advisoryNudges(log, detections);
   if (!opts.noPush) {
     const ok = await deployGame(
       { projectId: meta.id, sshUrl: meta.sshUrl, apiUrl, token },
-      { noBuild: opts.noBuild },
+      { noBuild: opts.noBuild, matchmaking: detections.matchmaking },
       log
     );
     if (!ok) {
@@ -1166,11 +1388,10 @@ async function runPublish(opts) {
     if (opts.description) body.description = opts.description;
     if (opts.regenerateCover) body.regenerateCover = true;
     if (opts.categories?.length) body.categories = opts.categories;
-    const embedSdkVersion = await detectEmbedSdkVersion();
-    if (embedSdkVersion) body.embedSdkVersion = embedSdkVersion;
-    body.multiplayer = await detectMultiplayer();
-    const matchmaking = await detectMatchmaking(log);
-    if (matchmaking) body.matchmaking = matchmaking;
+    if (detections.embedSdkVersion) body.embedSdkVersion = detections.embedSdkVersion;
+    body.multiplayer = detections.multiplayer;
+    body.matchmaking = detections.matchmaking ?? null;
+    body.gameStateUsed = detections.gameStateUsed;
     res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
@@ -1208,10 +1429,14 @@ async function runPreview(opts) {
     process.exitCode = 1;
     return;
   }
+  const detections = await detectFeatures(log);
+  advisoryNudges(log, detections);
   const apiUrl = getApiUrl(meta.apiUrl);
   const ok = await deployGame(
     { projectId: meta.id, sshUrl: meta.sshUrl, apiUrl, token },
-    { noBuild: opts.noBuild },
+    // matchmaking reaches the server on every preview too — a draft with a declared
+    // preset must not silently run the default one (null clears a removed config).
+    { noBuild: opts.noBuild, matchmaking: detections.matchmaking },
     log
   );
   if (!ok) {
@@ -1223,11 +1448,11 @@ async function runPreview(opts) {
 }
 
 // src/commands/generate.ts
-import path11 from "path";
+import path12 from "path";
 
 // src/lib/assets.ts
-import fs9 from "fs/promises";
-import path10 from "path";
+import fs10 from "fs/promises";
+import path11 from "path";
 function slugify(input) {
   const s = input.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 50).replace(/-+$/g, "");
   return s || "asset";
@@ -1236,8 +1461,8 @@ async function downloadToFile(url, dest, headers) {
   const res = await fetch(url, { headers });
   if (!res.ok) throw new Error(`download failed (HTTP ${res.status}) for ${url}`);
   const buf = Buffer.from(await res.arrayBuffer());
-  await fs9.mkdir(path10.dirname(dest), { recursive: true });
-  await fs9.writeFile(dest, buf);
+  await fs10.mkdir(path11.dirname(dest), { recursive: true });
+  await fs10.writeFile(dest, buf);
   return buf.byteLength;
 }
 
@@ -1369,7 +1594,7 @@ async function runGenerate(kind, opts) {
     for (const f of view.files ?? []) {
       const rel = fileDest(kind, slug, f);
       const url = `${apiUrl}/api/generations/${id}/asset/${f.role}`;
-      const bytes = await downloadToFile(url, path11.join(process.cwd(), rel), {
+      const bytes = await downloadToFile(url, path12.join(process.cwd(), rel), {
         Authorization: `Bearer ${token}`
       });
       written.push(rel);
@@ -1475,8 +1700,8 @@ function printHint(kind, written, log) {
 }
 
 // src/commands/controller.ts
-import fs10 from "fs/promises";
-import path12 from "path";
+import fs11 from "fs/promises";
+import path13 from "path";
 var CONTROLLER_KINDS = ["character", "car", "drone"];
 var SHARED = [
   "shared/math.ts",
@@ -1555,8 +1780,8 @@ var CONTROLLER_FILE_SETS = {
     ]
   }
 };
-var CODE_DEST = path12.join("src", "controllers");
-var ASSETS_DEST = path12.join("public", "assets");
+var CODE_DEST = path13.join("src", "controllers");
+var ASSETS_DEST = path13.join("public", "assets");
 async function runController(opts) {
   const log = createLogger({ quiet: opts.quiet });
   const kind = opts.kind?.trim();
@@ -1569,31 +1794,31 @@ async function runController(opts) {
     process.exitCode = 1;
     return;
   }
-  const srcDir = path12.join(getTemplatesDir(), "controllers");
+  const srcDir = path13.join(getTemplatesDir(), "controllers");
   const root = opts.cwd ?? process.cwd();
   const set = CONTROLLER_FILE_SETS[kind];
   log.plain(c.bold(`genex controller ${kind}`));
   log.plain("");
-  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path12.sep)}`);
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path13.sep)}`);
   const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path12.join(CODE_DEST, rel) })),
+    ...set.code.map((rel) => ({ from: rel, rel: path13.join(CODE_DEST, rel) })),
     ...set.assets.map((rel) => ({
       from: rel,
-      rel: path12.join(ASSETS_DEST, path12.basename(rel))
+      rel: path13.join(ASSETS_DEST, path13.basename(rel))
     }))
   ];
   let copied = 0;
   let skipped = 0;
   try {
     for (const file of plan) {
-      const dest = path12.join(root, file.rel);
+      const dest = path13.join(root, file.rel);
       if (!opts.force && await exists2(dest)) {
         skipped++;
         log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
         continue;
       }
-      await fs10.mkdir(path12.dirname(dest), { recursive: true });
-      await fs10.copyFile(path12.join(srcDir, file.from), dest);
+      await fs11.mkdir(path13.dirname(dest), { recursive: true });
+      await fs11.copyFile(path13.join(srcDir, file.from), dest);
       copied++;
       log.dim(`  ${file.rel}`);
     }
@@ -1625,8 +1850,8 @@ async function runController(opts) {
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path12.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs10.mkdir(path12.dirname(dest), { recursive: true });
+  const dest = path13.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs11.mkdir(path13.dirname(dest), { recursive: true });
   if (token) {
     try {
       const res = await fetch(`${apiUrl}/api/avatars/me`, {
@@ -1638,7 +1863,7 @@ async function installOwnerAvatar(args) {
           const vrmRes = await fetch(me.vrmUrl);
           if (vrmRes.ok) {
             const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs10.writeFile(dest, buf);
+            await fs11.writeFile(dest, buf);
             log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
             return;
           }
@@ -1649,14 +1874,14 @@ async function installOwnerAvatar(args) {
       log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  await fs10.copyFile(path12.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  await fs11.copyFile(path13.join(srcDir, "assets", "default-avatar.vrm"), dest);
   log.dim(
     token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
   );
 }
 async function exists2(p) {
   try {
-    await fs10.access(p);
+    await fs11.access(p);
     return true;
   } catch {
     return false;
@@ -1667,9 +1892,9 @@ async function exists2(p) {
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
 function getVersion() {
   try {
-    const here = path13.dirname(fileURLToPath2(import.meta.url));
+    const here = path14.dirname(fileURLToPath2(import.meta.url));
     const pkg = JSON.parse(
-      readFileSync(path13.resolve(here, "..", "package.json"), "utf8")
+      readFileSync(path14.resolve(here, "..", "package.json"), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1680,6 +1905,9 @@ var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize
 
 ${c.bold("Usage")}
   genex init [<name>] [options]      Scaffold + authorize + create the draft project.
+  genex link <slug> [options]        Re-link THIS folder to an existing game of yours
+                                     (lost folder / new machine); preview/publish then
+                                     update the same live game. Never creates a project.
   genex preview [options]            Build + push to the hosted draft URL (unlisted).
   genex publish [options]            Build + push, then list the game in the gallery.
   genex model "<prompt>" [options]   Generate a 3D model (GLB) into public/assets/models.
@@ -1709,6 +1937,15 @@ ${c.bold("Options for `init`")}
   --force              Overwrite existing files (default: never overwrite).
   --timeout <seconds>  How long to wait for the auth redirect (default: 300).
 
+${c.bold("Options for `link`")}
+  <slug>               The game to reconnect to (the name in your play URL). Required.
+  --force              Re-link a folder already linked to a DIFFERENT game.
+  --env <path>         Token env file (default: ~/.genex/env).
+  --auth-url <url>     Override the auth site (used only if sign-in is needed).
+  --api-url <url>      Override the API base URL.
+  --colyseus-url <url> Override the multiplayer URL (stored in project metadata).
+  --timeout <seconds>  How long to wait for the auth redirect (default: 300).
+
 ${c.bold("Options for `preview` / `publish`")}
   --no-build           Skip the build step; deploy whatever is already built.
   --no-push            (publish) Skip build + push; only flip the gallery flag.
@@ -1734,6 +1971,7 @@ ${c.bold("Environment")}
 ${c.bold("Examples")}
   genex init my-game
   genex init my-game --api-url http://localhost:3000 --auth-url http://localhost:5173
+  genex link my-game
   genex preview
   genex publish
   genex publish --categories games,vfx
@@ -1912,6 +2150,9 @@ async function main() {
     case "init":
       await runInit(parsed.options);
       break;
+    case "link":
+      await runLink(parsed.options);
+      break;
     case "controller":
       await runController({ ...parsed.options, kind: parsed.options.name });
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {