stackbite 0.0.0-stage → 0.5.11

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# Stackbite through npm and npx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Work Stack organizes the work. Stackbite gets it moving.
+
+Node.js 20 or newer is required. The portable runtime is available for Windows x64
+and Linux x64 with glibc; macOS, ARM and musl/Alpine builds are not supplied yet.
+Python installation and compilation are unnecessary. Archive extraction requires
+`tar` (included in current Windows and common Linux distributions).
+
+## Install without an account
+
+The public npm package is available as `stackbite`:
+
+```sh
+npx --yes stackbite
+npm install --global stackbite
+stackbite
+```
+
+Update a registry installation with `npm install --global stackbite@latest`.
+
+## Direct GitHub package
+
+Run the package attached to the verified GitHub release:
+
+```sh
+npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.11/stackbite-0.5.11.tgz
+```
+
+Arguments go after the package URL, for example `--version` or `--status`. For a
+persistent command, install that same package globally:
+
+```sh
+npm install --global https://github.com/Shinick-Han/stackbite/releases/download/v0.5.11/stackbite-0.5.11.tgz
+stackbite
+```
+
+The core source repository remains private at `Shinick-Han/helm`. The separate
+public `Shinick-Han/stackbite` repository distributes only this thin launcher and
+verified compiled runtime releases; installers need no GitHub or npm login.
+Registry-free distribution does not require publishing rights on npm.
+The small JavaScript package downloads the
+exact pinned native release on first execution, verifies its archive and file
+checksums and product identity, then reuses a persistent binary cache. There is no
+postinstall download or provider installation. An offline cached launch is possible;
+the first launch needs access to GitHub release downloads.
+
+For a GitHub URL installation, install the package URL from the newer release.
+Each npm package pins one native release; the portable app's own `stackbite update`
+does not change the npm package version.
+
+## Existing data and processes
+
+`STACKBITE_STATE_DIR` is the explicit state override. The bundled native runtime
+owns state discovery and migration for both npm and direct launches. It reuses
+existing configured state and keeps live databases, authentication and records
+in place. New state uses `%LOCALAPPDATA%\Stackbite\state` or
+`${XDG_STATE_HOME:-~/.local/state}/stackbite`.
+Rooms, Seats, authentication, provider configuration, journals and Work Stack
+contracts are not renamed or migrated. Binary cache data is separate from this
+state. Installing or launching the npm package does not stop an existing backend.
+Check the connected server's capabilities before using newly added runtime features.
+
+The launcher inherits terminal input/output and passes CLI arguments directly to
+the native app. It does not insert a second screen renderer or an agent provider.
+Global npm installation creates only the `stackbite` command; it does not claim an
+external `helm` command or replace independent Kubernetes tooling.
+
+## Maintainer release steps
+
+Build and verify both native platform archives first. Prepare the pinned manifest
+from their exact extracted bundles and archive bytes:
+
+```sh
+python scripts/prepare_npm_release.py --version 0.5.11
+npm test
+npm pack
+```
+
+Keep `package.json` and `packaging/npm/release.json` versions equal. Inspect `npm
+pack --dry-run` before publishing; the package must include the launcher and pinned
+manifest, and exclude native runtimes, installed state, credentials, tests and
+development worktrees. Test the packed package with `npx` on both platforms.
+
+Attach `stackbite-<version>.tgz` and its SHA-256 sidecar to the corresponding GitHub
+release in the public distribution repository. Copy only the npm file allowlist to
+that repository; never push the private core history, state, personal notes or
+credentials. Native archives must retain dependency license notices. Publishing
+the short name requires an authenticated owner account:
+
+```sh
+npm login --registry=https://registry.npmjs.org
+npm publish --access public --registry=https://registry.npmjs.org
+```
+
+Complete any registry-required authentication interactively; do not put credentials
+in this repository, prompts or package files. The repository currently specifies
+`UNLICENSED` for the JavaScript wrapper instead of inventing a license for the app;
+native runtime dependency notices remain in each platform archive.

package/package.json

@@ -1,6 +1,12 @@
-{
-  "name": "stackbite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "stackbite",
+  "version": "0.5.11",
+  "description": "Verified native Stackbite CLI bootstrapper",
+  "license": "UNLICENSED",
+  "engines": { "node": ">=20" },
+  "bin": { "stackbite": "packaging/npm/bin/stackbite.js" },
+  "files": ["packaging/npm/bin/", "packaging/npm/lib/", "packaging/npm/release.json"],
+  "scripts": { "test": "node --test packaging/npm/test/*.test.js" },
+  "repository": { "type": "git", "url": "https://github.com/Shinick-Han/stackbite.git" },
+  "homepage": "https://github.com/Shinick-Han/stackbite"
+}

package/packaging/npm/bin/stackbite.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+const { main } = require('../lib/bootstrap');
+main().then(({ code, signal }) => {
+  if (signal && process.platform !== 'win32') {
+    process.kill(process.pid, signal);
+  } else {
+    process.exitCode = code === null ? 1 : code;
+  }
+}).catch(error => {
+  console.error(`Stackbite: ${error.message}`);
+  process.exitCode = 1;
+});

package/packaging/npm/lib/archive.js

@@ -0,0 +1,226 @@
+'use strict';
+const fs = require('node:fs/promises');
+const { createReadStream, createWriteStream } = require('node:fs');
+const { createGunzip, createInflateRaw } = require('node:zlib');
+const { Transform, Writable } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const { LIMITS, fail, memberPath } = require('./common');
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+const crcTable = Uint32Array.from({ length: 256 }, (_, value) => {
+  for (let bit = 0; bit < 8; bit++) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
+  return value >>> 0;
+});
+
+async function readAt(file, offset, length) {
+  const bytes = Buffer.alloc(length);
+  const { bytesRead } = await file.read(bytes, 0, length, offset);
+  if (bytesRead !== length) fail('Truncated release archive');
+  return bytes;
+}
+function validateEntries(entries, root, windows) {
+  if (!entries.length || entries.length > LIMITS.members) fail('Invalid archive member count');
+  const names = new Map();
+  let expanded = 0;
+  for (const entry of entries) {
+    entry.name = memberPath(entry.name);
+    if (entry.name !== root && !entry.name.startsWith(root + '/')) fail('Archive member is outside its pinned root');
+    const key = windows ? entry.name.toLowerCase() : entry.name;
+    if (names.has(key)) fail('Duplicate archive member');
+    names.set(key, entry);
+    expanded += entry.size;
+    if (entry.size < 0 || entry.size > LIMITS.member || expanded > LIMITS.expanded) fail('Archive expansion exceeds limit');
+  }
+  for (const entry of entries) {
+    for (let parent = path.posix.dirname(entry.name); parent !== '.'; parent = path.posix.dirname(parent)) {
+      const ancestor = names.get(windows ? parent.toLowerCase() : parent);
+      if (ancestor && ancestor.kind !== 'directory') fail('Archive link/file is another member parent');
+    }
+    if (entry.kind === 'link') {
+      if (windows || !entry.link || entry.link.length > 1024 || /[\\:\x00-\x1f\x7f]/.test(entry.link)
+          || path.posix.isAbsolute(entry.link)) fail('Unsafe archive link');
+      const target = path.posix.normalize(path.posix.join(path.posix.dirname(entry.name), entry.link));
+      const destination = names.get(target);
+      if (!target.startsWith(root + '/') || !destination || destination.kind !== 'file') fail('Archive link is escaping, dangling or chained');
+    }
+  }
+  return entries;
+}
+async function zipEntries(archive) {
+  const file = await fs.open(archive, 'r');
+  const signal = AbortSignal.timeout(LIMITS.timeout);
+  try {
+    const size = (await file.stat()).size;
+    const tailStart = Math.max(0, size - 65557);
+    const tail = await readAt(file, tailStart, size - tailStart);
+    const end = tail.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+    if (end < 0 || end + 22 > tail.length) fail('Invalid ZIP directory');
+    const count = tail.readUInt16LE(end + 10), directorySize = tail.readUInt32LE(end + 12), offset = tail.readUInt32LE(end + 16);
+    if (tail.readUInt16LE(end + 4) || tail.readUInt16LE(end + 6) || tail.readUInt16LE(end + 8) !== count
+        || count === 65535 || count > LIMITS.members || directorySize > 16 * 1024 * 1024
+        || offset + directorySize !== tailStart + end || end + 22 + tail.readUInt16LE(end + 20) !== tail.length) fail('Unsafe ZIP directory');
+    const central = await readAt(file, offset, directorySize);
+    const entries = [], ranges = [];
+    let position = 0, totalExpanded = 0;
+    for (let index = 0; index < count; index++) {
+      signal.throwIfAborted();
+      if (position + 46 > central.length || central.readUInt32LE(position) !== 0x02014b50) fail('Invalid ZIP member');
+      const flags = central.readUInt16LE(position + 8), method = central.readUInt16LE(position + 10);
+      const compressed = central.readUInt32LE(position + 20), expanded = central.readUInt32LE(position + 24);
+      totalExpanded += expanded;
+      if (totalExpanded > LIMITS.expanded) fail('ZIP total expansion exceeds limit');
+      const nameSize = central.readUInt16LE(position + 28), extraSize = central.readUInt16LE(position + 30), commentSize = central.readUInt16LE(position + 32);
+      const localOffset = central.readUInt32LE(position + 42), mode = central.readUInt32LE(position + 38) >>> 16;
+      if (!nameSize || nameSize > 1024 || position + 46 + nameSize + extraSize + commentSize > central.length
+          || central.readUInt16LE(position + 34) || (flags & ~0x080e) || ![0, 8].includes(method)
+          || expanded > LIMITS.member || ![0, 0o100000, 0o040000].includes(mode & 0o170000) || (mode & 0o7000)) fail('Unsupported ZIP member');
+      const rawName = central.subarray(position + 46, position + 46 + nameSize);
+      if (!(flags & 0x0800) && rawName.some(value => value > 127)) fail('Ambiguous ZIP filename encoding');
+      const name = utf8.decode(rawName);
+      const directory = name.endsWith('/');
+      if (directory && (expanded || compressed)) fail('Invalid ZIP directory member');
+      const directoryMode = (mode & 0o170000) === 0o040000 || !!(central.readUInt32LE(position + 38) & 16);
+      if (directoryMode && !directory) fail('ZIP directory identity mismatch');
+      const local = await readAt(file, localOffset, 30);
+      const localNameSize = local.readUInt16LE(26), localExtraSize = local.readUInt16LE(28);
+      const dataStart = localOffset + 30 + localNameSize + localExtraSize;
+      if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== method
+          || localNameSize !== nameSize || dataStart + compressed > offset
+          || !(await readAt(file, localOffset + 30, localNameSize)).equals(rawName)) fail('ZIP local/central identity mismatch');
+      if (!(flags & 8) && (local.readUInt32LE(14) !== central.readUInt32LE(position + 16)
+          || local.readUInt32LE(18) !== compressed || local.readUInt32LE(22) !== expanded)) fail('ZIP local size mismatch');
+      if (!directory) {
+        // Bound the actual inflated bytes, not only the central-directory claim,
+        // before handing the same archive to the native extraction command.
+        if (method === 0 && compressed !== expanded) fail('Invalid stored ZIP size');
+        let actualSize = 0, crc = 0xffffffff;
+        const sink = new Writable({ write(chunk, encoding, callback) {
+          actualSize += chunk.length;
+          if (actualSize > expanded) return callback(new Error('ZIP expansion exceeds declared size'));
+          for (const byte of chunk) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 255];
+          callback();
+        } });
+        if (compressed) {
+          const input = createReadStream(archive, { start: dataStart, end: dataStart + compressed - 1 });
+          if (method === 8) await pipeline(input, createInflateRaw(), sink, { signal });
+          else await pipeline(input, sink, { signal });
+        }
+        if (actualSize !== expanded || ((crc ^ 0xffffffff) >>> 0) !== central.readUInt32LE(position + 16)) fail('ZIP content size/CRC mismatch');
+      }
+      // Reject Unicode-path/ZIP64 extra fields: native tar must use the same name
+      // and sizes checked here, without a second interpretation of this entry.
+      for (const extra of [central.subarray(position + 46 + nameSize, position + 46 + nameSize + extraSize),
+        await readAt(file, localOffset + 30 + localNameSize, localExtraSize)]) {
+        for (let at = 0; at < extra.length;) {
+          if (at + 4 > extra.length) fail('Invalid ZIP extra field');
+          const kind = extra.readUInt16LE(at), length = extra.readUInt16LE(at + 2);
+          if (![0x5455, 0x7875].includes(kind) || at + 4 + length > extra.length) fail('Unsupported ZIP extension');
+          at += 4 + length;
+        }
+      }
+      ranges.push([localOffset, dataStart + compressed]);
+      entries.push({ name, kind: directory ? 'directory' : 'file', size: expanded });
+      position += 46 + nameSize + extraSize + commentSize;
+    }
+    if (position !== central.length) fail('Extra ZIP directory records');
+    ranges.sort((a, b) => a[0] - b[0]);
+    if (ranges.some((range, index) => index && range[0] < ranges[index - 1][1])) fail('Overlapping ZIP members');
+    return entries;
+  } finally { await file.close(); }
+}
+function tarNumber(bytes) {
+  const value = bytes.toString('ascii').replace(/\0.*$/, '').trim();
+  if (value && !/^[0-7]+$/.test(value)) fail('Unsupported TAR numeric field');
+  const result = Number.parseInt(value || '0', 8);
+  if (!Number.isSafeInteger(result)) fail('Invalid TAR size');
+  return result;
+}
+function tarText(bytes) { return utf8.decode(bytes.subarray(0, bytes.indexOf(0) < 0 ? bytes.length : bytes.indexOf(0))); }
+function paxFields(bytes) {
+  const fields = {};
+  for (let offset = 0; offset < bytes.length;) {
+    const space = bytes.indexOf(32, offset);
+    if (space < 0 || !/^\d+$/.test(bytes.subarray(offset, space).toString())) fail('Invalid TAR PAX length');
+    const length = Number(bytes.subarray(offset, space).toString());
+    if (!Number.isSafeInteger(length) || length <= space - offset + 2 || offset + length > bytes.length || bytes[offset + length - 1] !== 10) fail('Invalid TAR PAX record');
+    const record = utf8.decode(bytes.subarray(space + 1, offset + length - 1));
+    const equal = record.indexOf('=');
+    const key = record.slice(0, equal), value = record.slice(equal + 1);
+    if (equal < 1 || !['path', 'linkpath', 'mtime', 'atime', 'ctime'].includes(key) || Object.hasOwn(fields, key)) fail('Unsupported TAR PAX field');
+    fields[key] = value;
+    offset += length;
+  }
+  return fields;
+}
+async function tarEntries(archive) {
+  const file = await fs.open(archive, 'r');
+  try {
+    const total = (await file.stat()).size;
+    const entries = [];
+    let offset = 0, pax = null, headers = 0;
+    while (offset + 512 <= total) {
+      const header = await readAt(file, offset, 512);
+      offset += 512;
+      if (header.every(value => value === 0)) {
+        if (pax || offset + 512 > total) fail('Truncated TAR trailer');
+        for (let at = offset; at < total; at += 65536) {
+          if (!(await readAt(file, at, Math.min(65536, total - at))).every(value => value === 0)) fail('Extra TAR payload after trailer');
+        }
+        return entries;
+      }
+      if (++headers > LIMITS.members * 2) fail('Too many TAR headers');
+      if (header.subarray(257, 263).toString('ascii') !== 'ustar\0') fail('Unsupported TAR header format');
+      let checksum = 0;
+      for (let index = 0; index < 512; index++) checksum += index >= 148 && index < 156 ? 32 : header[index];
+      if (checksum !== tarNumber(header.subarray(148, 156))) fail('Invalid TAR checksum');
+      const size = tarNumber(header.subarray(124, 136));
+      const kind = String.fromCharCode(header[156]);
+      if (size > (kind === 'x' ? 65536 : LIMITS.member) || offset + Math.ceil(size / 512) * 512 > total
+          || tarNumber(header.subarray(100, 108)) & 0o7000) fail('Unsafe TAR size or permissions');
+      if (kind === 'x') {
+        if (pax) fail('Chained TAR PAX headers');
+        pax = paxFields(await readAt(file, offset, size));
+      } else {
+        if (!['\0', '0', '5', '2'].includes(kind) || (kind !== '0' && kind !== '\0' && size)) fail('Unsupported TAR member');
+        const prefix = tarText(header.subarray(345, 500));
+        const name = pax && Object.hasOwn(pax, 'path') ? pax.path : (prefix ? prefix + '/' : '') + tarText(header.subarray(0, 100));
+        entries.push({ name, kind: kind === '5' ? 'directory' : kind === '2' ? 'link' : 'file', size,
+          link: pax && Object.hasOwn(pax, 'linkpath') ? pax.linkpath : tarText(header.subarray(157, 257)) });
+        pax = null;
+      }
+      offset += Math.ceil(size / 512) * 512;
+    }
+    fail('TAR trailer is missing');
+  } finally { await file.close(); }
+}
+async function boundedGunzip(archive, destination) {
+  let size = 0;
+  const bounded = new Transform({ transform(chunk, encoding, callback) {
+    size += chunk.length;
+    callback(size > LIMITS.expanded ? new Error('TAR expansion exceeds limit') : null, chunk);
+  } });
+  await pipeline(createReadStream(archive), createGunzip(), bounded,
+    createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal: AbortSignal.timeout(LIMITS.timeout) });
+}
+function nativeTar() {
+  return process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : '/usr/bin/tar';
+}
+async function extractArchive(archive, destination, spec, { spawnImpl = spawn } = {}) {
+  let input = archive;
+  const windows = spec.asset.endsWith('.zip');
+  if (!windows) { input = archive + '.tar'; await boundedGunzip(archive, input); }
+  const entries = windows ? await zipEntries(input) : await tarEntries(input);
+  validateEntries(entries, spec.root, windows);
+  await new Promise((resolve, reject) => {
+    const child = spawnImpl(nativeTar(), ['-xf', input, '-C', destination, '--no-same-owner', '--no-same-permissions'],
+      { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+    let errorBytes = 0;
+    const timer = setTimeout(() => { child.kill(); reject(new Error('Native tar extraction timed out')); }, LIMITS.timeout);
+    child.stderr.on('data', chunk => { errorBytes += chunk.length; if (errorBytes > 65536) { child.kill(); } });
+    child.once('error', () => { clearTimeout(timer); reject(new Error('Native tar is unavailable; install the operating system tar command')); });
+    child.once('close', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('Native tar rejected the release archive')); });
+  });
+  return entries;
+}
+module.exports = { validateEntries, zipEntries, tarEntries, extractArchive, nativeTar };

package/packaging/npm/lib/bootstrap.js

@@ -0,0 +1,150 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory } = require('./common');
+const { download } = require('./download');
+const { extractArchive } = require('./archive');
+const { cacheDirectory } = require('./cache');
+const packageVersion = require('../../../package.json').version;
+
+function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}) {
+  const key = `${platform}-${arch}`;
+  if (!['win32-x64', 'linux-x64'].includes(key)) fail(`Stackbite does not have a native release for ${key}; supported platforms are Windows x64 and Linux x64.`);
+  if (platform === 'linux' && (process.platform === 'linux' || Object.hasOwn(runtime, 'glibcVersionRuntime'))) {
+    const glibc = Object.hasOwn(runtime, 'glibcVersionRuntime')
+      ? runtime.glibcVersionRuntime : process.report.getReport().header.glibcVersionRuntime;
+    if (typeof glibc !== 'string' || !/^\d+\.\d+(?:\.\d+)?$/.test(glibc)) {
+      fail('Stackbite requires Linux x64 with glibc; Alpine/musl Linux is unsupported. No release was downloaded.');
+    }
+  }
+  if (manifest.schema !== 1 || manifest.version !== packageVersion || !/^[a-f0-9]{40}$/.test(manifest.commit)
+      || manifest.repository !== 'Shinick-Han/stackbite') fail('Invalid pinned Stackbite release identity');
+  const spec = manifest.platforms?.[key];
+  const host = platform === 'win32' ? 'windows-x64' : 'linux-x86_64';
+  const root = `stackbite-${manifest.version}-${host}-${manifest.commit.slice(0, 12)}`;
+  const asset = root + (platform === 'win32' ? '.zip' : '.tar.gz');
+  if (!spec || spec.root !== root || spec.asset !== asset
+      || spec.url !== `https://github.com/${manifest.repository}/releases/download/v${manifest.version}/${asset}`
+      || ![spec.sha256, spec.manifestSha256, spec.metadataSha256].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 { ...spec, key, platform, host, version: manifest.version, commit: manifest.commit };
+}
+async function validatePayload(directory, spec) {
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Cached release root is not a regular directory');
+  const root = await fs.realpath(directory);
+  const manifestPath = path.join(root, 'SHA256SUMS.json'), metadataPath = path.join(root, 'portable.json');
+  const manifestBytes = await readSmall(manifestPath), metadataBytes = await readSmall(metadataPath, 16384);
+  if (createHash('sha256').update(manifestBytes).digest('hex') !== spec.manifestSha256
+      || createHash('sha256').update(metadataBytes).digest('hex') !== spec.metadataSha256) fail('Pinned release manifest or metadata SHA-256 mismatch');
+  const hashes = JSON.parse(manifestBytes.toString('utf8'));
+  const metadata = JSON.parse(metadataBytes.toString('utf8'));
+  if (!hashes || Array.isArray(hashes) || typeof hashes !== 'object' || !Object.keys(hashes).length
+      || Object.keys(hashes).length > LIMITS.members) fail('Invalid release file manifest');
+  const expected = new Set();
+  for (const [name, digest] of Object.entries(hashes)) {
+    if (memberPath(name) !== name || !/^[a-f0-9]{64}$/.test(digest) || ['SHA256SUMS.json', 'SHA256SUMS'].includes(name)) fail('Invalid release manifest member');
+    expected.add(name);
+  }
+  if (!expected.has('portable.json') || !expected.has('runtime/build-info.json')) fail('Required release metadata is missing');
+  const actual = new Set();
+  let total = 0, entries = 0;
+  async function visit(directoryPath) {
+    for (const name of await fs.readdir(directoryPath)) {
+      if (++entries > LIMITS.members * 2) fail('Cached release has too many entries');
+      const target = path.join(directoryPath, name), relative = path.relative(root, target).split(path.sep).join('/');
+      memberPath(relative);
+      const entry = await fs.lstat(target);
+      if (entry.isDirectory()) { await visit(target); continue; }
+      if (!entry.isFile() && !entry.isSymbolicLink()) fail('Release contains a special file');
+      const resolved = await fs.realpath(target);
+      if (!inside(root, resolved)) fail('Release link escapes the cache root');
+      const resolvedInfo = await fs.lstat(resolved);
+      if (!resolvedInfo.isFile() || resolvedInfo.size > LIMITS.member) fail('Release link does not resolve to a bounded regular file');
+      total += resolvedInfo.size;
+      if (total > LIMITS.expanded) fail('Cached release exceeds expansion limit');
+      actual.add(relative);
+      if (expected.has(relative) && await hashFile(resolved) !== hashes[relative]) fail(`Release file SHA-256 mismatch: ${relative}`);
+    }
+  }
+  await visit(root);
+  expected.add('SHA256SUMS.json');
+  if (spec.platform === 'linux') {
+    expected.add('SHA256SUMS');
+    const text = await readSmall(path.join(root, 'SHA256SUMS'));
+    if (text.toString('utf8') !== Object.entries(hashes).map(([name, digest]) => `${digest}  ${name}\n`).join('')) fail('Linux checksum text disagrees with pinned manifest');
+  }
+  if (actual.size !== expected.size || [...actual].some(name => !expected.has(name))) fail('Release files disagree with pinned manifest');
+  const build = JSON.parse((await readSmall(path.join(root, 'runtime', 'build-info.json'), 16384)).toString('utf8'));
+  for (const value of [metadata, build]) {
+    if (value.version !== spec.version || value.commit !== spec.commit || value.product !== 'Stackbite'
+        || (value.command !== undefined && value.command !== 'stackbite')
+        || (value.platform !== undefined && value.platform !== spec.host)) fail('Release product/version/commit identity mismatch');
+  }
+  const executable = path.join(root, spec.platform === 'win32' ? 'stackbite.exe' : 'stackbite');
+  const image = await fs.lstat(executable);
+  if (!image.isFile() || image.isSymbolicLink()) fail('Native release executable is missing or a link');
+  const file = await fs.open(executable, 'r');
+  try {
+    const magic = Buffer.alloc(4);
+    if ((await file.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');
+  } finally { await file.close(); }
+  if (spec.platform === 'linux' && process.platform !== 'win32' && !(image.mode & 0o111)) fail('Native release executable has no execute permission');
+  return executable;
+}
+async function ensureBinary(spec, { cache = cacheDirectory(), downloadImpl = download, extractImpl = extractArchive } = {}) {
+  cache = path.resolve(cache);
+  await safeDirectory(cache);
+  const target = path.join(cache, `${spec.version}-${spec.commit}-${spec.key}-${spec.sha256}`);
+  if (await exists(target)) return { home: target, executable: await validatePayload(target, spec) };
+  const staging = await fs.mkdtemp(path.join(cache, '.staging-'));
+  try {
+    const archive = path.join(staging, spec.asset), extraction = path.join(staging, 'extract');
+    await fs.mkdir(extraction, { mode: 0o700 });
+    await downloadImpl(spec, archive);
+    // Recheck at the extraction boundary, including for injected test transports.
+    if ((await fs.stat(archive)).size !== spec.size || await hashFile(archive, LIMITS.download) !== spec.sha256) fail('Pinned archive SHA-256 or size mismatch');
+    await extractImpl(archive, extraction, spec);
+    const payload = path.join(extraction, spec.root);
+    await validatePayload(payload, spec);
+    try { await fs.rename(payload, target); }
+    catch (error) {
+      // Another process may have installed the same immutable payload first.
+      // Never delete/rewrite its directory or try a destructive rename retry.
+      if (!await exists(target)) throw error;
+    }
+    return { home: target, executable: await validatePayload(target, spec) };
+  } finally {
+    // Only this mkdtemp handle is owned by this invocation.
+    if (!inside(cache, staging) || path.dirname(staging) !== cache) fail('Unsafe staging cleanup path');
+    await fs.rm(staging, { recursive: true, force: true });
+  }
+}
+async function launchNative(executable, argv, environment, { spawnImpl = spawn, signalSource = process } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(executable, argv, { env: environment, stdio: 'inherit', shell: false });
+    const handlers = new Map();
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      const handler = () => child.kill(signal);
+      handlers.set(signal, handler);
+      signalSource.on(signal, handler);
+    }
+    function cleanup() { for (const [signal, handler] of handlers) signalSource.removeListener(signal, handler); }
+    child.once('error', () => { cleanup(); reject(new Error('Cannot start the verified native Stackbite executable')); });
+    child.once('exit', (code, signal) => { cleanup(); resolve({ code, signal }); });
+  });
+}
+async function main(argv = process.argv.slice(2), options = {}) {
+  const manifest = options.manifest || require('../release.json');
+  const platform = options.platform || process.platform;
+  const environment = options.environment || process.env;
+  const spec = releaseSpec(manifest, platform, options.arch || process.arch, options);
+  const installed = await ensureBinary(spec, { ...options, cache: options.cache || cacheDirectory(environment, platform) });
+  // The bundled runtime owns state discovery and migration for every entrypoint.
+  return launchNative(installed.executable, argv, { ...environment,
+    STACKBITE_HOME: path.resolve(installed.home) }, options);
+}
+module.exports = { releaseSpec, validatePayload, ensureBinary, launchNative, main };

package/packaging/npm/lib/cache.js

@@ -0,0 +1,10 @@
+'use strict';
+const path = require('node:path');
+const os = require('node:os');
+
+function cacheDirectory(environment = process.env, platform = process.platform, home = os.homedir()) {
+  return platform === 'win32'
+    ? path.resolve(environment.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Stackbite', 'cache')
+    : path.resolve(environment.XDG_CACHE_HOME || path.join(environment.HOME || home, '.cache'), 'stackbite');
+}
+module.exports = { cacheDirectory };

package/packaging/npm/lib/common.js

@@ -0,0 +1,51 @@
+'use strict';
+const fs = require('node:fs/promises');
+const { createReadStream } = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+
+const LIMITS = Object.freeze({ download: 512 * 1024 * 1024, expanded: 1024 * 1024 * 1024,
+  member: 128 * 1024 * 1024, metadata: 2 * 1024 * 1024, members: 25000, timeout: 120000 });
+function fail(message) { throw new Error(message); }
+function memberPath(name) {
+  if (typeof name !== 'string' || !name || name.length > 1024 || /[\\:<>"|?*\x00-\x1f\x7f]/.test(name)) fail('Unsafe archive path');
+  const cleaned = name.endsWith('/') ? name.slice(0, -1) : name;
+  const parts = cleaned.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..' || /[ .]$/.test(part)
+      || /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i.test(part))) fail('Unsafe archive path');
+  return cleaned;
+}
+function inside(root, target) {
+  const relative = path.relative(root, target);
+  return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+}
+async function hashFile(filename, maximum = LIMITS.member) {
+  const info = await fs.stat(filename);
+  if (!info.isFile() || info.size > maximum) fail('Release file exceeds its size limit');
+  const hash = createHash('sha256');
+  let size = 0;
+  for await (const chunk of createReadStream(filename)) {
+    size += chunk.length;
+    if (size > maximum) fail('Release file exceeds its size limit');
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+async function readSmall(filename, maximum = LIMITS.metadata) {
+  const info = await fs.lstat(filename);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > maximum) fail('Unsafe or oversized release metadata');
+  return fs.readFile(filename);
+}
+async function exists(filename) {
+  try { await fs.lstat(filename); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+async function safeDirectory(directory) {
+  const parent = path.dirname(directory);
+  if (parent !== directory) await safeDirectory(parent);
+  if (!await exists(directory)) {
+    try { await fs.mkdir(directory, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Cache directory contains a link or non-directory');
+}
+module.exports = { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory };

package/packaging/npm/lib/download.js

@@ -0,0 +1,52 @@
+'use strict';
+const https = require('node:https');
+const { createWriteStream } = require('node:fs');
+const { Transform } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+const { LIMITS, fail, hashFile } = require('./common');
+
+function secureURL(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' || url.username || url.password || (url.port && url.port !== '443')
+      || !['github.com', 'release-assets.githubusercontent.com', 'objects.githubusercontent.com'].includes(url.hostname)) {
+    fail('Release redirect is not an approved HTTPS origin');
+  }
+  return url;
+}
+async function download(spec, destination, { request = https.get, timeout = LIMITS.timeout } = {}) {
+  if (!Number.isSafeInteger(spec.size) || spec.size <= 0 || spec.size > LIMITS.download) fail('Invalid pinned download size');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  let current = secureURL(spec.url);
+  try {
+    for (let redirects = 0; redirects <= 5; redirects++) {
+      const response = await new Promise((resolve, reject) => {
+        const req = request(current, { signal: controller.signal, headers: {
+          'User-Agent': 'Stackbite-npm-bootstrap', 'Accept-Encoding': 'identity', Accept: 'application/octet-stream'
+        } }, resolve);
+        req.once('error', () => reject(new Error('Release download failed or timed out')));
+      });
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        const location = response.headers.location;
+        response.destroy();
+        if (redirects === 5 || typeof location !== 'string' || location.length > 4096) fail('Invalid release redirect');
+        current = secureURL(new URL(location, current).href);
+        continue;
+      }
+      if (response.statusCode !== 200 || (response.headers['content-encoding'] && response.headers['content-encoding'] !== 'identity')) {
+        response.destroy(); fail('Release download was not available');
+      }
+      const length = response.headers['content-length'];
+      if (length !== undefined && String(spec.size) !== length) { response.destroy(); fail('Release download size mismatch'); }
+      let size = 0;
+      const bounded = new Transform({ transform(chunk, encoding, callback) {
+        size += chunk.length;
+        callback(size > spec.size ? new Error('Release download exceeds pinned size') : null, chunk);
+      } });
+      await pipeline(response, bounded, createWriteStream(destination, { flags: 'wx', mode: 0o600 }), { signal: controller.signal });
+      if (size !== spec.size || await hashFile(destination, LIMITS.download) !== spec.sha256) fail('Release SHA-256 or size mismatch');
+      return;
+    }
+  } finally { clearTimeout(timer); }
+}
+module.exports = { download, secureURL };

package/packaging/npm/release.json

@@ -0,0 +1,26 @@
+{
+  "schema": 1,
+  "version": "0.5.11",
+  "commit": "572562d1755f055d2ec343ec431876a2d2838eec",
+  "repository": "Shinick-Han/stackbite",
+  "platforms": {
+    "win32-x64": {
+      "asset": "stackbite-0.5.11-windows-x64-572562d1755f.zip",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.11/stackbite-0.5.11-windows-x64-572562d1755f.zip",
+      "sha256": "757619ad45c8f20b76e6c2b67e061415d7894e8d8e1cb9ce215a427dcc5c1b8f",
+      "size": 35311793,
+      "root": "stackbite-0.5.11-windows-x64-572562d1755f",
+      "manifestSha256": "179ced3cf7c7cd8aebc9fec5244baa978152730da8d894812e7b4587630e264b",
+      "metadataSha256": "d783e1f17dd31a43521b9b78b62a7c13f3e0193fe07e23b27e078038596a9589"
+    },
+    "linux-x64": {
+      "asset": "stackbite-0.5.11-linux-x86_64-572562d1755f.tar.gz",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.11/stackbite-0.5.11-linux-x86_64-572562d1755f.tar.gz",
+      "sha256": "500927a33edb6ec567b7b0d20ff40ad9f24646b52d33eebeb23f550907554f6c",
+      "size": 18475500,
+      "root": "stackbite-0.5.11-linux-x86_64-572562d1755f",
+      "manifestSha256": "7b8487f4f29b36d9d584d981dc57dc96da991c2951bd808c67fb158ae1239eba",
+      "metadataSha256": "0490bde5afb5279516b254eb43b25bf228def181cfd4a83cc2c4251993718c8b"
+    }
+  }
+}