@bakapiano/ccsm 0.22.2 → 0.22.4

package/scripts/dev.js

@@ -1,149 +1,149 @@
-#!/usr/bin/env node
-'use strict';
-
-// Dev launcher · fully isolates from the user's prod ccsm install.
-//
-// Why: many contributors run the published `@bakapiano/ccsm` package
-// for their day-to-day work (port 7777, ~/.ccsm). If `npm run dev`
-// reused the same data dir + port, every hot-reload would clobber the
-// live sessions.json. So dev gets its own:
-//
-//   - CCSM_HOME   → ~/.ccsm-dev/   (separate config.json, sessions.json, folders.json)
-//   - port        → 7788           (no contention with prod 7777)
-//   - workDir     → ~/ccsm-workspaces-dev (separate workspace tree)
-//   - no browser auto-open (we're iterating in an already-open tab)
-//
-// Run via `npm run dev`. The first launch seeds a starter config; later
-// launches leave it alone so dev's own customisations stick.
-
-const path = require('node:path');
-const os = require('node:os');
-const fs = require('node:fs');
-const { spawn } = require('node:child_process');
-
-const DEV_HOME = path.join(os.homedir(), '.ccsm-dev');
-const DEV_PORT = '7788';
-const DEV_WORKDIR = path.join(os.homedir(), 'ccsm-workspaces-dev');
-
-fs.mkdirSync(DEV_HOME, { recursive: true });
-
-// Seed a fresh dev config the first time. Subsequent runs leave the
-// existing file alone — the dev's own UI edits persist across restarts.
-const configPath = path.join(DEV_HOME, 'config.json');
-if (!fs.existsSync(configPath)) {
-  fs.writeFileSync(configPath, JSON.stringify({
-    port: Number(DEV_PORT),
-    workDir: DEV_WORKDIR,
-    repos: [],
-  }, null, 2));
-}
-
-// Mirror pages-root assets into public/ so the dev server can serve
-// them at the URL paths the deployed site uses (manifest at
-// /manifest.webmanifest, setup page at /setup/). Both mirror files
-// are .gitignored — they exist only for local preview.
-//
-// The manifest is rewritten with a "ccsm-dev" identity so the PWA
-// installed from dev shows up separately in Chrome's installed-apps
-// list and Start Menu, instead of conflicting with the prod CCSM
-// install.
-const REPO_ROOT = path.join(__dirname, '..');
-const PAGES_ROOT = path.join(REPO_ROOT, 'pages-root');
-const PUBLIC_DIR = path.join(REPO_ROOT, 'public');
-
-function mirrorSetup() {
-  try {
-    const src = path.join(PAGES_ROOT, 'setup');
-    const dst = path.join(PUBLIC_DIR, 'setup');
-    fs.mkdirSync(dst, { recursive: true });
-    for (const f of fs.readdirSync(src)) {
-      fs.copyFileSync(path.join(src, f), path.join(dst, f));
-    }
-  } catch (e) { console.warn('[dev] setup mirror failed:', e.message); }
-}
-function writeDevManifest() {
-  try {
-    const src = path.join(PAGES_ROOT, 'manifest.webmanifest');
-    const m = JSON.parse(fs.readFileSync(src, 'utf8'));
-    m.id = '/?ccsm-dev';
-    m.name = 'CCSM dev';
-    m.short_name = 'CCSM dev';
-    // Dev runs at host root (localhost:7788/), so scope + start_url
-    // anchor at `/` not `./` (which would resolve relative to the
-    // manifest URL — same result here, but explicit is clearer).
-    m.scope = '/';
-    m.start_url = '/';
-    // Drop related_applications self-reference — its URL points at
-    // the prod GH Pages manifest, not this dev one. Leaving it in
-    // would let prod's getInstalledRelatedApps() detect dev installs
-    // as if they were prod, which is the opposite of what we want.
-    delete m.related_applications;
-    fs.writeFileSync(path.join(PUBLIC_DIR, 'manifest.webmanifest'), JSON.stringify(m, null, 2));
-  } catch (e) { console.warn('[dev] manifest mirror failed:', e.message); }
-}
-mirrorSetup();
-writeDevManifest();
-
-const env = {
-  ...process.env,
-  CCSM_HOME: DEV_HOME,
-  CCSM_PORT: DEV_PORT,
-  CCSM_NO_BROWSER: '1',
-  // Marks the running server as "launched by dev.js" so /api/restart can
-  // skip the production restart-helper path (which respawns the global
-  // `ccsm.cmd` and would replace our --watch checkout server). In dev
-  // mode the server just process.exit(0)s and this script respawns it.
-  CCSM_DEV: '1',
-  // Always opt out of the 90s heartbeat watchdog in dev. The watchdog
-  // only matters when ccsm is tied to its own spawned browser window —
-  // closing that window means ccsm should stop. In dev there's no such
-  // window (CCSM_NO_BROWSER above) and the contributor's browser tab
-  // may be closed for minutes during a long file edit. Without this,
-  // any ambient CCSM_LAUNCHER=1 in the parent shell would silently make
-  // the dev server self-terminate every 90s.
-  CCSM_KEEP_ALIVE: '1',
-  // Explicitly clear CCSM_LAUNCHER so the watchdog activation condition
-  // can never be true here regardless of the parent env.
-  CCSM_LAUNCHER: '',
-};
-
-const serverPath = path.join(__dirname, '..', 'server.js');
-
-let current = null;
-let stopping = false;
-
-function spawnServer() {
-  // Don't use `node --watch` here — its restart-on-exit semantics are
-  // "wait for a file change after a clean exit", so calling
-  // process.exit(0) from /api/restart leaves --watch idling forever
-  // until the user touches a file. We do our own respawn-on-exit
-  // (below) which handles both the restart-by-exit path AND crashes,
-  // and the dev/api SSE endpoint still gives us frontend hot-reload
-  // without needing --watch for backend code (each restart pulls fresh
-  // require() cache anyway since this is a new process).
-  const child = spawn(process.execPath, [serverPath], {
-    env,
-    stdio: 'inherit',
-  });
-  child.on('exit', (code, signal) => {
-    if (stopping) {
-      process.exit(signal ? 1 : (code ?? 0));
-      return;
-    }
-    // Server asked to restart (POST /api/restart → gracefulShutdown +
-    // exit 0). Respawn — node --watch picks up any code changes that
-    // landed in the meantime. A small delay lets the port fully release.
-    console.log(`[dev] server exited (code=${code} signal=${signal || ''}) · respawning`);
-    setTimeout(() => { current = spawnServer(); }, 500);
-  });
-  return child;
-}
-
-const stop = (sig) => () => {
-  stopping = true;
-  if (current) current.kill(sig);
-};
-process.on('SIGINT', stop('SIGINT'));
-process.on('SIGTERM', stop('SIGTERM'));
-
-current = spawnServer();
+#!/usr/bin/env node
+'use strict';
+
+// Dev launcher · fully isolates from the user's prod ccsm install.
+//
+// Why: many contributors run the published `@bakapiano/ccsm` package
+// for their day-to-day work (port 7777, ~/.ccsm). If `npm run dev`
+// reused the same data dir + port, every hot-reload would clobber the
+// live sessions.json. So dev gets its own:
+//
+//   - CCSM_HOME   → ~/.ccsm-dev/   (separate config.json, sessions.json, folders.json)
+//   - port        → 7788           (no contention with prod 7777)
+//   - workDir     → ~/ccsm-workspaces-dev (separate workspace tree)
+//   - no browser auto-open (we're iterating in an already-open tab)
+//
+// Run via `npm run dev`. The first launch seeds a starter config; later
+// launches leave it alone so dev's own customisations stick.
+
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const DEV_HOME = path.join(os.homedir(), '.ccsm-dev');
+const DEV_PORT = '7788';
+const DEV_WORKDIR = path.join(os.homedir(), 'ccsm-workspaces-dev');
+
+fs.mkdirSync(DEV_HOME, { recursive: true });
+
+// Seed a fresh dev config the first time. Subsequent runs leave the
+// existing file alone — the dev's own UI edits persist across restarts.
+const configPath = path.join(DEV_HOME, 'config.json');
+if (!fs.existsSync(configPath)) {
+  fs.writeFileSync(configPath, JSON.stringify({
+    port: Number(DEV_PORT),
+    workDir: DEV_WORKDIR,
+    repos: [],
+  }, null, 2));
+}
+
+// Mirror pages-root assets into public/ so the dev server can serve
+// them at the URL paths the deployed site uses (manifest at
+// /manifest.webmanifest, setup page at /setup/). Both mirror files
+// are .gitignored — they exist only for local preview.
+//
+// The manifest is rewritten with a "ccsm-dev" identity so the PWA
+// installed from dev shows up separately in Chrome's installed-apps
+// list and Start Menu, instead of conflicting with the prod CCSM
+// install.
+const REPO_ROOT = path.join(__dirname, '..');
+const PAGES_ROOT = path.join(REPO_ROOT, 'pages-root');
+const PUBLIC_DIR = path.join(REPO_ROOT, 'public');
+
+function mirrorSetup() {
+  try {
+    const src = path.join(PAGES_ROOT, 'setup');
+    const dst = path.join(PUBLIC_DIR, 'setup');
+    fs.mkdirSync(dst, { recursive: true });
+    for (const f of fs.readdirSync(src)) {
+      fs.copyFileSync(path.join(src, f), path.join(dst, f));
+    }
+  } catch (e) { console.warn('[dev] setup mirror failed:', e.message); }
+}
+function writeDevManifest() {
+  try {
+    const src = path.join(PAGES_ROOT, 'manifest.webmanifest');
+    const m = JSON.parse(fs.readFileSync(src, 'utf8'));
+    m.id = '/?ccsm-dev';
+    m.name = 'CCSM dev';
+    m.short_name = 'CCSM dev';
+    // Dev runs at host root (localhost:7788/), so scope + start_url
+    // anchor at `/` not `./` (which would resolve relative to the
+    // manifest URL — same result here, but explicit is clearer).
+    m.scope = '/';
+    m.start_url = '/';
+    // Drop related_applications self-reference — its URL points at
+    // the prod GH Pages manifest, not this dev one. Leaving it in
+    // would let prod's getInstalledRelatedApps() detect dev installs
+    // as if they were prod, which is the opposite of what we want.
+    delete m.related_applications;
+    fs.writeFileSync(path.join(PUBLIC_DIR, 'manifest.webmanifest'), JSON.stringify(m, null, 2));
+  } catch (e) { console.warn('[dev] manifest mirror failed:', e.message); }
+}
+mirrorSetup();
+writeDevManifest();
+
+const env = {
+  ...process.env,
+  CCSM_HOME: DEV_HOME,
+  CCSM_PORT: DEV_PORT,
+  CCSM_NO_BROWSER: '1',
+  // Marks the running server as "launched by dev.js" so /api/restart can
+  // skip the production restart-helper path (which respawns the global
+  // `ccsm.cmd` and would replace our --watch checkout server). In dev
+  // mode the server just process.exit(0)s and this script respawns it.
+  CCSM_DEV: '1',
+  // Always opt out of the 90s heartbeat watchdog in dev. The watchdog
+  // only matters when ccsm is tied to its own spawned browser window —
+  // closing that window means ccsm should stop. In dev there's no such
+  // window (CCSM_NO_BROWSER above) and the contributor's browser tab
+  // may be closed for minutes during a long file edit. Without this,
+  // any ambient CCSM_LAUNCHER=1 in the parent shell would silently make
+  // the dev server self-terminate every 90s.
+  CCSM_KEEP_ALIVE: '1',
+  // Explicitly clear CCSM_LAUNCHER so the watchdog activation condition
+  // can never be true here regardless of the parent env.
+  CCSM_LAUNCHER: '',
+};
+
+const serverPath = path.join(__dirname, '..', 'server.js');
+
+let current = null;
+let stopping = false;
+
+function spawnServer() {
+  // Don't use `node --watch` here — its restart-on-exit semantics are
+  // "wait for a file change after a clean exit", so calling
+  // process.exit(0) from /api/restart leaves --watch idling forever
+  // until the user touches a file. We do our own respawn-on-exit
+  // (below) which handles both the restart-by-exit path AND crashes,
+  // and the dev/api SSE endpoint still gives us frontend hot-reload
+  // without needing --watch for backend code (each restart pulls fresh
+  // require() cache anyway since this is a new process).
+  const child = spawn(process.execPath, [serverPath], {
+    env,
+    stdio: 'inherit',
+  });
+  child.on('exit', (code, signal) => {
+    if (stopping) {
+      process.exit(signal ? 1 : (code ?? 0));
+      return;
+    }
+    // Server asked to restart (POST /api/restart → gracefulShutdown +
+    // exit 0). Respawn — node --watch picks up any code changes that
+    // landed in the meantime. A small delay lets the port fully release.
+    console.log(`[dev] server exited (code=${code} signal=${signal || ''}) · respawning`);
+    setTimeout(() => { current = spawnServer(); }, 500);
+  });
+  return child;
+}
+
+const stop = (sig) => () => {
+  stopping = true;
+  if (current) current.kill(sig);
+};
+process.on('SIGINT', stop('SIGINT'));
+process.on('SIGTERM', stop('SIGTERM'));
+
+current = spawnServer();

package/scripts/install.js

@@ -1,153 +1,153 @@
-#!/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.');
-}
-
-// Open the hosted setup guide. The page walks the user through the
-// remaining one-time setup (allow ccsm:// protocol, firewall, install
-// as PWA) and Step 1's "Try ccsm://start" button doubles as ccsm
-// auto-launch — so we don't need a separate spawn here. Set
-// CCSM_NO_AUTOLAUNCH=1 to skip (CI, headless setups).
-if (process.env.CCSM_NO_AUTOLAUNCH !== '1') {
-  try {
-    // `start` on Windows opens the default browser without attaching a
-    // console. Run via cmd.exe /c since `start` is a cmd builtin.
-    require('node:child_process').spawn(
-      'cmd.exe',
-      ['/d', '/s', '/c', 'start', '', 'https://bakapiano.github.io/ccsm/setup/'],
-      { detached: true, stdio: 'ignore', windowsHide: true }
-    ).unref();
-    log('opened setup guide · https://bakapiano.github.io/ccsm/setup/');
-    log('(set CCSM_NO_AUTOLAUNCH=1 to skip this on future installs)');
-  } catch (e) {
-    warn(`setup guide open 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.');
+}
+
+// Open the hosted setup guide. The page walks the user through the
+// remaining one-time setup (allow ccsm:// protocol, firewall, install
+// as PWA) and Step 1's "Try ccsm://start" button doubles as ccsm
+// auto-launch — so we don't need a separate spawn here. Set
+// CCSM_NO_AUTOLAUNCH=1 to skip (CI, headless setups).
+if (process.env.CCSM_NO_AUTOLAUNCH !== '1') {
+  try {
+    // `start` on Windows opens the default browser without attaching a
+    // console. Run via cmd.exe /c since `start` is a cmd builtin.
+    require('node:child_process').spawn(
+      'cmd.exe',
+      ['/d', '/s', '/c', 'start', '', 'https://bakapiano.github.io/ccsm/setup/'],
+      { detached: true, stdio: 'ignore', windowsHide: true }
+    ).unref();
+    log('opened setup guide · https://bakapiano.github.io/ccsm/setup/');
+    log('(set CCSM_NO_AUTOLAUNCH=1 to skip this on future installs)');
+  } catch (e) {
+    warn(`setup guide open failed · ${e.message}`);
+    warn('run `ccsm` manually to start.');
+  }
+}