@volter/sdk 0.5.208 → 0.5.210

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.208",
+  "version": "0.5.210",
   "publishConfig": {
     "access": "public"
   },
@@ -487,7 +487,7 @@
     "@fortawesome/react-fontawesome": "^3.2.0",
     "@storybook/react": "10.6.0",
     "@types/node": "^22.0.0",
-    "@volter/project": "0.5.208",
+    "@volter/project": "0.5.210",
     "mediabunny": "1.56.2",
     "postcss": "8.5.28",
     "rrweb": "2.1.6",

package/src/kit/product-command.ts

@@ -52,14 +52,36 @@ export function commandLine(verb: string): string {
 }
 
 /**
- * Several verbs run in order, as one line a person can paste:
- * `volter-game-editor close && volter-game-editor edit .`. Before the identity
- * is known: ``the editor's `close`, then `edit .` ``.
+ * The npx a person types on this machine. Windows PowerShell's script policy
+ * refuses the bare `npx` (its `.ps1` shim) where `npx.cmd` runs in every shell
+ * (the 0.5.208 blind walk's returning user).
+ */
+function npx(): string {
+  const windows =
+    typeof navigator !== 'undefined'
+      ? navigator.platform.startsWith('Win')
+      : (globalThis as { process?: { platform?: string } }).process?.platform === 'win32';
+  return windows ? 'npx.cmd' : 'npx';
+}
+
+/**
+ * One verb as a person runs it from the project folder, through the project's
+ * own install: `npx --no-install cyclotron edit .`. The bare command is on no
+ * PATH the install line or npx sets. `null` before the identity is known.
+ */
+export function projectCommandLine(verb: string): string | null {
+  return names ? `${npx()} --no-install ${names.command} ${verb}` : null;
+}
+
+/**
+ * Several verbs run in order from the project folder, one line each so the
+ * paste runs in any shell (`&&` is not Windows PowerShell 5.1's):
+ * `npx --no-install cyclotron close` then `npx --no-install cyclotron edit .`.
+ * Before the identity is known: ``the editor's `close`, then `edit .` ``.
  */
 export function commandSequence(verbs: readonly string[]): string {
-  const known = names;
-  return known
-    ? verbs.map((verb) => `${known.command} ${verb}`).join(' && ')
+  return names
+    ? verbs.map((verb) => projectCommandLine(verb)).join('\n')
     : `the editor's ${verbs.map((verb) => `\`${verb}\``).join(', then ')}`;
 }
 

package/src/kit/startup-failure.ts

@@ -22,7 +22,7 @@
 export interface StartupFailureNotice {
   readonly message: string;
   readonly guidance: string | null;
-  /** The recovery as one pasteable line (`commandSequence`), when it has one. */
+  /** The recovery to paste, one command per line (`commandSequence`), when it has one. */
   readonly command: string | null;
   /**
    * STILL TRYING, not refused: a slow start that may yet succeed (detection that keeps being

package/src/session/project-upgrade.ts

@@ -31,11 +31,13 @@
  * `AGENTS.md`, `CLAUDE.md`), so the project's agent servers and instructions keep working.
  */
 import { spawn } from 'node:child_process';
-import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, statSync } from 'node:fs';
 import { mkdir, readdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { MANIFEST_FILENAME } from '@volter/project/manifest/filename';
 import { hasManifest } from '@volter/project/manifest/locate';
+import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, HttpSessionDiscovery } from './discovery';
+import { readLiveRegisteredSessions } from './registry-format';
 import { compareSemver } from './editor-compatibility';
 
 export const UPGRADE_USAGE = "upgrade [version]    # move this project's @volter packages and its engine pin to one release (default: latest); from a project made before 0.5.203, run the newest release's own: npx <package>@latest upgrade";
@@ -351,10 +353,44 @@ async function readRelease(product: UpgradingProduct, requested: string | undefi
     return await npmView(spec);
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(`Could not read ${spec} from the registry (${reason}). Name a published version: ${product.command} upgrade <version>.`);
+    throw new Error(`Could not read ${spec} from the registry (${reason}). Name a published version: ${projectLine(product.command, 'upgrade <version>')}.`);
   }
 }
 
+/** Whether an editor session is open on `project` now (the same folder on disk, however it was typed).
+ *  The Next lines close one first; with none open, `close` runs the project's OLD install, whose
+ *  refusal before 0.5.210 was a wall about other sessions and exit 1. The registry names each live
+ *  editor's project; a registered editor that did not answer may be this one, and a question nobody
+ *  could answer keeps the close line. */
+async function editorOpenOn(project: string): Promise<boolean> {
+  try {
+    const here = statSync(project, { bigint: true });
+    const isHere = (path: string | null): boolean => {
+      if (path === null) return false;
+      try {
+        const there = statSync(path, { bigint: true });
+        return there.dev === here.dev && there.ino === here.ino;
+      } catch {
+        return false;
+      }
+    };
+    const registered = readLiveRegisteredSessions();
+    if (registered.length === 0) return false;
+    if (registered.some((session) => isHere(session.project))) return true;
+    const answered = await new HttpSessionDiscovery().listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS);
+    // listSessions drops a session whose probe failed, and throws only when none answered.
+    return answered.length < registered.length || answered.some((session) => isHere(session.project));
+  } catch {
+    return true;
+  }
+}
+
+/** A verb as a person runs it from the project folder, through its own install and in any shell (the Next lines
+ *  at the end of `upgradeProject` say why). */
+function projectLine(command: string, verb: string): string {
+  return `${process.platform === 'win32' ? 'npx.cmd' : 'npx'} --no-install ${command} ${verb}`;
+}
+
 export async function upgradeProject(product: UpgradingProduct, requested?: string, cwd = process.cwd()): Promise<void> {
   if (requested !== undefined && !EXACT_VERSION.test(requested))
     throw new Error(`${product.command} upgrade takes an exact version (e.g. 0.5.189), not "${requested}".`);
@@ -401,7 +437,7 @@ export async function upgradeProject(product: UpgradingProduct, requested?: stri
   if (pkg.workspaces !== undefined) {
     const members = Array.isArray(pkg.workspaces) ? pkg.workspaces
       : Array.isArray((pkg.workspaces as { packages?: unknown }).packages) ? (pkg.workspaces as { packages: unknown[] }).packages : [];
-    kept.push(`workspace members${members.length > 0 ? ` (${members.map(String).join(', ')})` : ''} are not upgraded: run ${product.command} upgrade in each member that is a project`);
+    kept.push(`workspace members${members.length > 0 ? ` (${members.map(String).join(', ')})` : ''} are not upgraded: run ${projectLine(product.command, 'upgrade')} in each member that is a project`);
   }
 
   let packagesChanged = false;
@@ -588,7 +624,7 @@ export async function upgradeProject(product: UpgradingProduct, requested?: stri
     if (requested === undefined)
       throw new Error(
         `${product.packageName}@latest is ${release.version} (engine ${engine}), older than the ${backwards} this project is on, so upgrading to it would move the project backwards. ` +
-          `Nothing was changed. To go back on purpose, name the version: ${product.command} upgrade ${release.version}.`,
+          `Nothing was changed. To go back on purpose, name the version: ${projectLine(product.command, `upgrade ${release.version}`)}.`,
       );
     warnings.push(`This moves the project BACKWARDS, from ${backwards} to ${product.packageName}@${release.version} (engine ${engine}), because that version was named.`);
   }
@@ -650,20 +686,30 @@ export async function upgradeProject(product: UpgradingProduct, requested?: stri
   for (const line of changed) console.log(`  + ${line}`);
   if (kept.length > 0) console.log('Left as it was:');
   for (const line of kept) console.log(`  = ${line}`);
+  // Every printed command runs as typed in any shell from the project folder: `&&` is not Windows
+  // PowerShell 5.1's, an inline `#` comment is an argument to cmd, the product's bare command is on
+  // no PATH an install line or npx sets, and PowerShell's script policy refuses a bare `npx`/`npm`
+  // (their `.ps1` shims) where the `.cmd` names run (the 0.5.208 blind walk's returning user).
+  const [npm, npx] = process.platform === 'win32' ? ['npm.cmd', 'npx.cmd'] : ['npm', 'npx'];
   if (changed.length === 0) {
     // NOTHING TO MOVE, YET AN EDITOR REFUSED: then the editor that refused is not this project's
     // own installation (an older global install, another checkout), and saying "already on"
     // alone left the person with no next step (#146 review).
-    console.log(`If an editor still refuses this project, it is running from another installation: open it with this project's own, \`npx --no-install ${product.command} edit .\` in ${project}.`);
+    console.log(`If an editor still refuses this project, it is running from another installation: open it with this project's own, \`${npx} --no-install ${product.command} edit .\` in ${project}.`);
     return;
   }
   if (retired !== null)
-    console.log(`This project now opens in ${product.packageName}. Its command is ${product.command}: from the project folder, \`npx --no-install ${product.command} <command>\`.`);
-  console.log('Next:');
-  if (packagesChanged && !linked) console.log(`  npm install    # in ${project}; installs the versions above`);
+    console.log(`This project now opens in ${product.packageName}. Its command is ${product.command}: from the project folder, \`${npx} --no-install ${product.command} <command>\`.`);
+  console.log(`Next, in ${project}, one line at a time:`);
   // A running session keeps the editor it started with: new packages need a new session, while a
-  // pin that moved alone is read again by the page's Retry.
-  console.log(packagesChanged
-    ? `  ${product.command} close && ${product.command} edit .    # restart the session on the new install`
-    : `  Press Retry on the editor page that refused the project, or run ${product.command} edit .`);
+  // pin that moved alone is read again by the page's Retry. The old session is closed before
+  // `npm install` replaces the packages under it, and by the command it was started with.
+  if (packagesChanged) {
+    if (await editorOpenOn(project))
+      console.log(`  ${npx} --no-install ${linked ? product.command : retired?.command ?? product.command} close`);
+    if (!linked) console.log(`  ${npm} install`);
+    console.log(`  ${npx} --no-install ${product.command} edit .`);
+  } else {
+    console.log(`  Press Retry on the editor page that refused the project, or run: ${npx} --no-install ${product.command} edit .`);
+  }
 }