stackbite 0.5.98 → 0.5.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stackbite",
-  "version": "0.5.98",
+  "version": "0.5.99",
   "description": "Verified native Stackbite CLI bootstrapper",
   "license": "UNLICENSED",
   "engines": {

package/packaging/npm/lib/bootstrap.js

@@ -171,17 +171,26 @@ async function publicExecutable(root, spec, hashes) {
   const manifest = JSON.parse((await readSmall(path.join(root, 'manifest.json'))).toString('utf8'));
   const entry = manifest.binaries?.['stackbite-launcher'], info = entry?.build_info;
   const target = { win32: 'x86_64-pc-windows-msvc', linux: 'x86_64-unknown-linux-gnu', darwin: 'aarch64-apple-darwin' }[spec.platform];
-  if (manifest.schema !== 'stackbite-rust-terminal-build-v1' || manifest.product !== 'Stackbite'
-      || manifest.version !== spec.version || manifest.commit !== spec.commit || manifest.target !== target || manifest.protocol !== 1
-      || !entry || Object.keys(entry).sort().join(',') !== 'build_info,path,sha256'
-      || entry.path !== name || entry.sha256 !== hashes[name] || manifest.artifacts?.[name]?.sha256 !== hashes[name]
-      || manifest.artifacts?.[name]?.kind !== 'binary' || !Number.isSafeInteger(manifest.artifacts?.[name]?.size) || manifest.artifacts[name].size < 1
-      || !info || Object.keys(info).sort().join(',') !== 'binary,commit,product,protocol,target,version'
-      || info.product !== 'Stackbite' || info.binary !== 'stackbite-launcher' || info.version !== spec.version
-      || info.commit !== spec.commit || info.target !== target || info.protocol !== 1) fail('Native entry package identity or pin is invalid');
+  if (!terminalBuildMatches(manifest, spec, target) || !launcherPinMatches(manifest, entry, name, hashes)
+      || !launcherBuildInfoMatches(info, spec, target)) fail('Native entry package identity or pin is invalid');
   const launcher = await nativeExecutable(root, spec, 'stackbite-launcher');
   return spec.platform === 'win32' ? engine : launcher;
 }
+function terminalBuildMatches(manifest, spec, target) {
+  return manifest.schema === 'stackbite-rust-terminal-build-v1' && manifest.product === 'Stackbite'
+    && manifest.version === spec.version && manifest.commit === spec.commit && manifest.target === target && manifest.protocol === 1;
+}
+// The manifest entry and its artifact record both pin the release hash of `name`.
+function launcherPinMatches(manifest, entry, name, hashes) {
+  return !!entry && Object.keys(entry).sort().join(',') === 'build_info,path,sha256'
+    && entry.path === name && entry.sha256 === hashes[name] && manifest.artifacts?.[name]?.sha256 === hashes[name]
+    && manifest.artifacts?.[name]?.kind === 'binary' && Number.isSafeInteger(manifest.artifacts?.[name]?.size) && !(manifest.artifacts[name].size < 1);
+}
+function launcherBuildInfoMatches(info, spec, target) {
+  return !!info && Object.keys(info).sort().join(',') === 'binary,commit,product,protocol,target,version'
+    && info.product === 'Stackbite' && info.binary === 'stackbite-launcher' && info.version === spec.version
+    && info.commit === spec.commit && info.target === target && info.protocol === 1;
+}
 async function validatePayload(directory, spec, { includePhone = true } = {}) {
   const root = await payloadRoot(directory);
   const { hashes, metadata } = await pinnedDocuments(root, spec);
@@ -301,34 +310,40 @@ async function assertBaseline(environment, platform) {
   if (Buffer.byteLength(raw) > 16384) fail('Invalid installation baseline');
   const expected = JSON.parse(raw), root = installationRoot(environment, platform);
   if (expected.preparation !== undefined) {
-    const pin = expected.preparation, file = path.join(root, '.stackbite-update', 'update.lock');
-    if (Object.keys(expected).sort().join(',') !== 'preparation,root' || expected.root !== root
-        || !pin || Object.keys(pin).sort().join(',') !== 'identity,path' || pin.path !== file || !pin.identity) fail('Invalid installation preparation');
-    let identity = pin.identity;
-    const actual = await baselinePin(file);
-    if (platform === 'win32' && actual) identity = { ...identity, device: (BigInt(identity.device) & 0xffffffffn).toString() };
-    if (JSON.stringify(actual) !== JSON.stringify(identity)) fail('Installation changed while staging');
+    await assertPreparationBaseline(expected, root, platform);
     return;
   }
-  let current = null;
+  const current = await locatorInstallationId(root);
+  if (expected.root !== root || expected.incarnation !== current) fail('Installation changed while staging');
+  if (current === null) await assertLegacyBaseline(expected, platform);
+}
+// Python-origin restrictions retain FILE_ID_INFO's full volume serial;
+// libuv reports its 32-bit component. The engine still checks the full pin.
+function libuvIdentity(platform, actual, identity) {
+  return platform === 'win32' && actual && identity ? { ...identity, device: (BigInt(identity.device) & 0xffffffffn).toString() } : identity;
+}
+async function assertPreparationBaseline(expected, root, platform) {
+  const pin = expected.preparation, file = path.join(root, '.stackbite-update', 'update.lock');
+  if (Object.keys(expected).sort().join(',') !== 'preparation,root' || expected.root !== root
+      || !pin || Object.keys(pin).sort().join(',') !== 'identity,path' || pin.path !== file || !pin.identity) fail('Invalid installation preparation');
+  const actual = await baselinePin(file);
+  if (JSON.stringify(actual) !== JSON.stringify(libuvIdentity(platform, actual, pin.identity))) fail('Installation changed while staging');
+}
+// The first present locator's incarnation; null for a legacy or absent locator.
+async function locatorInstallationId(root) {
   for (const name of ['default-install.json', 'install.json']) {
     const file = path.join(root, name);
     if (!await exists(file)) continue;
     const value = JSON.parse((await readSmall(file, 16384)).toString('utf8').replace(/^\uFEFF/, ''));
-    current = value.installation_id ?? null;
-    break;
+    return value.installation_id ?? null;
   }
-  if (expected.root !== root || expected.incarnation !== current) fail('Installation changed while staging');
-  if (current === null) {
-    if (!Array.isArray(expected.legacy) || !expected.legacy.length || expected.legacy.length > 32) fail('Invalid legacy installation baseline');
-    for (const pin of expected.legacy) {
-      const actual = await baselinePin(pin.path);
-      let identity = pin.identity;
-      // Python-origin restrictions retain FILE_ID_INFO's full volume serial;
-      // libuv reports its 32-bit component. The engine still checks the full pin.
-      if (platform === 'win32' && actual && identity) identity = { ...identity, device: (BigInt(identity.device) & 0xffffffffn).toString() };
-      if (JSON.stringify(actual) !== JSON.stringify(identity)) fail('Installation changed while staging');
-    }
+  return null;
+}
+async function assertLegacyBaseline(expected, platform) {
+  if (!Array.isArray(expected.legacy) || !expected.legacy.length || expected.legacy.length > 32) fail('Invalid legacy installation baseline');
+  for (const pin of expected.legacy) {
+    const actual = await baselinePin(pin.path);
+    if (JSON.stringify(actual) !== JSON.stringify(libuvIdentity(platform, actual, pin.identity))) fail('Installation changed while staging');
   }
 }
 
@@ -390,6 +405,30 @@ async function settlePreparation(preparation, environment, platform, source) {
   } finally { await preparation.handle.close(); }
 }
 
+// Identities of the candidates that this mkdir created (the first created directory and below).
+async function createdDirectories(firstCreated, candidates) {
+  const directories = [];
+  if (firstCreated) {
+    for (const selected of candidates) {
+      // libuv may return a Windows namespace spelling for the first directory.
+      const createdName = path.toNamespacedPath(firstCreated), selectedName = path.toNamespacedPath(selected);
+      if (selectedName === createdName || selectedName.startsWith(createdName + path.sep)) {
+        directories.push([selected, await fs.lstat(selected, { bigint: true })]);
+      }
+    }
+  }
+  return directories;
+}
+// Creates the control file, or opens the existing one; `created` marks ours.
+async function openPreparationFile(file) {
+  const constants = require('node:fs').constants;
+  try {
+    return { handle: await fs.open(file, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | (constants.O_NOFOLLOW || 0), 0o600), created: true };
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    return { handle: await fs.open(file, constants.O_RDWR | (constants.O_NOFOLLOW || 0)), created: false };
+  }
+}
 async function reservePreparation(environment, platform, target, source) {
   if (Object.hasOwn(environment, 'STACKBITE_INSTALL_BASELINE')) return null;
   let baseline = await captureBaseline(environment, platform, target);
@@ -410,26 +449,10 @@ async function reservePreparation(environment, platform, target, source) {
   if (source) await source.validate();
   const firstCreated = await fs.mkdir(directory, { recursive: true, mode: 0o700 });
   await existingCacheDirectory(directory);
-  const directories = [];
-  if (firstCreated) {
-    for (const selected of [directory, root]) {
-      // libuv may return a Windows namespace spelling for the first directory.
-      const createdName = path.toNamespacedPath(firstCreated), selectedName = path.toNamespacedPath(selected);
-      if (selectedName === createdName || selectedName.startsWith(createdName + path.sep)) {
-        directories.push([selected, await fs.lstat(selected, { bigint: true })]);
-      }
-    }
-  }
-  const constants = require('node:fs').constants;
+  const directories = await createdDirectories(firstCreated, [directory, root]);
   const file = path.join(directory, 'update.lock');
-  let handle, created = false, preparation;
-  try {
-    handle = await fs.open(file, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | (constants.O_NOFOLLOW || 0), 0o600);
-    created = true;
-  } catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    handle = await fs.open(file, constants.O_RDWR | (constants.O_NOFOLLOW || 0));
-  }
+  const { handle, created } = await openPreparationFile(file);
+  let preparation;
   try {
     const held = await handle.stat({ bigint: true });
     const identity = await baselinePin(file);

package/packaging/npm/lib/uninstall-registration.js

@@ -88,36 +88,51 @@ async function captureCommand(root, prefix, platform, node, cli, recoveryOptions
   if (!entryInfo.isFile() || entryInfo.isSymbolicLink() || entryInfo.nlink !== 1) throw new Error('Linked npm command preserved');
   const entryData = await fs.readFile(entry);
   for (const shim of platform === 'win32' ? ['stackbite', 'stackbite.cmd', 'stackbite.ps1'].map(name => path.join(prefix, name)) : [path.join(prefix, 'bin', 'stackbite')]) {
-    await commandParent(shim);
-    let info;
-    try { info = await fs.lstat(shim); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
-    if (info.isSymbolicLink()) {
-      const target = await fs.readlink(shim);
-      if (path.resolve(path.dirname(shim), target) !== entry) throw new Error('Foreign npm command preserved');
-      shims.push({ path: shim, info, target });
-    } else {
-      const data = await fs.readFile(shim);
-      if (!info.isFile() || info.nlink !== 1 || data.length > 128 * 1024 || !data.toString('utf8').replaceAll('\\', '/').includes(relative)) throw new Error('Foreign npm command preserved');
-      shims.push({ path: shim, info, data });
-    }
+    const captured = await captureShim(shim, entry, relative);
+    if (captured) shims.push(captured);
   }
   if (!shims.length) return null;
-  const options = JSON.stringify({ packageRoot: root, platform, nodeExecutable: node, npmCli: cli,
-    installRoot: recoveryOptions.installRoot, cache: recoveryOptions.cache });
-  const recovery = Buffer.from(`const m=require('./uninstall-registration'),cp=require('node:child_process');\nconst launch=async(exe,args,env)=>{const r=cp.spawnSync(exe,args,{env,stdio:'inherit'});if(r.error)throw r.error;return {code:r.status,signal:r.signal};};\nmodule.exports.main=async()=>{const r=await m.registrationOnly(process.argv.slice(2),process.env,launch,${options});if(!r)throw Error('Native removal remains incomplete');return r;};\n`);
+  const recovery = recoveryModule(root, platform, node, cli, recoveryOptions);
   const files = [];
   for (const [file, data] of [[path.join(root, 'package.json'), metadata], [entry, entryData],
     [path.join(root, 'packaging/npm/lib/bootstrap.js'), recovery],
     [path.join(root, 'packaging/npm/lib/uninstall-registration.js'), await fs.readFile(__filename)]]) {
-    await commandParent(file);
-    let info;
-    try { info = await fs.lstat(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
-    if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) throw new Error('Linked npm command preserved');
-    files.push({ path: file, info, data });
+    files.push(await captureFile(file, data));
   }
   return { root, info: await fs.lstat(root), prefix, prefixInfo: await fs.lstat(prefix), shims, files };
 }
 
+// The file's current identity (undefined when absent) with the bytes to restore.
+async function captureFile(file, data) {
+  await commandParent(file);
+  let info;
+  try { info = await fs.lstat(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) throw new Error('Linked npm command preserved');
+  return { path: file, info, data };
+}
+
+// An absent shim is null. A present one must link or point to this package's entry.
+async function captureShim(shim, entry, relative) {
+  await commandParent(shim);
+  let info;
+  try { info = await fs.lstat(shim); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (info.isSymbolicLink()) {
+    const target = await fs.readlink(shim);
+    if (path.resolve(path.dirname(shim), target) !== entry) throw new Error('Foreign npm command preserved');
+    return { path: shim, info, target };
+  }
+  const data = await fs.readFile(shim);
+  if (!info.isFile() || info.nlink !== 1 || data.length > 128 * 1024 || !data.toString('utf8').replaceAll('\\', '/').includes(relative)) throw new Error('Foreign npm command preserved');
+  return { path: shim, info, data };
+}
+
+// The bootstrap.js replacement that lets the original bin finish registration-only removal.
+function recoveryModule(root, platform, node, cli, recoveryOptions) {
+  const options = JSON.stringify({ packageRoot: root, platform, nodeExecutable: node, npmCli: cli,
+    installRoot: recoveryOptions.installRoot, cache: recoveryOptions.cache });
+  return Buffer.from(`const m=require('./uninstall-registration'),cp=require('node:child_process');\nconst launch=async(exe,args,env)=>{const r=cp.spawnSync(exe,args,{env,stdio:'inherit'});if(r.error)throw r.error;return {code:r.status,signal:r.signal};};\nmodule.exports.main=async()=>{const r=await m.registrationOnly(process.argv.slice(2),process.env,launch,${options});if(!r)throw Error('Native removal remains incomplete');return r;};\n`);
+}
+
 async function restoreCommand(backup) {
   if (!backup) return;
   const info = await fs.lstat(backup.root);
@@ -125,32 +140,37 @@ async function restoreCommand(backup) {
   const prefix = await fs.lstat(backup.prefix);
   if (prefix.dev !== backup.prefixInfo.dev || prefix.ino !== backup.prefixInfo.ino) throw new Error('npm prefix replaced; preserved');
   const items = [...backup.files, ...backup.shims];
-  for (const item of items) {
-    await commandParent(item.path);
-    try {
-      const current = await fs.lstat(item.path);
-      if (!item.info || current.dev !== item.info.dev || current.ino !== item.info.ino) throw new Error('npm command replaced; preserved');
-      if (!item.target && (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1)) throw new Error('Linked npm command preserved');
-    } catch (error) { if (error.code !== 'ENOENT') throw error; }
-  }
+  for (const item of items) await assertRestorable(item);
   for (const item of items) {
     if (item.target) {
       try { await fs.lstat(item.path); } catch (error) { if (error.code !== 'ENOENT') throw error; await fs.symlink(item.target, item.path); }
-    } else {
-      // An npm partial uninstall can leave this original bin read/share-only.
-      // Its existing require('../lib/bootstrap') reaches the small recovery module.
-      try { if ((await fs.readFile(item.path)).equals(item.data)) continue; }
-      catch (error) { if (error.code !== 'ENOENT') throw error; }
-      await fs.mkdir(path.dirname(item.path), { recursive: true });
-      await commandParent(item.path);
-      const file = await fs.open(item.path, require('node:fs').constants.O_WRONLY | require('node:fs').constants.O_CREAT
-        | require('node:fs').constants.O_TRUNC | (require('node:fs').constants.O_NOFOLLOW || 0), 0o755);
-      try { await file.writeFile(item.data); } finally { await file.close(); }
-      await fs.chmod(item.path, 0o755);
-    }
+    } else await restoreFile(item);
   }
 }
 
+// A present item is still the captured object; a file is still unlinked.
+async function assertRestorable(item) {
+  await commandParent(item.path);
+  try {
+    const current = await fs.lstat(item.path);
+    if (!item.info || current.dev !== item.info.dev || current.ino !== item.info.ino) throw new Error('npm command replaced; preserved');
+    if (!item.target && (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1)) throw new Error('Linked npm command preserved');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+async function restoreFile(item) {
+  // An npm partial uninstall can leave this original bin read/share-only.
+  // Its existing require('../lib/bootstrap') reaches the small recovery module.
+  try { if ((await fs.readFile(item.path)).equals(item.data)) return; }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await fs.mkdir(path.dirname(item.path), { recursive: true });
+  await commandParent(item.path);
+  const file = await fs.open(item.path, require('node:fs').constants.O_WRONLY | require('node:fs').constants.O_CREAT
+    | require('node:fs').constants.O_TRUNC | (require('node:fs').constants.O_NOFOLLOW || 0), 0o755);
+  try { await file.writeFile(item.data); } finally { await file.close(); }
+  await fs.chmod(item.path, 0o755);
+}
+
 async function commandParent(file) {
   for (let parent = path.dirname(file); ; parent = path.dirname(parent)) {
     try { const info = await fs.lstat(parent); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Linked npm command preserved'); }
@@ -188,119 +208,154 @@ function windowsCleanupCommand(helper, pin) {
   return ['powershell.exe', '-NoProfile', '-Command', dispatch];
 }
 
-async function registrationOnly(argv, environment, launch, options = {}) {
-  if (!explicitApply(argv)) return null;
-  const platform = options.platform || process.platform;
-  const packageRoot = options.packageRoot || path.resolve(__dirname, '../../..');
-  const prefix = await registration(packageRoot, platform);
-  if (prefix === null) return null;
+const sameIdentity = (a, b) => a.dev === b.dev && a.ino === b.ino;
+
+// The user's home and the data directory that holds the canonical installation root.
+function productData(environment, platform) {
   const home = (platform === 'win32' ? environment.USERPROFILE || environment.HOME : environment.HOME) || require('node:os').homedir();
   const data = platform === 'win32' ? environment.LOCALAPPDATA || home
     : environment.XDG_DATA_HOME || path.join(home, '.local', 'share');
-  const root = options.installRoot || path.join(data, platform === 'win32' ? 'Stackbite' : 'stackbite');
+  return { home, data };
+}
+
+// Every location an installed native product could occupy. Registration-only
+// removal is allowed only when all of them are absent or empty directory shells.
+function nativeLocations(environment, platform, prefix, options) {
+  const { home, data } = productData(environment, platform);
   const canonical = path.join(data, platform === 'win32' ? 'Stackbite' : 'stackbite');
+  const root = options.installRoot || canonical;
   const old = path.join(data, platform === 'win32' ? 'Helm' : 'helm');
+  const legacyNames = ['app', 'cache', 'state', 'default-install.json', 'install.json'];
   // Keep this recovery module standalone after npm removes the other modules.
   // This is cache.js's npm namespace, not Python's locator/control fallback.
   const npmData = environment.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
-  const roots = [root, ...['app', 'cache', 'state', 'default-install.json', 'install.json'].map(name => path.join(old, name)),
-    ...(platform === 'win32' ? [path.join(npmData, 'Stackbite'),
-      ...['app', 'cache', 'state', 'default-install.json', 'install.json'].map(name =>
-        path.join(npmData, 'Helm', name))] : []),
+  const roots = [root, ...legacyNames.map(name => path.join(old, name)),
+    ...(platform === 'win32' ? [path.join(npmData, 'Stackbite'), ...legacyNames.map(name => path.join(npmData, 'Helm', name))] : []),
     ...(platform === 'win32' ? [] : ['stackbite', 'helm'].flatMap(name => [
       path.join(environment.XDG_STATE_HOME || path.join(home, '.local', 'state'), name),
       path.join(environment.XDG_CACHE_HOME || path.join(home, '.cache'), name)])),
     ...[options.cache, environment.STACKBITE_HOME, environment.STACKBITE_STATE_DIR].filter(Boolean)];
-  // Directory shells left by a completed physical tail contain no artifacts.
-  // The pinned canonical preparation below is the only permitted file.
-  let preparation, preparationHandle;
-  async function empty(location) {
-    try {
-      const info = await fs.lstat(location);
-      if (preparation && location === preparation.file) return preparationCurrent();
-      if (!info.isDirectory() || info.isSymbolicLink() || await fs.realpath(location) !== path.resolve(location)) return false;
-      for (const name of await fs.readdir(location)) if (!await empty(path.join(location, name))) return false;
-      return true;
-    } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+  const commands = platform === 'win32' ? ['stackbite.cmd', 'stackbite-portable.cmd', 'stackbite.exe', 'stackbite.exe.next'] : ['stackbite'];
+  for (const name of commands) {
+    const native = path.join(home, '.local', 'bin', name);
+    const own = platform === 'win32' ? path.join(prefix, name) : path.join(prefix, 'bin', name);
+    if (native !== own) roots.push(native);
   }
-  const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
-  async function preparationCurrent() {
-    const held = await preparation.handle.stat({ bigint: true });
-    const current = await fs.lstat(preparation.file, { bigint: true });
-    const bytes = Buffer.alloc(2);
-    const { bytesRead } = await preparation.handle.read(bytes, 0, bytes.length, 0);
-    return held.isFile() && current.isFile() && !current.isSymbolicLink()
-      && held.nlink === 1n && current.nlink === 1n && same(held, preparation.info) && same(current, held)
-      && held.size <= 1n && current.size === held.size && BigInt(bytesRead) === held.size
-      && (bytesRead === 0 || bytesRead === 1 && bytes[0] === 0x30);
+  return { root, canonical, roots: [...new Set(roots)] };
+}
+
+// True when `start` and each ancestor is a real, unlinked directory outside a Git checkout.
+async function plainDirectoryChain(start) {
+  for (let parent = start; ; parent = path.dirname(parent)) {
+    const info = await fs.lstat(parent);
+    if (!info.isDirectory() || info.isSymbolicLink() || await fs.realpath(parent) !== parent) return false;
+    try { await fs.lstat(path.join(parent, '.git')); return false; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (parent === path.dirname(parent)) return true;
   }
-  async function preparationDirectories() {
-    for (let parent = preparation.directory; ; parent = path.dirname(parent)) {
-      const info = await fs.lstat(parent);
-      if (!info.isDirectory() || info.isSymbolicLink() || await fs.realpath(parent) !== parent) return false;
-      try { await fs.lstat(path.join(parent, '.git')); return false; }
-      catch (error) { if (error.code !== 'ENOENT') throw error; }
-      if (parent === path.dirname(parent)) break;
-    }
-    for (const [directory, expected, names] of [
-      [root, preparation.rootInfo, ['.stackbite-update']],
-      [preparation.directory, preparation.directoryInfo, ['update.lock']],
-    ]) {
-      const info = await fs.lstat(directory, { bigint: true });
-      if (!info.isDirectory() || info.isSymbolicLink() || !same(info, expected)
-          || await fs.realpath(directory) !== directory
-          || JSON.stringify((await fs.readdir(directory)).sort()) !== JSON.stringify(names)) return false;
-    }
-    return preparationCurrent();
+}
+
+async function ancestorsAreDirectories(location) {
+  for (let parent = path.dirname(location); ; parent = path.dirname(parent)) {
+    try { const info = await fs.lstat(parent); if (!info.isDirectory() || info.isSymbolicLink()) return false; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (parent === path.dirname(parent)) return true;
   }
-  // A first-ever publisher pins this existing control object across download.
-  // Unlinking its verified name invalidates that publisher; this FD is no mutex.
+}
+
+// A first-ever publisher pins this existing control object across download.
+// Unlinking its verified name invalidates that publisher; this FD is no mutex.
+// Returns null when there is no preparation, false when it is not ours to remove.
+async function openPreparation(root, canonical) {
   const directory = path.join(root, '.stackbite-update'), file = path.join(directory, 'update.lock');
+  let info;
+  try { info = await fs.lstat(file, { bigint: true }); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (root !== canonical || !path.isAbsolute(root) || path.resolve(root) !== root
+      || root.split(path.sep).includes('..') || /[\0\r\n]/.test(root)
+      || !info.isFile() || info.isSymbolicLink() || info.nlink !== 1n || info.size > 1n) return false;
   try {
+    if (!await plainDirectoryChain(directory)) return false;
+    const { constants } = require('node:fs');
+    const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const preparation = { root, file, directory, info, handle };
     try {
-      const info = await fs.lstat(file, { bigint: true });
-      if (root !== canonical || !path.isAbsolute(root) || path.resolve(root) !== root
-          || root.split(path.sep).includes('..') || /[\0\r\n]/.test(root)
-          || !info.isFile() || info.isSymbolicLink() || info.nlink !== 1n || info.size > 1n) return null;
-      for (let parent = directory; ; parent = path.dirname(parent)) {
-        const parentInfo = await fs.lstat(parent);
-        if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink() || await fs.realpath(parent) !== parent) return null;
-        try { await fs.lstat(path.join(parent, '.git')); return null; }
-        catch (error) { if (error.code !== 'ENOENT') throw error; }
-        if (parent === path.dirname(parent)) break;
-      }
-      preparationHandle = await fs.open(file, require('node:fs').constants.O_RDONLY | (require('node:fs').constants.O_NOFOLLOW || 0));
-      preparation = { file, directory, info, handle: preparationHandle, rootInfo: await fs.lstat(root, { bigint: true }),
-        directoryInfo: await fs.lstat(directory, { bigint: true }) };
-    } catch (error) { if (error.code !== 'ENOENT') throw error; }
-    if (preparation && !await preparationDirectories()) return null;
-    const commands = platform === 'win32' ? ['stackbite.cmd', 'stackbite-portable.cmd', 'stackbite.exe', 'stackbite.exe.next'] : ['stackbite'];
-    for (const name of commands) {
-      const native = path.join(home, '.local', 'bin', name);
-      const own = platform === 'win32' ? path.join(prefix, name) : path.join(prefix, 'bin', name);
-      if (native !== own) roots.push(native);
-    }
-    for (const location of new Set(roots)) {
+      preparation.rootInfo = await fs.lstat(root, { bigint: true });
+      preparation.directoryInfo = await fs.lstat(directory, { bigint: true });
+    } catch (error) { await handle.close(); throw error; }
+    return preparation;
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+// The held lock is still the same single-link file holding nothing or the byte '0'.
+async function preparationCurrent(preparation) {
+  const held = await preparation.handle.stat({ bigint: true });
+  const current = await fs.lstat(preparation.file, { bigint: true });
+  const bytes = Buffer.alloc(2);
+  const { bytesRead } = await preparation.handle.read(bytes, 0, bytes.length, 0);
+  return held.isFile() && current.isFile() && !current.isSymbolicLink()
+    && held.nlink === 1n && current.nlink === 1n && sameIdentity(held, preparation.info) && sameIdentity(current, held)
+    && held.size <= 1n && current.size === held.size && BigInt(bytesRead) === held.size
+    && (bytesRead === 0 || bytesRead === 1 && bytes[0] === 0x30);
+}
+
+async function preparationUnchanged(preparation) {
+  if (!await plainDirectoryChain(preparation.directory)) return false;
+  for (const [directory, expected, names] of [
+    [preparation.root, preparation.rootInfo, ['.stackbite-update']],
+    [preparation.directory, preparation.directoryInfo, ['update.lock']],
+  ]) {
+    const info = await fs.lstat(directory, { bigint: true });
+    if (!info.isDirectory() || info.isSymbolicLink() || !sameIdentity(info, expected)
+        || await fs.realpath(directory) !== directory
+        || JSON.stringify((await fs.readdir(directory)).sort()) !== JSON.stringify(names)) return false;
+  }
+  return preparationCurrent(preparation);
+}
+
+// Directory shells left by a completed physical tail contain no artifacts.
+// The pinned canonical preparation is the only permitted file.
+async function emptyLocation(location, preparation) {
+  try {
+    const info = await fs.lstat(location);
+    if (preparation && location === preparation.file) return preparationCurrent(preparation);
+    if (!info.isDirectory() || info.isSymbolicLink() || await fs.realpath(location) !== path.resolve(location)) return false;
+    for (const name of await fs.readdir(location)) if (!await emptyLocation(path.join(location, name), preparation)) return false;
+    return true;
+  } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+}
+
+async function removePreparation(preparation) {
+  await fs.unlink(preparation.file);
+  for (const [location, expected] of [[preparation.directory, preparation.directoryInfo], [preparation.root, preparation.rootInfo]]) {
+    const current = await fs.lstat(location, { bigint: true });
+    if (!sameIdentity(current, expected) || !current.isDirectory() || current.isSymbolicLink()
+        || await fs.realpath(location) !== location) throw new Error('Installation preparation replaced; preserved');
+    await fs.rmdir(location);
+  }
+}
+
+async function registrationOnly(argv, environment, launch, options = {}) {
+  if (!explicitApply(argv)) return null;
+  const platform = options.platform || process.platform;
+  const packageRoot = options.packageRoot || path.resolve(__dirname, '../../..');
+  const prefix = await registration(packageRoot, platform);
+  if (prefix === null) return null;
+  const { root, canonical, roots } = nativeLocations(environment, platform, prefix, options);
+  const preparation = await openPreparation(root, canonical);
+  if (preparation === false) return null;
+  try {
+    if (preparation && !await preparationUnchanged(preparation)) return null;
+    for (const location of roots) {
       const absolute = path.resolve(location);
-      for (let parent = path.dirname(absolute); ; parent = path.dirname(parent)) {
-        try { const info = await fs.lstat(parent); if (!info.isDirectory() || info.isSymbolicLink()) return null; }
-        catch (error) { if (error.code !== 'ENOENT') throw error; }
-        if (parent === path.dirname(parent)) break;
-      }
-      if (!await empty(absolute)) return null;
+      if (!await ancestorsAreDirectories(absolute) || !await emptyLocation(absolute, preparation)) return null;
     }
     if (preparation) {
-      if (!await preparationDirectories()) return null;
-      await fs.unlink(preparation.file);
-      for (const [location, expected] of [[directory, preparation.directoryInfo], [root, preparation.rootInfo]]) {
-        const current = await fs.lstat(location, { bigint: true });
-        if (!same(current, expected) || !current.isDirectory() || current.isSymbolicLink()
-            || await fs.realpath(location) !== location) throw new Error('Installation preparation replaced; preserved');
-        await fs.rmdir(location);
-      }
+      if (!await preparationUnchanged(preparation)) return null;
+      await removePreparation(preparation);
     }
     return removeRegistration(argv, { code: 0, signal: null }, environment, launch, { ...options, packageRoot });
-  } finally { if (preparationHandle) await preparationHandle.close(); }
+  } finally { if (preparation) await preparation.handle.close(); }
 }
 
 // Recovery never installs/downloads another runtime. Only the accepted journal's
@@ -308,22 +363,46 @@ async function registrationOnly(argv, environment, launch, options = {}) {
 async function resumeWithoutRuntime(argv, environment, launch, options = {}) {
   if (!explicitApply(argv)) return null;
   const platform = options.platform || process.platform;
-  const home = (platform === 'win32' ? environment.USERPROFILE || environment.HOME : environment.HOME) || require('node:os').homedir();
-  const root = options.installRoot || (platform === 'win32'
-    ? path.join(environment.LOCALAPPDATA || home, 'Stackbite')
-    : path.join(environment.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'stackbite'));
+  const root = options.installRoot || path.join(productData(environment, platform).data, platform === 'win32' ? 'Stackbite' : 'stackbite');
   const journal = path.join(root, '.stackbite-uninstall.json');
-  let record;
-  try {
-    const info = await fs.lstat(journal);
-    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 8 * 1024 * 1024
-        || await fs.realpath(journal) !== journal) throw new Error('Unsafe removal journal');
-    record = JSON.parse(await fs.readFile(journal, 'utf8'));
-  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  const record = await readRemovalJournal(journal);
+  if (record === undefined) return null;
   if (record.schema !== 'stackbite.uninstall.v1' || !record.accepted || !record.processes_settled
       || record.install_identity?.root !== root) return null;
   // The capsule takes the existing installation/removal locks and owns all
   // journal mutation, including npm settlement. This reader never rewrites it.
+  const recovery = recoveryCommand(record, journal, platform);
+  if (recovery === null) return null;
+  const { selected, helper, pin } = recovery;
+  const info = await fs.lstat(helper);
+  if (!await soleRegularFile(helper, info, 128 * 1024) || await sha256File(helper) !== pin.sha256) {
+    throw new Error('Removal capsule changed; preserved');
+  }
+  if (platform !== 'win32') await assertShellCapsule(record, journal);
+  return launch(selected[0], selected.slice(1), environment, options);
+}
+
+// The parsed journal; undefined when there is none.
+async function readRemovalJournal(journal) {
+  try {
+    const info = await fs.lstat(journal);
+    if (!await soleRegularFile(journal, info, 8 * 1024 * 1024)) throw new Error('Unsafe removal journal');
+    return JSON.parse(await fs.readFile(journal, 'utf8'));
+  } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+}
+
+// A regular, singly linked file within `limit` bytes that is its own real path.
+async function soleRegularFile(location, info, limit = Infinity) {
+  return info.isFile() && !info.isSymbolicLink() && info.nlink === 1 && !(info.size > limit)
+    && await fs.realpath(location) === location;
+}
+
+async function sha256File(location) {
+  return require('node:crypto').createHash('sha256').update(await fs.readFile(location)).digest('hex');
+}
+
+// The journal's recovery argv when it is exactly this platform's pinned helper invocation.
+function recoveryCommand(record, journal, platform) {
   const command = record.recovery_command;
   const suffix = platform === 'win32' ? '.ps1' : '.sh';
   const helper = journal.replace(/\.json$/, suffix);
@@ -334,43 +413,36 @@ async function resumeWithoutRuntime(argv, environment, launch, options = {}) {
   const selected = platform === 'win32' && JSON.stringify(command) === JSON.stringify(legacy) ? legacy : expected;
   if (!Array.isArray(command) || JSON.stringify(command) !== JSON.stringify(selected)
       || !record.helper_files?.some(item => item.path === helper)) return null;
-  const info = await fs.lstat(helper);
-  if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 128 * 1024
-      || await fs.realpath(helper) !== helper
-      || require('node:crypto').createHash('sha256').update(await fs.readFile(helper)).digest('hex') !== pin.sha256) {
+  return { selected, helper, pin };
+}
+
+async function assertShellCapsule(record, journal) {
+  const capsule = journal.replace(/\.json$/, '.cleanup');
+  const pinned = record.helper_files.find(item => item.path === capsule);
+  const current = await fs.lstat(capsule);
+  if (!pinned || !await soleRegularFile(capsule, current) || await sha256File(capsule) !== pinned.sha256) {
     throw new Error('Removal capsule changed; preserved');
   }
-  if (platform !== 'win32') {
-    const capsule = journal.replace(/\.json$/, '.cleanup');
-    const pinned = record.helper_files.find(item => item.path === capsule);
-    const current = await fs.lstat(capsule);
-    if (!pinned || !current.isFile() || current.isSymbolicLink() || current.nlink !== 1
-        || await fs.realpath(capsule) !== capsule
-        || require('node:crypto').createHash('sha256').update(await fs.readFile(capsule)).digest('hex') !== pinned.sha256) {
-      throw new Error('Removal capsule changed; preserved');
-    }
-    // Source invocations retain their existing interpreter/entry outside the
-    // removal inventory. Validate those exact pins before executing the shell
-    // capsule; neither environment PATH nor journal argv selects a runtime.
-    if (record.source_cleanup_pins !== undefined) {
-      if (!Array.isArray(record.source_cleanup_pins) || record.source_cleanup_pins.length !== 4) {
-        throw new Error('Source cleanup identity changed');
-      }
-      for (const pin of record.source_cleanup_pins) {
-        const location = pin.path;
-        if (typeof location !== 'string' || !path.isAbsolute(location) || /[\x00\r\n]/.test(location)
-            || location.split(path.sep).includes('..')) throw new Error('Source cleanup runtime changed');
-        const current = await fs.lstat(location);
-        if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1
-            || await fs.realpath(location) !== location || current.dev !== pin.identity?.device
-            || current.ino !== pin.identity?.inode
-            || require('node:crypto').createHash('sha256').update(await fs.readFile(location)).digest('hex') !== pin.sha256) {
-          throw new Error('Source cleanup runtime changed');
-        }
-      }
+  // Source invocations retain their existing interpreter/entry outside the
+  // removal inventory. Validate those exact pins before executing the shell
+  // capsule; neither environment PATH nor journal argv selects a runtime.
+  if (record.source_cleanup_pins !== undefined) await assertSourceCleanupPins(record.source_cleanup_pins);
+}
+
+async function assertSourceCleanupPins(pins) {
+  if (!Array.isArray(pins) || pins.length !== 4) {
+    throw new Error('Source cleanup identity changed');
+  }
+  for (const pin of pins) {
+    const location = pin.path;
+    if (typeof location !== 'string' || !path.isAbsolute(location) || /[\x00\r\n]/.test(location)
+        || location.split(path.sep).includes('..')) throw new Error('Source cleanup runtime changed');
+    const current = await fs.lstat(location);
+    if (!await soleRegularFile(location, current) || current.dev !== pin.identity?.device
+        || current.ino !== pin.identity?.inode || await sha256File(location) !== pin.sha256) {
+      throw new Error('Source cleanup runtime changed');
     }
   }
-  return launch(selected[0], selected.slice(1), environment, options);
 }
 
 module.exports = { registration, npmProgram, removeRegistration, explicitApply, descriptor, resumeWithoutRuntime, registrationOnly };

package/packaging/npm/release.json

@@ -1,35 +1,35 @@
 {
   "schema": 1,
-  "version": "0.5.98",
-  "commit": "4c23b408dfb8e87b7bb93154b895769fa17c4af3",
+  "version": "0.5.99",
+  "commit": "90aae4864b24be65ebfb31fcf6fe17b9d5b28cb5",
   "repository": "Shinick-Han/stackbite",
   "platforms": {
     "win32-x64": {
-      "asset": "stackbite-0.5.98-windows-x64-4c23b408dfb8.zip",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.98/stackbite-0.5.98-windows-x64-4c23b408dfb8.zip",
-      "sha256": "3b587ba43f67158a14e55ee4d4c9431f93cc0b576360d42e281ecc4736ae6f6d",
-      "size": 95796531,
-      "root": "stackbite-0.5.98-windows-x64-4c23b408dfb8",
-      "manifestSha256": "6e5c387b3af706690f372b831dab60ca923211ffb02d481c9bda3c40a599fd1c",
-      "metadataSha256": "152b7c85dccafc2cedb9ce8ea498f4a26e43834c534f6dd086d047d7539b05c1"
+      "asset": "stackbite-0.5.99-windows-x64-90aae4864b24.zip",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.99/stackbite-0.5.99-windows-x64-90aae4864b24.zip",
+      "sha256": "1d2e469d71802398b095a1ef77abe26050c7a43523005119449e01108350f13c",
+      "size": 95935897,
+      "root": "stackbite-0.5.99-windows-x64-90aae4864b24",
+      "manifestSha256": "4544eb749c94ef633748650466298a013cbf950533e42a54c3fc1a87537e0475",
+      "metadataSha256": "91e564369939e31d1e2e5d549d1185fc081b2ad80e478fa0d0658f8870898b70"
     },
     "linux-x64": {
-      "asset": "stackbite-0.5.98-linux-x86_64-4c23b408dfb8.tar.gz",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.98/stackbite-0.5.98-linux-x86_64-4c23b408dfb8.tar.gz",
-      "sha256": "eaf429b2521cbbb7f7f3675379f855ec5f62510f10c1ab2f1d3f0dec413b6eb3",
-      "size": 76072178,
-      "root": "stackbite-0.5.98-linux-x86_64-4c23b408dfb8",
-      "manifestSha256": "1542d61e5aaee722b99bfefe04274b11e6287caa6924dc4c5f2fc7157c5842d3",
-      "metadataSha256": "5d0a1ec2ca0c26f3119bfc68e70bd102890313099e961ee7ba65f3da661eee8b"
+      "asset": "stackbite-0.5.99-linux-x86_64-90aae4864b24.tar.gz",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.99/stackbite-0.5.99-linux-x86_64-90aae4864b24.tar.gz",
+      "sha256": "84e78372b8ef337480fe230a4eaf4cf2ff39048ff8af2c21929e8b4535122d5a",
+      "size": 76221146,
+      "root": "stackbite-0.5.99-linux-x86_64-90aae4864b24",
+      "manifestSha256": "a892cd3e8ff2d338e6bd8580df67b357b7e15b2129107d359d97e12cb98d1673",
+      "metadataSha256": "441c8da312ee420767e761665c83753018a01e20d2d954670f43bdc640a1369c"
     },
     "darwin-arm64": {
-      "asset": "stackbite-0.5.98-macos-arm64-4c23b408dfb8.tar.gz",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.98/stackbite-0.5.98-macos-arm64-4c23b408dfb8.tar.gz",
-      "sha256": "56e4f20164b0163cde0be464349165944a7b333e223b1e4091ed60ba1476b1c2",
-      "size": 31031692,
-      "root": "stackbite-0.5.98-macos-arm64-4c23b408dfb8",
-      "manifestSha256": "b833a1fbc7bbe6a8bdfa3aa69c9c2f8e35dc8be5a8bf9ed7d3fa2756e9316478",
-      "metadataSha256": "93c06432dffb83f1afa72cda84e7f441482314fc67c2d511855b50ab4f014629"
+      "asset": "stackbite-0.5.99-macos-arm64-90aae4864b24.tar.gz",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.99/stackbite-0.5.99-macos-arm64-90aae4864b24.tar.gz",
+      "sha256": "e40810f5c5b18728bddbc494e27c89d46b32ce4eb3c0db4fe5bca1b0f0e712f8",
+      "size": 31167159,
+      "root": "stackbite-0.5.99-macos-arm64-90aae4864b24",
+      "manifestSha256": "49b23c300843d261c6195b252cb6d10dec2810795fc6d7a599d57d71d6a3d288",
+      "metadataSha256": "5768005ea1b1c5beecbc3f5933818db04f2f5cdd533f29b511ad6e0d6af46b19"
     }
   }
 }