@bakapiano/ccsm 0.13.0 → 0.15.0

package/scripts/install.js

@@ -1,137 +1,158 @@
-#!/usr/bin/env node
-'use strict';
-
-// ccsm postinstall · Windows-only · runs after `npm install -g @bakapiano/ccsm`.
-// Registers the `ccsm://` URL protocol in HKCU so the hosted frontend
-// (https://bakapiano.github.io/ccsm/v1/) can fire `<a href="ccsm://start">`
-// from its OfflineBanner and have Windows spawn the backend on demand.
-//
-// Best-effort: any failure MUST NOT break npm install. Each step is in
-// its own try/catch; we just log and move on.
-//
-// No .lnk file, no Start Menu shortcut — just the protocol handler.
-
-const path = require('node:path');
-const fs = require('node:fs');
-const { spawnSync } = require('node:child_process');
-
-function log(msg)  { process.stdout.write(`[ccsm install] ${msg}\n`); }
-function warn(msg) { process.stderr.write(`[ccsm install] ${msg}\n`); }
-
-if (process.platform !== 'win32') {
-  log('non-Windows · skipping ccsm:// registration');
-  process.exit(0);
-}
-// Note: we DO register on npx-cache installs too (not just global). The
-// npx cache path is stable across re-runs of the same package, and even
-// if the user later cleans the cache, the only consequence is the
-// OfflineBanner button no-ops — nothing actively broken. Registering
-// always means a first-time `npx @bakapiano/ccsm` gets the full "click
-// to wake" UX without needing a separate `npm i -g`.
-
-function findCcsmCmd() {
-  const prefix = process.env.npm_config_prefix
-    || (() => {
-      try {
-        const r = spawnSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8', shell: true });
-        return r.stdout?.trim() || null;
-      } catch { return null; }
-    })();
-  if (!prefix) return null;
-  const candidate = path.join(prefix, 'ccsm.cmd');
-  return fs.existsSync(candidate) ? candidate : null;
-}
-
-// Write a tiny VBScript wrapper that ccsm:// dispatches into. Why VBS:
-// wscript.exe is a Windows-subsystem host (no console window), and
-// `Shell.Run(..., 0, False)` launches the target completely hidden — so
-// when the user clicks ccsm://start, NOTHING flashes on screen, the
-// backend just appears in the next health probe.
-function writeLauncherVbs(ccsmCmd) {
-  const home = process.env.LOCALAPPDATA || process.env.APPDATA;
-  if (!home) throw new Error('no LOCALAPPDATA/APPDATA env var');
-  const dir = path.join(home, 'ccsm');
-  fs.mkdirSync(dir, { recursive: true });
-  const vbsPath = path.join(dir, 'launcher.vbs');
-  // Escape any double-quotes in the cmd path (rare but possible).
-  const cmdEsc = ccsmCmd.replace(/"/g, '""');
-  const vbs = [
-    "' ccsm protocol launcher · invoked by wscript.exe via the registered",
-    "' ccsm:// URL handler. Spawns ccsm.cmd with WindowStyle 0 (hidden) +",
-    "' bWaitOnReturn=False (async), so the click leaves zero visible trace.",
-    'If WScript.Arguments.Count >= 1 Then',
-    '  arg = WScript.Arguments(0)',
-    'Else',
-    '  arg = ""',
-    'End If',
-    'Set sh = CreateObject("WScript.Shell")',
-    `sh.Run """${cmdEsc}"" """ & arg & """", 0, False`,
-    '',
-  ].join('\r\n');
-  fs.writeFileSync(vbsPath, vbs, { encoding: 'utf8' });
-  return vbsPath;
-}
-
-function registerProtocol(vbsPath) {
-  // wscript.exe is a no-console host. The protocol-registered command
-  // hands the entire ccsm:// URL to launcher.vbs as argv[0]; the VBS
-  // forwards it to ccsm.cmd "%1" with a hidden window.
-  const command = `wscript.exe "${vbsPath}" "%1"`;
-  const root = 'HKCU\\Software\\Classes\\ccsm';
-  const calls = [
-    ['add', root, '/ve', '/d', 'URL:ccsm protocol', '/f'],
-    ['add', root, '/v', 'URL Protocol', '/d', '', '/f'],
-    ['add', `${root}\\shell\\open\\command`, '/ve', '/d', command, '/f'],
-  ];
-  for (const args of calls) {
-    const r = spawnSync('reg.exe', args, { windowsHide: true });
-    if (r.status !== 0) {
-      throw new Error(`reg ${args.join(' ')} → exit ${r.status}: ${r.stderr?.toString() || ''}`);
-    }
-  }
-}
-
-const ccsmCmd = (() => {
-  try { return findCcsmCmd(); } catch { return null; }
-})();
-if (!ccsmCmd) {
-  warn('could not locate ccsm.cmd · skipping protocol registration');
-  process.exit(0);
-}
-
-try {
-  const vbsPath = writeLauncherVbs(ccsmCmd);
-  registerProtocol(vbsPath);
-  log(`launcher · ${vbsPath}`);
-  log(`ccsm:// protocol registered (silent · via wscript.exe)`);
-} catch (e) {
-  warn(`failed · ${e.message}`);
-  warn('the hosted frontend\'s "Start ccsm" button will not be able to launch the backend. You can still run `ccsm` manually in a terminal.');
-}
-
-// Auto-launch ccsm after install so the user lands directly in the app
-// without needing a second command. Detached + windowsHide so the npm
-// install command returns immediately. Skip if CCSM_NO_AUTOLAUNCH=1 is
-// set (CI, headless setups).
-if (process.env.CCSM_NO_AUTOLAUNCH !== '1') {
-  try {
-    const { spawn } = require('node:child_process');
-    // Spawn `node bin/ccsm.js` directly — NOT ccsm.cmd. On Windows,
-    // child_process.spawn() with shell:false refuses .cmd files (throws
-    // EINVAL); using shell:true would flash a console window. Going
-    // through node + the JS entrypoint sidesteps both problems and
-    // matches exactly what the .cmd shim would have invoked.
-    const launcherJs = path.join(__dirname, '..', 'bin', 'ccsm.js');
-    const child = spawn(process.execPath, [launcherJs], {
-      detached: true,
-      stdio: 'ignore',
-      windowsHide: true,
-    });
-    child.unref();
-    log('launching ccsm now · check for the chromeless window');
-    log('(set CCSM_NO_AUTOLAUNCH=1 to skip this on future installs)');
-  } catch (e) {
-    warn(`auto-launch failed · ${e.message}`);
-    warn('run `ccsm` manually to start.');
-  }
-}
+#!/usr/bin/env node
+'use strict';
+
+// ccsm postinstall · Windows-only · runs after `npm install -g @bakapiano/ccsm`.
+// Registers the `ccsm://` URL protocol in HKCU so the hosted frontend
+// (https://bakapiano.github.io/ccsm/v1/) can fire `<a href="ccsm://start">`
+// from its OfflineBanner and have Windows spawn the backend on demand.
+//
+// Best-effort: any failure MUST NOT break npm install. Each step is in
+// its own try/catch; we just log and move on.
+//
+// No .lnk file, no Start Menu shortcut — just the protocol handler.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+function log(msg)  { process.stdout.write(`[ccsm install] ${msg}\n`); }
+function warn(msg) { process.stderr.write(`[ccsm install] ${msg}\n`); }
+
+if (process.platform !== 'win32') {
+  log('non-Windows · skipping ccsm:// registration');
+  process.exit(0);
+}
+// Note: we DO register on npx-cache installs too (not just global). The
+// npx cache path is stable across re-runs of the same package, and even
+// if the user later cleans the cache, the only consequence is the
+// OfflineBanner button no-ops — nothing actively broken. Registering
+// always means a first-time `npx @bakapiano/ccsm` gets the full "click
+// to wake" UX without needing a separate `npm i -g`.
+
+// Returns { ccsmCmd, isSandbox } where isSandbox=true means this install
+// went into a non-default prefix (e.g. `npm i -g --prefix=<tmp>` from
+// the in-app upgrade's test mode). For sandboxed installs we DO NOT
+// touch the global launcher.vbs / ccsm:// protocol registration —
+// otherwise we'd repoint them at a directory that gets deleted later.
+function findCcsmCmd() {
+  const givenPrefix = process.env.npm_config_prefix || null;
+  let defaultPrefix = null;
+  try {
+    // npm config get prefix when run WITHOUT --prefix returns the
+    // user's default global prefix; with --prefix it echoes the flag.
+    // We want the env-independent default so we can compare. INIT_CWD
+    // and a clean spawn give us the user-default value.
+    const r = spawnSync('npm', ['config', 'get', 'prefix'], {
+      encoding: 'utf8', shell: true,
+      env: { ...process.env, npm_config_prefix: '' },
+    });
+    defaultPrefix = r.stdout?.trim() || null;
+  } catch {}
+  const prefix = givenPrefix || defaultPrefix;
+  if (!prefix) return { ccsmCmd: null, isSandbox: false };
+  const candidate = path.join(prefix, 'ccsm.cmd');
+  const isSandbox = !!(givenPrefix && defaultPrefix
+    && path.resolve(givenPrefix).toLowerCase() !== path.resolve(defaultPrefix).toLowerCase());
+  return {
+    ccsmCmd: fs.existsSync(candidate) ? candidate : null,
+    isSandbox,
+  };
+}
+
+// Write a tiny VBScript wrapper that ccsm:// dispatches into. Why VBS:
+// wscript.exe is a Windows-subsystem host (no console window), and
+// `Shell.Run(..., 0, False)` launches the target completely hidden — so
+// when the user clicks ccsm://start, NOTHING flashes on screen, the
+// backend just appears in the next health probe.
+function writeLauncherVbs(ccsmCmd) {
+  const home = process.env.LOCALAPPDATA || process.env.APPDATA;
+  if (!home) throw new Error('no LOCALAPPDATA/APPDATA env var');
+  const dir = path.join(home, 'ccsm');
+  fs.mkdirSync(dir, { recursive: true });
+  const vbsPath = path.join(dir, 'launcher.vbs');
+  // Escape any double-quotes in the cmd path (rare but possible).
+  const cmdEsc = ccsmCmd.replace(/"/g, '""');
+  const vbs = [
+    "' ccsm protocol launcher · invoked by wscript.exe via the registered",
+    "' ccsm:// URL handler. Spawns ccsm.cmd with WindowStyle 0 (hidden) +",
+    "' bWaitOnReturn=False (async), so the click leaves zero visible trace.",
+    'If WScript.Arguments.Count >= 1 Then',
+    '  arg = WScript.Arguments(0)',
+    'Else',
+    '  arg = ""',
+    'End If',
+    'Set sh = CreateObject("WScript.Shell")',
+    `sh.Run """${cmdEsc}"" """ & arg & """", 0, False`,
+    '',
+  ].join('\r\n');
+  fs.writeFileSync(vbsPath, vbs, { encoding: 'utf8' });
+  return vbsPath;
+}
+
+function registerProtocol(vbsPath) {
+  // wscript.exe is a no-console host. The protocol-registered command
+  // hands the entire ccsm:// URL to launcher.vbs as argv[0]; the VBS
+  // forwards it to ccsm.cmd "%1" with a hidden window.
+  const command = `wscript.exe "${vbsPath}" "%1"`;
+  const root = 'HKCU\\Software\\Classes\\ccsm';
+  const calls = [
+    ['add', root, '/ve', '/d', 'URL:ccsm protocol', '/f'],
+    ['add', root, '/v', 'URL Protocol', '/d', '', '/f'],
+    ['add', `${root}\\shell\\open\\command`, '/ve', '/d', command, '/f'],
+  ];
+  for (const args of calls) {
+    const r = spawnSync('reg.exe', args, { windowsHide: true });
+    if (r.status !== 0) {
+      throw new Error(`reg ${args.join(' ')} → exit ${r.status}: ${r.stderr?.toString() || ''}`);
+    }
+  }
+}
+
+const { ccsmCmd, isSandbox } = (() => {
+  try { return findCcsmCmd(); } catch { return { ccsmCmd: null, isSandbox: false }; }
+})();
+if (!ccsmCmd) {
+  warn('could not locate ccsm.cmd · skipping protocol registration');
+  process.exit(0);
+}
+if (isSandbox) {
+  log(`sandbox install detected (prefix=${process.env.npm_config_prefix}) · skipping global launcher.vbs + protocol registration + auto-launch`);
+  process.exit(0);
+}
+
+try {
+  const vbsPath = writeLauncherVbs(ccsmCmd);
+  registerProtocol(vbsPath);
+  log(`launcher · ${vbsPath}`);
+  log(`ccsm:// protocol registered (silent · via wscript.exe)`);
+} catch (e) {
+  warn(`failed · ${e.message}`);
+  warn('the hosted frontend\'s "Start ccsm" button will not be able to launch the backend. You can still run `ccsm` manually in a terminal.');
+}
+
+// Auto-launch ccsm after install so the user lands directly in the app
+// without needing a second command. Detached + windowsHide so the npm
+// install command returns immediately. Skip if CCSM_NO_AUTOLAUNCH=1 is
+// set (CI, headless setups).
+if (process.env.CCSM_NO_AUTOLAUNCH !== '1') {
+  try {
+    const { spawn } = require('node:child_process');
+    // Spawn `node bin/ccsm.js` directly — NOT ccsm.cmd. On Windows,
+    // child_process.spawn() with shell:false refuses .cmd files (throws
+    // EINVAL); using shell:true would flash a console window. Going
+    // through node + the JS entrypoint sidesteps both problems and
+    // matches exactly what the .cmd shim would have invoked.
+    const launcherJs = path.join(__dirname, '..', 'bin', 'ccsm.js');
+    const child = spawn(process.execPath, [launcherJs], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+    log('launching ccsm now · check for the chromeless window');
+    log('(set CCSM_NO_AUTOLAUNCH=1 to skip this on future installs)');
+  } catch (e) {
+    warn(`auto-launch failed · ${e.message}`);
+    warn('run `ccsm` manually to start.');
+  }
+}

package/scripts/restart-helper.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+
+// Restart helper · spawned detached by /api/restart.
+//
+// Just like upgrade-helper but skips the `npm i` step. Server kicks
+// this off + gracefulShutdowns; helper waits for the port to free, then
+// respawns ccsm (which finds no live backend and starts a fresh one).
+//
+// Argv: node restart-helper.js <port> <pid>
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const net = require('node:net');
+const { spawn } = require('node:child_process');
+
+const oldPort = Number(process.argv[2] || 7777);
+const oldPid = Number(process.argv[3] || 0);
+
+const HOME = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
+const LOG = path.join(HOME, 'restart.log');
+try { fs.mkdirSync(HOME, { recursive: true }); } catch {}
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}\n`;
+  try { fs.appendFileSync(LOG, line); } catch {}
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+function portFree(port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const s = new net.Socket();
+    let settled = false;
+    const finish = (free) => { if (settled) return; settled = true; try { s.destroy(); } catch {} resolve(free); };
+    s.setTimeout(timeoutMs);
+    s.once('connect', () => finish(false));
+    s.once('timeout', () => finish(true));
+    s.once('error', () => finish(true));
+    s.connect(port, '127.0.0.1');
+  });
+}
+
+function pidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; }
+}
+
+(async () => {
+  log(`start · oldPort=${oldPort} oldPid=${oldPid}`);
+
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const free = await portFree(oldPort);
+    const dead = !pidAlive(oldPid);
+    if (free && dead) break;
+    await sleep(250);
+  }
+  log(`old server gone (or 30s elapsed) · respawning`);
+
+  const isWin = process.platform === 'win32';
+  const ccsmCmd = isWin ? 'ccsm.cmd' : 'ccsm';
+  const childEnv = { ...process.env, CCSM_NO_BROWSER: '1' };
+  let exe, exeArgs;
+  if (isWin) {
+    exe = process.env.ComSpec || 'cmd.exe';
+    exeArgs = ['/d', '/s', '/c', ccsmCmd];
+  } else {
+    exe = ccsmCmd;
+    exeArgs = [];
+  }
+  try {
+    const child = spawn(exe, exeArgs, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      shell: false,
+      env: childEnv,
+    });
+    child.unref();
+    log(`respawned ${ccsmCmd} (via ${path.basename(exe)})`);
+  } catch (e) {
+    log(`respawn failed: ${e.message}`);
+    process.exit(1);
+  }
+})().catch((e) => {
+  log(`fatal: ${e.message}`);
+  process.exit(1);
+});

package/scripts/upgrade-helper.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+'use strict';
+
+// In-app upgrade helper · spawned detached by /api/upgrade.
+//
+// The previous implementation kicked off `npm i -g` directly from the
+// running server. On Windows that fails with EBUSY: npm tries to rename
+// the package directory but the server has files open inside it.
+//
+// This script breaks the cycle:
+//
+//   1. Server validates the upgrade request, spawns this helper detached
+//      with [target, port, pid] argv, sends 200 OK, then gracefulShutdowns.
+//   2. Helper waits for the old port to free up + the old pid to die.
+//   3. Helper runs `npm i -g @bakapiano/ccsm@<target>` synchronously.
+//   4. On success it spawns `ccsm` detached (which spins up the new
+//      backend on the same port) and exits.
+//
+// Logs everything to ~/.ccsm/upgrade.log so a failed upgrade is
+// debuggable without the user needing to re-run the command manually.
+//
+// Argv: node upgrade-helper.js <target> <port> <pid> [installPrefix] [respawn=1|0]
+// - installPrefix: when set, runs `npm i -g --prefix=<this>` so the
+//   global install can be redirected to a sandbox dir for testing
+//   against a live prod install without disturbing it. Respawn then
+//   uses <prefix>/ccsm.cmd (Windows) or <prefix>/bin/ccsm (posix).
+// - respawn: '0' skips the final ccsm respawn (also useful for tests).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const net = require('node:net');
+const { spawn, spawnSync } = require('node:child_process');
+
+const target = process.argv[2] || 'latest';
+const oldPort = Number(process.argv[3] || 7777);
+const oldPid = Number(process.argv[4] || 0);
+const installPrefix = process.argv[5] || '';
+const doRespawn = process.argv[6] !== '0';
+
+const HOME = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
+const LOG = path.join(HOME, 'upgrade.log');
+try { fs.mkdirSync(HOME, { recursive: true }); } catch {}
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}\n`;
+  try { fs.appendFileSync(LOG, line); } catch {}
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+// Returns true once nothing answers on host:port within timeoutMs.
+function portFree(port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const s = new net.Socket();
+    let settled = false;
+    const finish = (free) => { if (settled) return; settled = true; try { s.destroy(); } catch {} resolve(free); };
+    s.setTimeout(timeoutMs);
+    s.once('connect', () => finish(false));
+    s.once('timeout', () => finish(true));
+    s.once('error', () => finish(true));
+    s.connect(port, '127.0.0.1');
+  });
+}
+
+function pidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; }
+}
+
+(async () => {
+  log(`start · target=${target} oldPort=${oldPort} oldPid=${oldPid}${installPrefix ? ` prefix=${installPrefix}` : ''}${!doRespawn ? ' (no respawn)' : ''}`);
+
+  // Wait up to 30s for the old server to be gone. Both port-free AND
+  // pid-dead so we don't fight npm's rename for a stale file handle.
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const free = await portFree(oldPort);
+    const dead = !pidAlive(oldPid);
+    if (free && dead) break;
+    await sleep(250);
+  }
+  log(`old server gone (or 30s elapsed) · running npm install`);
+
+  // npm.cmd is a batch wrapper on Windows; spawn it via cmd.exe /c so
+  // we don't need shell:true (which would mean argv quoting). target
+  // has already been regex-validated server-side so this is safe.
+  const isWin = process.platform === 'win32';
+  const arg = `@bakapiano/ccsm@${target}`;
+  const npmArgs = ['i', '-g'];
+  if (installPrefix) {
+    try { fs.mkdirSync(installPrefix, { recursive: true }); } catch {}
+    npmArgs.push(`--prefix=${installPrefix}`);
+  }
+  npmArgs.push(arg);
+  let r;
+  if (isWin) {
+    r = spawnSync(process.env.ComSpec || 'cmd.exe',
+      ['/d', '/s', '/c', 'npm', ...npmArgs],
+      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  } else {
+    r = spawnSync('npm', npmArgs,
+      { stdio: ['ignore', 'pipe', 'pipe'] });
+  }
+  const stdout = r.stdout?.toString().trim();
+  const stderr = r.stderr?.toString().trim();
+  log(`npm exit=${r.status}${stdout ? `\nSTDOUT:\n${stdout}` : ''}${stderr ? `\nSTDERR:\n${stderr}` : ''}`);
+  if (r.status !== 0) {
+    log(`upgrade failed · not respawning`);
+    process.exit(1);
+  }
+
+  if (!doRespawn) {
+    log(`respawn skipped (respawn=0)`);
+    return;
+  }
+
+  // Respawn ccsm. With installPrefix the binary lives there; otherwise
+  // it's on PATH from the global npm install. The launcher handles
+  // detect-or-spawn-server and detaches.
+  //
+  // On Windows, CreateProcess refuses to spawn .cmd / .bat directly —
+  // they're cmd.exe scripts, not native exes. Route through cmd.exe /c
+  // so it loads the wrapper.
+  const ccsmCmd = installPrefix
+    ? (isWin ? path.join(installPrefix, 'ccsm.cmd') : path.join(installPrefix, 'bin', 'ccsm'))
+    : (isWin ? 'ccsm.cmd' : 'ccsm');
+  const childEnv = { ...process.env, CCSM_NO_BROWSER: '1' };
+  let exe, exeArgs;
+  if (isWin) {
+    exe = process.env.ComSpec || 'cmd.exe';
+    exeArgs = ['/d', '/s', '/c', ccsmCmd];
+  } else {
+    exe = ccsmCmd;
+    exeArgs = [];
+  }
+  try {
+    const child = spawn(exe, exeArgs, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      shell: false,
+      env: childEnv,
+    });
+    child.unref();
+    log(`respawned ${ccsmCmd} (via ${path.basename(exe)})`);
+  } catch (e) {
+    log(`respawn failed: ${e.message}`);
+    process.exit(1);
+  }
+})().catch((e) => {
+  log(`fatal: ${e.message}`);
+  process.exit(1);
+});