workbite 0.1.21 → 0.1.24

package/lib/install.js

@@ -1,274 +1,274 @@
-'use strict';
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const os = require('node:os');
-const { performance } = require('node:perf_hooks');
-const { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory, sha256 } = require('./common');
-const { download } = require('./download');
-const { extractArchive, diagnosticText, TOP_DIRECTORIES, BUNDLE } = require('./archive');
-const packageVersion = require('../package.json').version;
-
-const REPOSITORY = 'Shinick-Han/WorkBite-releases';
-const TARGETS = Object.freeze({ 'win32-x64': 'windows-x64', 'linux-x64': 'linux-x64' });
-const EXECUTABLES = Object.freeze({
-  workstack_engine: 'workstack/workstack-native-engine',
-  workstack_client: 'workstack/workstack-native-client',
-  workstack_tui: 'workstack/workstack-tui',
-  stackbite: 'stackbite/stackbite',
-});
-// Exact executable roster per bundle schema: v1 keeps the four legacy entries; v2 adds only the
-// same-window execution UI (proprietary assembly binary workstack-native-tui). Any other schema is refused.
-const BUNDLE_V1 = 'workbite.bundle.v1';
-const BUNDLE_V2 = 'workbite.bundle.v2';
-const ROSTERS = Object.freeze({
-  [BUNDLE_V1]: EXECUTABLES,
-  [BUNDLE_V2]: Object.freeze({ ...EXECUTABLES, workbite_tui: 'workstack/workstack-native-tui' }),
-});
-
-function absoluteOverride(environment, name) {
-  const value = environment[name];
-  if (value === undefined || value === '') return undefined;
-  if (!path.isAbsolute(value) || /[\x00-\x1f]/.test(value)) fail(`${name} must be an absolute path`);
-  return path.resolve(value);
-}
-// Per-user locations owned by WorkBite only; existing Work Stack/StackBite locations are never used.
-function locations(environment = process.env, platform = process.platform, home = os.homedir()) {
-  const windows = platform === 'win32';
-  const local = windows ? (environment.LOCALAPPDATA || path.join(home, 'AppData', 'Local')) : undefined;
-  const data = absoluteOverride(environment, 'WORKBITE_HOME') || (windows ? path.resolve(local, 'WorkBite')
-    : path.resolve(environment.XDG_DATA_HOME || path.join(environment.HOME || home, '.local', 'share'), 'workbite'));
-  const state = absoluteOverride(environment, 'WORKBITE_STATE_DIR') || (windows ? path.resolve(local, 'WorkBite', 'state')
-    : path.resolve(environment.XDG_STATE_HOME || path.join(environment.HOME || home, '.local', 'state'), 'workbite'));
-  return { apps: path.join(data, 'app'), state };
-}
-
-function platformTarget(platform = process.platform, arch = process.arch, runtime = {}) {
-  const key = `${platform}-${arch}`;
-  const target = TARGETS[key];
-  if (!target) fail(`WorkBite has no native release for ${key}; supported platforms are Windows x64 and Linux x64 (glibc 2.28+). Nothing was downloaded.`);
-  if (platform === 'linux' && (process.platform === 'linux' || Object.hasOwn(runtime, 'glibcVersionRuntime'))) {
-    const glibc = Object.hasOwn(runtime, 'glibcVersionRuntime')
-      ? runtime.glibcVersionRuntime : process.report.getReport().header.glibcVersionRuntime;
-    const match = typeof glibc === 'string' ? /^(\d+)\.(\d+)/.exec(glibc) : null;
-    if (!match) fail('WorkBite requires Linux x64 with glibc; Alpine/musl Linux is unsupported. Nothing was downloaded.');
-    if (Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 28)) {
-      fail(`WorkBite requires glibc 2.28 or newer; this system has ${glibc}. Nothing was downloaded.`);
-    }
-  }
-  return target;
-}
-
-const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
-function canonicalVersion(value) { return typeof value === 'string' && SEMVER.test(value); }
-
-// manifest.version names the sealed native artifact (asset, tag, URL, bundle, cache directory).
-// An explicit launcherVersion lets a launcher-only npm patch reuse that artifact unchanged;
-// without it the legacy binding (artifact version == package version) still applies.
-function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}, launcher = packageVersion) {
-  const target = platformTarget(platform, arch, runtime);
-  const bound = Object.hasOwn(manifest, 'launcherVersion')
-    ? canonicalVersion(manifest.launcherVersion) && manifest.launcherVersion === launcher
-    : manifest.version === launcher;
-  if (manifest.schema !== 'workbite.release.v1' || manifest.product !== 'WorkBite' || !canonicalVersion(manifest.version) || !bound
-      || manifest.repository !== REPOSITORY || manifest.tag !== `v${manifest.version}`) fail('Invalid pinned WorkBite release identity');
-  const spec = manifest.platforms?.[target];
-  const asset = `workbite-${manifest.version}-${target}${platform === 'win32' ? '.zip' : '.tar.gz'}`;
-  if (!spec || spec.asset !== asset
-      || spec.url !== `https://github.com/${manifest.repository}/releases/download/${manifest.tag}/${asset}`) fail('Invalid pinned release asset');
-  if (spec.sha256 === null || spec.size === null || spec.bundleSha256 === null) {
-    fail(`This workbite ${launcher} package has no sealed ${target} release artifact yet. Nothing was downloaded.`);
-  }
-  if (![spec.sha256, spec.bundleSha256].every(value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value))
-      || !Number.isSafeInteger(spec.size) || spec.size <= 0 || spec.size > LIMITS.download) fail('Invalid pinned release asset');
-  return { asset, url: spec.url, sha256: spec.sha256, size: spec.size, bundleSha256: spec.bundleSha256,
-    platform, target, version: manifest.version };
-}
-
-function expectedExecutables(spec, schema = BUNDLE_V1) {
-  if (!Object.hasOwn(ROSTERS, schema)) fail('bundle.json identity or executable layout mismatch');
-  const suffix = spec.platform === 'win32' ? '.exe' : '';
-  return Object.fromEntries(Object.entries(ROSTERS[schema]).map(([name, file]) => [name, file + suffix]));
-}
-function plainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
-function sameKeys(value, keys) {
-  return plainObject(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
-}
-
-// Full payload proof: pinned bundle.json bytes, then every regular file against its map, with no extras.
-async function validateBundle(directory, spec) {
-  const info = await fs.lstat(directory);
-  if (!info.isDirectory() || info.isSymbolicLink()) fail('Installed WorkBite root is not a regular directory');
-  const root = await fs.realpath(directory);
-  const bundleBytes = await readSmall(path.join(root, BUNDLE));
-  if (sha256(bundleBytes) !== spec.bundleSha256) fail('Pinned bundle.json SHA-256 mismatch');
-  let bundle;
-  try { bundle = JSON.parse(bundleBytes.toString('utf8')); } catch { fail('bundle.json is not valid JSON'); }
-  if (!plainObject(bundle) || !Object.hasOwn(ROSTERS, bundle.schema)) fail('bundle.json identity or executable layout mismatch');
-  const executables = expectedExecutables(spec, bundle.schema);
-  // Optional reviewed Windows mobile assembly. Older v1/v2 bundles keep their exact roster.
-  // A mobile entry is accepted only at this fixed path and receives the same full hash/magic proof.
-  if (bundle.schema === BUNDLE_V2 && spec.platform === 'win32' && Object.hasOwn(bundle.executables || {}, 'workbite_mobile')) {
-    executables.workbite_mobile = 'workstack/workbite-mobile.exe';
-  }
-  if (bundle.product !== 'WorkBite'
-      || bundle.version !== spec.version || bundle.target !== spec.target || !plainObject(bundle.components)
-      || !sameKeys(bundle.executables, Object.keys(executables))
-      || Object.entries(executables).some(([name, file]) => bundle.executables[name] !== file)
-      || !plainObject(bundle.files)) fail('bundle.json identity or executable layout mismatch');
-  const expected = new Map();
-  for (const [name, digest] of Object.entries(bundle.files)) {
-    if (memberPath(name) !== name || name === BUNDLE || !TOP_DIRECTORIES.includes(name.split('/')[0])
-        || !name.includes('/') || typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest)) fail('Invalid bundle file entry');
-    const key = spec.platform === 'win32' ? name.toLowerCase() : name;
-    if (expected.has(key)) fail('Duplicate bundle file entry');
-    expected.set(key, { name, digest });
-  }
-  if (!expected.size || expected.size > LIMITS.members) fail('Invalid bundle file map');
-  for (const file of Object.values(executables)) if (!Object.hasOwn(bundle.files, file)) fail('Bundle executable is not in its file map');
-  let total = 0, entries = 0, seen = 0;
-  async function visit(current) {
-    for (const name of await fs.readdir(current)) {
-      if (++entries > LIMITS.members * 2) fail('Installed WorkBite has too many entries');
-      const target = path.join(current, name);
-      const relative = path.relative(root, target).split(path.sep).join('/');
-      memberPath(relative);
-      const entry = await fs.lstat(target);
-      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) fail('Installed WorkBite contains a link or special file');
-      if (entry.isDirectory()) {
-        if (current === root && !TOP_DIRECTORIES.includes(name)) fail('Installed WorkBite has an unexpected top-level directory');
-        await visit(target); continue;
-      }
-      if (relative === BUNDLE) continue;
-      const record = expected.get(spec.platform === 'win32' ? relative.toLowerCase() : relative);
-      if (!record || record.name !== relative) fail(`Installed file is not in bundle.json: ${relative}`);
-      total += entry.size;
-      if (total > LIMITS.expanded) fail('Installed WorkBite exceeds expansion limit');
-      if (await hashFile(target) !== record.digest) fail(`Installed file SHA-256 mismatch: ${relative}`);
-      seen++;
-    }
-  }
-  await visit(root);
-  if (seen !== expected.size) fail('Installed files disagree with bundle.json');
-  const paths = {};
-  for (const [name, file] of Object.entries(executables)) {
-    const executable = path.join(root, ...file.split('/'));
-    const handle = await fs.open(executable, 'r');
-    try {
-      const magic = Buffer.alloc(4);
-      if ((await handle.read(magic, 0, 4, 0)).bytesRead !== 4
-          || !(spec.platform === 'win32' ? magic.subarray(0, 2).equals(Buffer.from('MZ')) : magic.equals(Buffer.from([0x7f, 69, 76, 70])))) {
-        fail(`Invalid native executable identity: ${file}`);
-      }
-    } finally { await handle.close(); }
-    if (spec.platform === 'linux' && process.platform !== 'win32' && !((await fs.stat(executable)).mode & 0o111)) {
-      fail(`Native executable has no execute permission: ${file}`);
-    }
-    paths[name] = executable;
-  }
-  return { home: root, executables: paths, bundle };
-}
-
-function installName(spec) { return `${spec.version}-${spec.target}-${spec.sha256.slice(0, 16)}`; }
-
-// Windows cannot start bundle executables (or load their files) past MAX_PATH.
-const WINDOWS_MAX_PATH = 259;
-function checkPathBudget(target, bundle, spec) {
-  if (spec.platform !== 'win32') return;
-  const longest = Object.keys(bundle.files).reduce((best, name) => (name.length > best.length ? name : best), '');
-  if (path.join(target, longest).length > WINDOWS_MAX_PATH) {
-    fail(`WorkBite app folder path is too long for Windows (${path.join(target, longest).length} > ${WINDOWS_MAX_PATH} characters); set WORKBITE_HOME to a shorter absolute folder.`);
-  }
-}
-
-// A version directory is published once by rename and never rewritten; reuse revalidates it fully.
-async function installVersion(spec, { apps, downloadImpl = download, extractImpl = extractArchive,
-  checkOnly = false, progress = () => {} } = {}) {
-  apps = path.resolve(apps);
-  const target = path.join(apps, installName(spec));
-  if (await exists(target)) {
-    progress('validate');
-    const installed = await validateBundle(target, spec);
-    checkPathBudget(target, installed.bundle, spec);
-    progress('ready');
-    return installed;
-  }
-  if (checkOnly) fail('WorkBite is not installed for this package version; run workbite install.');
-  await safeDirectory(apps);
-  const staging = await fs.mkdtemp(path.join(apps, '.staging-'));
-  let cleanup = true;
-  try {
-    const archive = path.join(staging, spec.asset), extraction = path.join(staging, 'payload');
-    await fs.mkdir(extraction, { mode: 0o700 });
-    progress('download');
-    await downloadImpl(spec, archive);
-    progress('archive');
-    if ((await fs.stat(archive)).size !== spec.size || await hashFile(archive, LIMITS.download) !== spec.sha256) fail('Pinned archive SHA-256 or size mismatch');
-    progress('extract');
-    await extractImpl(archive, extraction, spec);
-    progress('validate');
-    checkPathBudget(target, (await validateBundle(extraction, spec)).bundle, spec);
-    progress('publish');
-    try { await fs.rename(extraction, target); }
-    catch (error) {
-      // A concurrent installer may have published the same immutable version first.
-      if (!await exists(target)) throw error;
-    }
-    progress('validate-published');
-    const installed = await validateBundle(target, spec);
-    progress('ready');
-    return installed;
-  } catch (error) {
-    if (error.extractionMayBeRunning) cleanup = false;
-    throw error;
-  } finally {
-    // Only this invocation's mkdtemp staging directory is ever removed.
-    if (!inside(apps, staging) || path.dirname(staging) !== apps) fail('Unsafe staging cleanup path');
-    if (cleanup) await fs.rm(staging, { recursive: true, force: true });
-  }
-}
-
-// Keep progress on stderr through the existing reporter; stdout remains the
-// workbite.install.v1 document. Every reuse still performs full hash validation.
-async function ensureInstalled(spec, options = {}) {
-  const apps = path.resolve(options.apps);
-  const target = path.join(apps, installName(spec));
-  const started = performance.now();
-  let verifying, verificationMs = 0;
-  const progress = stage => {
-    const now = performance.now();
-    if (verifying !== undefined) { verificationMs += now - verifying; verifying = undefined; }
-    if (stage === 'validate' || stage === 'validate-published') verifying = now;
-    (options.progress || (() => {}))(stage, { elapsedMs: Math.round(now - started),
-      verificationMs: Math.round(verificationMs), home: target, apps });
-  };
-  try {
-    return await installVersion(spec, { ...options, apps, progress });
-  } catch (error) {
-    const failure = new Error(`${diagnosticText(error.message, 8192)} Installation path: ${diagnosticText(target)} (apps: ${diagnosticText(apps)}); elapsed: ${Math.round(performance.now() - started)} ms.`);
-    for (const key of ['code', 'exitCode', 'signal']) {
-      if (typeof error[key] === 'string') failure[key] = diagnosticText(error[key], 64);
-      else if (error[key] === null || typeof error[key] === 'number') failure[key] = error[key];
-    }
-    throw failure;
-  }
-}
-
-function stageReporter(stderr) {
-  const messages = {
-    download: 'Downloading pinned WorkBite release...',
-    archive: 'Verifying archive...',
-    extract: 'Extracting...',
-    validate: 'Validating installed files...',
-    publish: 'Publishing version directory...',
-    'validate-published': 'Validating published version...',
-    ready: 'Verified WorkBite release is ready.',
-  };
-  return (stage, details) => {
-    const timing = stage === 'ready' && details
-      ? ` Elapsed: ${details.elapsedMs} ms; file verification: ${details.verificationMs} ms; home: ${diagnosticText(details.home)}.` : '';
-    stderr.write(`WorkBite: ${messages[stage]}${timing}\n`);
-  };
-}
-
-module.exports = { REPOSITORY, TARGETS, EXECUTABLES, BUNDLE_V1, BUNDLE_V2, ROSTERS, locations, platformTarget, releaseSpec, expectedExecutables,
-  validateBundle, ensureInstalled, installName, stageReporter, packageVersion };
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { performance } = require('node:perf_hooks');
+const { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory, sha256 } = require('./common');
+const { download } = require('./download');
+const { extractArchive, diagnosticText, TOP_DIRECTORIES, BUNDLE } = require('./archive');
+const packageVersion = require('../package.json').version;
+
+const REPOSITORY = 'Shinick-Han/WorkBite-releases';
+const TARGETS = Object.freeze({ 'win32-x64': 'windows-x64', 'linux-x64': 'linux-x64' });
+const EXECUTABLES = Object.freeze({
+  workstack_engine: 'workstack/workstack-native-engine',
+  workstack_client: 'workstack/workstack-native-client',
+  workstack_tui: 'workstack/workstack-tui',
+  stackbite: 'stackbite/stackbite',
+});
+// Exact executable roster per bundle schema: v1 keeps the four legacy entries; v2 adds only the
+// same-window execution UI (proprietary assembly binary workstack-native-tui). Any other schema is refused.
+const BUNDLE_V1 = 'workbite.bundle.v1';
+const BUNDLE_V2 = 'workbite.bundle.v2';
+const ROSTERS = Object.freeze({
+  [BUNDLE_V1]: EXECUTABLES,
+  [BUNDLE_V2]: Object.freeze({ ...EXECUTABLES, workbite_tui: 'workstack/workstack-native-tui' }),
+});
+
+function absoluteOverride(environment, name) {
+  const value = environment[name];
+  if (value === undefined || value === '') return undefined;
+  if (!path.isAbsolute(value) || /[\x00-\x1f]/.test(value)) fail(`${name} must be an absolute path`);
+  return path.resolve(value);
+}
+// Per-user locations owned by WorkBite only; existing Work Stack/StackBite locations are never used.
+function locations(environment = process.env, platform = process.platform, home = os.homedir()) {
+  const windows = platform === 'win32';
+  const local = windows ? (environment.LOCALAPPDATA || path.join(home, 'AppData', 'Local')) : undefined;
+  const data = absoluteOverride(environment, 'WORKBITE_HOME') || (windows ? path.resolve(local, 'WorkBite')
+    : path.resolve(environment.XDG_DATA_HOME || path.join(environment.HOME || home, '.local', 'share'), 'workbite'));
+  const state = absoluteOverride(environment, 'WORKBITE_STATE_DIR') || (windows ? path.resolve(local, 'WorkBite', 'state')
+    : path.resolve(environment.XDG_STATE_HOME || path.join(environment.HOME || home, '.local', 'state'), 'workbite'));
+  return { apps: path.join(data, 'app'), state };
+}
+
+function platformTarget(platform = process.platform, arch = process.arch, runtime = {}) {
+  const key = `${platform}-${arch}`;
+  const target = TARGETS[key];
+  if (!target) fail(`WorkBite has no native release for ${key}; supported platforms are Windows x64 and Linux x64 (glibc 2.28+). Nothing was downloaded.`);
+  if (platform === 'linux' && (process.platform === 'linux' || Object.hasOwn(runtime, 'glibcVersionRuntime'))) {
+    const glibc = Object.hasOwn(runtime, 'glibcVersionRuntime')
+      ? runtime.glibcVersionRuntime : process.report.getReport().header.glibcVersionRuntime;
+    const match = typeof glibc === 'string' ? /^(\d+)\.(\d+)/.exec(glibc) : null;
+    if (!match) fail('WorkBite requires Linux x64 with glibc; Alpine/musl Linux is unsupported. Nothing was downloaded.');
+    if (Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 28)) {
+      fail(`WorkBite requires glibc 2.28 or newer; this system has ${glibc}. Nothing was downloaded.`);
+    }
+  }
+  return target;
+}
+
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function canonicalVersion(value) { return typeof value === 'string' && SEMVER.test(value); }
+
+// manifest.version names the sealed native artifact (asset, tag, URL, bundle, cache directory).
+// An explicit launcherVersion lets a launcher-only npm patch reuse that artifact unchanged;
+// without it the legacy binding (artifact version == package version) still applies.
+function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}, launcher = packageVersion) {
+  const target = platformTarget(platform, arch, runtime);
+  const bound = Object.hasOwn(manifest, 'launcherVersion')
+    ? canonicalVersion(manifest.launcherVersion) && manifest.launcherVersion === launcher
+    : manifest.version === launcher;
+  if (manifest.schema !== 'workbite.release.v1' || manifest.product !== 'WorkBite' || !canonicalVersion(manifest.version) || !bound
+      || manifest.repository !== REPOSITORY || manifest.tag !== `v${manifest.version}`) fail('Invalid pinned WorkBite release identity');
+  const spec = manifest.platforms?.[target];
+  const asset = `workbite-${manifest.version}-${target}${platform === 'win32' ? '.zip' : '.tar.gz'}`;
+  if (!spec || spec.asset !== asset
+      || spec.url !== `https://github.com/${manifest.repository}/releases/download/${manifest.tag}/${asset}`) fail('Invalid pinned release asset');
+  if (spec.sha256 === null || spec.size === null || spec.bundleSha256 === null) {
+    fail(`This workbite ${launcher} package has no sealed ${target} release artifact yet. Nothing was downloaded.`);
+  }
+  if (![spec.sha256, spec.bundleSha256].every(value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value))
+      || !Number.isSafeInteger(spec.size) || spec.size <= 0 || spec.size > LIMITS.download) fail('Invalid pinned release asset');
+  return { asset, url: spec.url, sha256: spec.sha256, size: spec.size, bundleSha256: spec.bundleSha256,
+    platform, target, version: manifest.version };
+}
+
+function expectedExecutables(spec, schema = BUNDLE_V1) {
+  if (!Object.hasOwn(ROSTERS, schema)) fail('bundle.json identity or executable layout mismatch');
+  const suffix = spec.platform === 'win32' ? '.exe' : '';
+  return Object.fromEntries(Object.entries(ROSTERS[schema]).map(([name, file]) => [name, file + suffix]));
+}
+function plainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function sameKeys(value, keys) {
+  return plainObject(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+// Full payload proof: pinned bundle.json bytes, then every regular file against its map, with no extras.
+async function validateBundle(directory, spec) {
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Installed WorkBite root is not a regular directory');
+  const root = await fs.realpath(directory);
+  const bundleBytes = await readSmall(path.join(root, BUNDLE));
+  if (sha256(bundleBytes) !== spec.bundleSha256) fail('Pinned bundle.json SHA-256 mismatch');
+  let bundle;
+  try { bundle = JSON.parse(bundleBytes.toString('utf8')); } catch { fail('bundle.json is not valid JSON'); }
+  if (!plainObject(bundle) || !Object.hasOwn(ROSTERS, bundle.schema)) fail('bundle.json identity or executable layout mismatch');
+  const executables = expectedExecutables(spec, bundle.schema);
+  // Optional reviewed Windows mobile assembly. Older v1/v2 bundles keep their exact roster.
+  // A mobile entry is accepted only at this fixed path and receives the same full hash/magic proof.
+  if (bundle.schema === BUNDLE_V2 && spec.platform === 'win32' && Object.hasOwn(bundle.executables || {}, 'workbite_mobile')) {
+    executables.workbite_mobile = 'workstack/workbite-mobile.exe';
+  }
+  if (bundle.product !== 'WorkBite'
+      || bundle.version !== spec.version || bundle.target !== spec.target || !plainObject(bundle.components)
+      || !sameKeys(bundle.executables, Object.keys(executables))
+      || Object.entries(executables).some(([name, file]) => bundle.executables[name] !== file)
+      || !plainObject(bundle.files)) fail('bundle.json identity or executable layout mismatch');
+  const expected = new Map();
+  for (const [name, digest] of Object.entries(bundle.files)) {
+    if (memberPath(name) !== name || name === BUNDLE || !TOP_DIRECTORIES.includes(name.split('/')[0])
+        || !name.includes('/') || typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest)) fail('Invalid bundle file entry');
+    const key = spec.platform === 'win32' ? name.toLowerCase() : name;
+    if (expected.has(key)) fail('Duplicate bundle file entry');
+    expected.set(key, { name, digest });
+  }
+  if (!expected.size || expected.size > LIMITS.members) fail('Invalid bundle file map');
+  for (const file of Object.values(executables)) if (!Object.hasOwn(bundle.files, file)) fail('Bundle executable is not in its file map');
+  let total = 0, entries = 0, seen = 0;
+  async function visit(current) {
+    for (const name of await fs.readdir(current)) {
+      if (++entries > LIMITS.members * 2) fail('Installed WorkBite has too many entries');
+      const target = path.join(current, name);
+      const relative = path.relative(root, target).split(path.sep).join('/');
+      memberPath(relative);
+      const entry = await fs.lstat(target);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) fail('Installed WorkBite contains a link or special file');
+      if (entry.isDirectory()) {
+        if (current === root && !TOP_DIRECTORIES.includes(name)) fail('Installed WorkBite has an unexpected top-level directory');
+        await visit(target); continue;
+      }
+      if (relative === BUNDLE) continue;
+      const record = expected.get(spec.platform === 'win32' ? relative.toLowerCase() : relative);
+      if (!record || record.name !== relative) fail(`Installed file is not in bundle.json: ${relative}`);
+      total += entry.size;
+      if (total > LIMITS.expanded) fail('Installed WorkBite exceeds expansion limit');
+      if (await hashFile(target) !== record.digest) fail(`Installed file SHA-256 mismatch: ${relative}`);
+      seen++;
+    }
+  }
+  await visit(root);
+  if (seen !== expected.size) fail('Installed files disagree with bundle.json');
+  const paths = {};
+  for (const [name, file] of Object.entries(executables)) {
+    const executable = path.join(root, ...file.split('/'));
+    const handle = await fs.open(executable, 'r');
+    try {
+      const magic = Buffer.alloc(4);
+      if ((await handle.read(magic, 0, 4, 0)).bytesRead !== 4
+          || !(spec.platform === 'win32' ? magic.subarray(0, 2).equals(Buffer.from('MZ')) : magic.equals(Buffer.from([0x7f, 69, 76, 70])))) {
+        fail(`Invalid native executable identity: ${file}`);
+      }
+    } finally { await handle.close(); }
+    if (spec.platform === 'linux' && process.platform !== 'win32' && !((await fs.stat(executable)).mode & 0o111)) {
+      fail(`Native executable has no execute permission: ${file}`);
+    }
+    paths[name] = executable;
+  }
+  return { home: root, executables: paths, bundle };
+}
+
+function installName(spec) { return `${spec.version}-${spec.target}-${spec.sha256.slice(0, 16)}`; }
+
+// Windows cannot start bundle executables (or load their files) past MAX_PATH.
+const WINDOWS_MAX_PATH = 259;
+function checkPathBudget(target, bundle, spec) {
+  if (spec.platform !== 'win32') return;
+  const longest = Object.keys(bundle.files).reduce((best, name) => (name.length > best.length ? name : best), '');
+  if (path.join(target, longest).length > WINDOWS_MAX_PATH) {
+    fail(`WorkBite app folder path is too long for Windows (${path.join(target, longest).length} > ${WINDOWS_MAX_PATH} characters); set WORKBITE_HOME to a shorter absolute folder.`);
+  }
+}
+
+// A version directory is published once by rename and never rewritten; reuse revalidates it fully.
+async function installVersion(spec, { apps, downloadImpl = download, extractImpl = extractArchive,
+  checkOnly = false, progress = () => {} } = {}) {
+  apps = path.resolve(apps);
+  const target = path.join(apps, installName(spec));
+  if (await exists(target)) {
+    progress('validate');
+    const installed = await validateBundle(target, spec);
+    checkPathBudget(target, installed.bundle, spec);
+    progress('ready');
+    return installed;
+  }
+  if (checkOnly) fail('WorkBite is not installed for this package version; run workbite install.');
+  await safeDirectory(apps);
+  const staging = await fs.mkdtemp(path.join(apps, '.staging-'));
+  let cleanup = true;
+  try {
+    const archive = path.join(staging, spec.asset), extraction = path.join(staging, 'payload');
+    await fs.mkdir(extraction, { mode: 0o700 });
+    progress('download');
+    await downloadImpl(spec, archive);
+    progress('archive');
+    if ((await fs.stat(archive)).size !== spec.size || await hashFile(archive, LIMITS.download) !== spec.sha256) fail('Pinned archive SHA-256 or size mismatch');
+    progress('extract');
+    await extractImpl(archive, extraction, spec);
+    progress('validate');
+    checkPathBudget(target, (await validateBundle(extraction, spec)).bundle, spec);
+    progress('publish');
+    try { await fs.rename(extraction, target); }
+    catch (error) {
+      // A concurrent installer may have published the same immutable version first.
+      if (!await exists(target)) throw error;
+    }
+    progress('validate-published');
+    const installed = await validateBundle(target, spec);
+    progress('ready');
+    return installed;
+  } catch (error) {
+    if (error.extractionMayBeRunning) cleanup = false;
+    throw error;
+  } finally {
+    // Only this invocation's mkdtemp staging directory is ever removed.
+    if (!inside(apps, staging) || path.dirname(staging) !== apps) fail('Unsafe staging cleanup path');
+    if (cleanup) await fs.rm(staging, { recursive: true, force: true });
+  }
+}
+
+// Keep progress on stderr through the existing reporter; stdout remains the
+// workbite.install.v1 document. Every reuse still performs full hash validation.
+async function ensureInstalled(spec, options = {}) {
+  const apps = path.resolve(options.apps);
+  const target = path.join(apps, installName(spec));
+  const started = performance.now();
+  let verifying, verificationMs = 0;
+  const progress = stage => {
+    const now = performance.now();
+    if (verifying !== undefined) { verificationMs += now - verifying; verifying = undefined; }
+    if (stage === 'validate' || stage === 'validate-published') verifying = now;
+    (options.progress || (() => {}))(stage, { elapsedMs: Math.round(now - started),
+      verificationMs: Math.round(verificationMs), home: target, apps });
+  };
+  try {
+    return await installVersion(spec, { ...options, apps, progress });
+  } catch (error) {
+    const failure = new Error(`${diagnosticText(error.message, 8192)} Installation path: ${diagnosticText(target)} (apps: ${diagnosticText(apps)}); elapsed: ${Math.round(performance.now() - started)} ms.`);
+    for (const key of ['code', 'exitCode', 'signal']) {
+      if (typeof error[key] === 'string') failure[key] = diagnosticText(error[key], 64);
+      else if (error[key] === null || typeof error[key] === 'number') failure[key] = error[key];
+    }
+    throw failure;
+  }
+}
+
+function stageReporter(stderr) {
+  const messages = {
+    download: 'Downloading pinned WorkBite release...',
+    archive: 'Verifying archive...',
+    extract: 'Extracting...',
+    validate: 'Validating installed files...',
+    publish: 'Publishing version directory...',
+    'validate-published': 'Validating published version...',
+    ready: 'Verified WorkBite release is ready.',
+  };
+  return (stage, details) => {
+    const timing = stage === 'ready' && details
+      ? ` Elapsed: ${details.elapsedMs} ms; file verification: ${details.verificationMs} ms; home: ${diagnosticText(details.home)}.` : '';
+    stderr.write(`WorkBite: ${messages[stage]}${timing}\n`);
+  };
+}
+
+module.exports = { REPOSITORY, TARGETS, EXECUTABLES, BUNDLE_V1, BUNDLE_V2, ROSTERS, locations, platformTarget, releaseSpec, expectedExecutables,
+  validateBundle, ensureInstalled, installName, stageReporter, packageVersion };