stackbite 0.5.106 → 0.5.108

package/package.json

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

package/packaging/npm/lib/bootstrap.js

@@ -484,8 +484,70 @@ async function reservePreparation(environment, platform, target, source) {
   }
 }
 
+// Durable runtime images share the standalone installer's versioned app root,
+// with its live-reference retention and removal inventory. The disposable
+// cache only holds images of the previous layout, which may be adopted.
+// A different archive of the same version and commit (for example a signed
+// rebuild) gets a sibling qualified by its pinned archive digest, so an image
+// another installer or pin published is never replaced or run under this pin.
+function runtimeName(spec, qualified = false) {
+  const commit = spec.commit.slice(0, 12), version = spec.version + (qualified ? `-pin${spec.sha256.slice(0, 10)}` : '');
+  return spec.platform === 'win32' ? `${version}-${commit}` : `stackbite-${version}-${spec.host}-${commit}`;
+}
+async function pinnedTarget(runtime, spec) {
+  const canonical = path.join(runtime, runtimeName(spec));
+  if (!await exists(canonical)) return canonical;
+  try { await pinnedDocuments(await payloadRoot(canonical), spec); return canonical; }
+  catch (error) { if (/manifest or metadata SHA-256 mismatch/.test(error.message)) return path.join(runtime, runtimeName(spec, true)); throw error; }
+}
+function previousCacheHome(home, cache, platform) {
+  const spelling = value => platform === 'win32' ? value.toLowerCase() : value;
+  return typeof home === 'string' && path.isAbsolute(home) && /^v1-[a-f0-9]{64}$/.test(path.basename(home))
+    && !!cache && spelling(path.dirname(path.resolve(home))) === spelling(cache);
+}
+// Bounded portable.json of an image; null when absent, linked, oversized or malformed.
+async function portableMetadata(root) {
+  try { return JSON.parse((await readSmall(path.join(root, 'portable.json'), 16384)).toString('utf8')); }
+  catch { return null; }
+}
+// The release identity Python's former-cache check compares (Windows may omit platform).
+function portableMatches(value, spec) {
+  return !!value && typeof value === 'object' && value.product === 'Stackbite' && value.command === 'stackbite'
+    && value.version === spec.version && value.commit === spec.commit
+    && (Object.hasOwn(value, 'platform') ? value.platform : spec.platform === 'win32' ? spec.host : undefined) === spec.host;
+}
+// An absolute literal path with no linked ancestor and no source repository.
+async function literalPath(home) {
+  if (!path.isAbsolute(home) || path.resolve(home) !== home) return false;
+  for (let ancestor = home; ; ancestor = path.dirname(ancestor)) {
+    let info = null;
+    try { info = await fs.lstat(ancestor); } catch (error) { if (error.code !== 'ENOENT') return false; }
+    if (info?.isSymbolicLink() || info && await exists(path.join(ancestor, '.git'))) return false;
+    if (ancestor === path.dirname(ancestor)) return true;
+  }
+}
+// A previous-layout cache image recorded by a host with another cache root:
+// the shape and portable identity Python's _former_cache_image accepts. This
+// classifies the file only; no environment state changes it. It is only read.
+async function formerCache(home, spec) {
+  if (typeof home !== 'string' || !/^v1-[a-f0-9]{64}$/.test(path.basename(home))
+      || path.basename(path.dirname(home)) !== 'stackbite') return null;
+  try {
+    if (!await literalPath(home) || !(await fs.lstat(home)).isDirectory()) return null;
+  } catch { return null; }
+  return portableMatches(await portableMetadata(home), spec) ? home : null;
+}
+// A former cache selection this run may migrate: the engine moves a selection
+// only under its own state, so a per-run STACKBITE_STATE_DIR never does. The
+// engine reads a legacy HELM_STATE_DIR only when STACKBITE_STATE_DIR is absent
+// (even empty, the canonical name wins). It decides again under its locks.
+async function formerSelection(saved, environment, spec) {
+  const state = Object.hasOwn(environment, 'STACKBITE_STATE_DIR') ? environment.STACKBITE_STATE_DIR : environment.HELM_STATE_DIR;
+  return state && path.resolve(state) !== saved?.state ? null : formerCache(saved?.home, spec);
+}
 async function publishCache(payload, target, spec, options) {
   await assertBaseline(options.environment, spec.platform);
+  let migrate = false;
   if (options.existing) {
     const root = installationRoot(options.environment, spec.platform);
     for (const name of ['default-install.json', 'install.json']) {
@@ -493,46 +555,140 @@ async function publishCache(payload, target, spec, options) {
       if (!await exists(locator)) continue;
       const saved = JSON.parse((await readSmall(locator, 16384)).toString('utf8').replace(/^\uFEFF/, ''));
       const descriptor = options.environment.STACKBITE_NPM_REGISTRATION;
-      if (typeof saved.home === 'string' && path.isAbsolute(saved.home)
+      migrate = previousCacheHome(saved.home, options.cache, spec.platform)
+        || !!await formerSelection(saved, options.environment, spec);
+      if (!migrate && typeof saved.home === 'string' && path.isAbsolute(saved.home)
           && typeof saved.state === 'string' && path.isAbsolute(saved.state) && /^[a-f0-9]{32}$/.test(saved.installation_id)
           && (!descriptor || JSON.stringify(saved.npm_registration) === JSON.stringify(JSON.parse(descriptor)))) return;
       break;
     }
   }
   const engine = path.join(payload, 'stackbite' + (spec.platform === 'win32' ? '.exe' : ''));
-  const argv = options.existing ? ['--record-install', target]
+  // A selection still in the previous cache layout moves to the durable image.
+  const argv = options.existing && !migrate ? ['--record-install', target]
     : ['--record-install', target, '-', payload, 'cache'];
   const result = await launchNative(engine, argv, { ...options.environment, STACKBITE_HOME: payload }, options);
   if (result.code !== 0 || result.signal) fail('Runtime publication was refused');
 }
 
-async function ensureBinary(spec, { cache = cacheDirectory(), downloadImpl = download, extractImpl = extractArchive,
-  checkOnly = false, reportCached = false, includePhone = false, progress = () => {},
+function runtimeDirectory(environment, platform) {
+  return path.join(installationRoot(environment, platform), 'app');
+}
+// This root's first locator, when it fully names an installation: the same
+// shape publishCache keeps without rewriting its home.
+async function establishedLocator(root) {
+  for (const name of ['default-install.json', 'install.json']) {
+    const locator = path.join(root, name);
+    if (!await exists(locator)) continue;
+    const saved = JSON.parse((await readSmall(locator, 16384)).toString('utf8').replace(/^\uFEFF/, ''));
+    return saved && typeof saved.home === 'string' && path.isAbsolute(saved.home)
+      && typeof saved.state === 'string' && path.isAbsolute(saved.state)
+      && /^[a-f0-9]{32}$/.test(saved.installation_id) ? saved : null;
+  }
+  return null;
+}
+async function installationLocator(environment, platform) {
+  const root = installationRoot(environment, platform);
+  return await selectedDirectory(root, environment, platform) ? establishedLocator(root) : null;
+}
+// The image root when its portable identity is this release; null otherwise.
+async function sameRelease(home, spec) {
+  let root;
+  try { root = await payloadRoot(home); } catch { return null; }
+  return portableMatches(await portableMetadata(root), spec) ? root : null;
+}
+// Another archive of this release (a re-signed build) carries its own valid
+// checksum manifest that pins its portable.json. A damaged image does not.
+async function anotherPin(root) {
+  try {
+    const hashes = JSON.parse((await readSmall(path.join(root, 'SHA256SUMS.json'))).toString('utf8'));
+    expectedMembers(hashes);
+    const metadata = await readSmall(path.join(root, 'portable.json'), 16384);
+    return hashes['portable.json'] === createHash('sha256').update(metadata).digest('hex');
+  } catch { return false; }
+}
+// An image the established installation already selects outside app/: an
+// explicit STACKBITE_HOME, else the locator's home. Another release or pin is
+// skipped; an image of this release must otherwise carry this package's pinned
+// documents, and the caller then validates its whole payload, so a damaged image
+// of this release is refused, not replaced. Publication keeps the locator's
+// home, except that a cache image (this host's or a former host's) is never run
+// in place.
+async function selectedImage(environment, spec, cache) {
+  const saved = await installationLocator(environment, spec.platform);
+  // A previous-cache selection keeps its existing migration path.
+  if (!saved || previousCacheHome(saved.home, cache, spec.platform)) return null;
+  const former = await formerCache(saved.home, spec);
+  for (const home of [environment.STACKBITE_HOME, saved.home]) {
+    if (typeof home !== 'string' || !path.isAbsolute(home) || home === former) continue;
+    const root = await sameRelease(home, spec);
+    if (!root) continue;
+    try { await pinnedDocuments(root, spec); }
+    catch (error) { if (await anotherPin(root)) continue; throw error; }
+    return path.resolve(home);
+  }
+  return null;
+}
+// An image of this exact pinned identity, when it passes the full pinned
+// validation. It is only read; a live process may use it.
+async function verifiedImage(home, spec) {
+  if (!home) return null;
+  try { await validatePayload(home, spec); } catch { return null; }
+  return home;
+}
+async function previousImage(legacy, cache, spec) {
+  return await existingCacheDirectory(cache) && await exists(legacy) ? verifiedImage(legacy, spec) : null;
+}
+async function ensureBinary(spec, { cache = cacheDirectory(), runtime = null, downloadImpl = download, extractImpl = extractArchive,
+  checkOnly = false, reportCached = false, includePhone = false, reuseSelected = false, progress = () => {},
   environment = process.env, publishImpl = publishCache, registrationSource = null, ...options } = {}) {
   cache = await resolveCacheDirectory(cache);
   environment = { ...environment };
+  runtime = path.resolve(runtime || runtimeDirectory(environment, spec.platform));
   if (!checkOnly) {
     await admitPublication(environment, spec.platform);
     await existingCacheDirectory(cache); // Validate existing ancestors without creating a cache.
   }
-  if (checkOnly) {
-    if (!await existingCacheDirectory(cache)) throw notCached();
-  }
   // Full identity remains SHA-256 addressed while avoiding Windows MAX_PATH.
   const cacheKey = createHash('sha256').update(JSON.stringify([spec.version, spec.commit, spec.key, spec.sha256])).digest('hex');
-  const target = path.join(cache, `v1-${cacheKey}`);
+  const legacy = path.join(cache, `v1-${cacheKey}`);
+  const target = await selectedDirectory(runtime, environment, spec.platform) ? await pinnedTarget(runtime, spec)
+    : path.join(runtime, runtimeName(spec));
   const preparation = !checkOnly ? await reservePreparation(environment, spec.platform, target, registrationSource) : null;
   try {
     if (registrationSource) await registrationSource.validate();
     if (!checkOnly) await assertBaseline(environment, spec.platform);
-    if (await exists(target)) {
+    // Check-only callers (removal, setup --check) never publish; they may still
+    // use an image of the previous cache layout, this host's or a former host's.
+    const published = await selectedDirectory(runtime, environment, spec.platform) && await exists(target);
+    const former = !published && reuseSelected
+      ? await formerCache((await installationLocator(environment, spec.platform))?.home, spec) : null;
+    const home = published ? target
+      : reuseSelected && await selectedImage(environment, spec, cache)
+        || (checkOnly ? (await existingCacheDirectory(cache) && await exists(legacy) ? legacy : former) : null);
+    if (home) {
       if (checkOnly || reportCached) progress('validate');
-      const installed = { home: target, executable: await validatePayload(target, spec, { includePhone }) };
-      if (!checkOnly) await publishImpl(target, target, spec, { ...options, environment, existing: true });
+      const installed = { home, executable: await validatePayload(home, spec, { includePhone }) };
+      // A selected image outside app/ is its own maintenance engine.
+      if (!checkOnly) await publishImpl(home, target, spec, { ...options, environment, cache, existing: true });
       if (checkOnly || reportCached) progress('ready');
       return installed;
     }
     if (checkOnly) throw notCached();
+    // A verified previous-layout image is copied once into the durable target;
+    // the engine then moves a cache selection there.
+    const previous = await previousImage(legacy, cache, spec) || await verifiedImage(former, spec);
+    if (previous) {
+      progress('publish');
+      await admitPublication(environment, spec.platform);
+      await assertBaseline(environment, spec.platform);
+      if (registrationSource) await registrationSource.validate();
+      await publishImpl(previous, target, spec, { ...options, environment, cache, existing: false });
+      progress('validate-published');
+      const installed = { home: target, executable: await validatePayload(target, spec) };
+      progress('ready');
+      return installed;
+    }
     // An owned system-temp stage keeps downloads out of product caches. Only the
     // verified engine below can create/publish a canonical cache installation.
     await admitPublication(environment, spec.platform);
@@ -545,7 +701,7 @@ async function ensureBinary(spec, { cache = cacheDirectory(), downloadImpl = dow
       await admitPublication(environment, spec.platform);
       await assertBaseline(environment, spec.platform);
       if (registrationSource) await registrationSource.validate();
-      await publishImpl(payload, target, spec, { ...options, environment, existing: false });
+      await publishImpl(payload, target, spec, { ...options, environment, cache, existing: false });
       // Validate at the final path, including a concurrent publisher's payload.
       progress('validate-published');
       const installed = { home: target, executable: await validatePayload(target, spec) };
@@ -565,9 +721,11 @@ async function stageRelease(spec, staging, { downloadImpl, extractImpl, progress
   await fs.mkdir(extraction, { mode: 0o700 });
   progress('download');
   await downloadImpl(spec, archive);
-  // Recheck at the extraction boundary, including for injected test transports.
+  // download() itself verifies the exact size and SHA-256 before returning.
+  // Recheck any other transport at the extraction boundary.
   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');
+  if (downloadImpl !== download && ((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);
   const payload = path.join(extraction, spec.root);
@@ -630,6 +788,21 @@ async function launchNative(executable, argv, environment, { spawnImpl = spawn,
     child.once('exit', (code, signal) => { cleanup(); resolve({ code, signal }); });
   });
 }
+// Before the first install, --help/--version answer from this package's pin
+// instead of downloading a runtime; the launcher only ever runs that build.
+async function coldAnswer(argv, spec, runtime, { stdout = process.stdout, stderr = process.stderr }) {
+  if (argv.length !== 1 || !['--version', '--help', '-h'].includes(argv[0])) return null;
+  try { if (await exists(await pinnedTarget(runtime, spec))) return null; } catch { return null; }
+  if (argv[0] === '--version') {
+    stdout.write(`Stackbite ${spec.version} (${spec.commit})\n`);
+    stderr.write('Stackbite: this is the pinned release; its runtime is not installed yet. Run stackbite setup to install it.\n');
+  } else {
+    stdout.write('usage: stackbite [--help | --version] | stackbite setup [--check] | stackbite [COMMAND ...]\n\n'
+      + `The pinned Stackbite ${spec.version} runtime is not installed yet. Run stackbite setup to\n`
+      + 'install it (or run any command); stackbite --help then shows the full reference.\n');
+  }
+  return { code: 0, signal: null };
+}
 async function main(argv = process.argv.slice(2), options = {}) {
   const setup = parseSetup(argv);
   const removing = ['uninstall', 'delete'].includes(argv[0]);
@@ -645,13 +818,15 @@ async function main(argv = process.argv.slice(2), options = {}) {
   try {
     if (npm) environment.STACKBITE_NPM_REGISTRATION = JSON.stringify(npm);
     const spec = releaseSpec(manifest, platform, options.arch || process.arch, options);
+    const cold = await coldAnswer(argv, spec, options.runtime || runtimeDirectory(environment, platform), options);
+    if (cold) return cold;
     // First install always verifies everything. Cached TUI/runtime starts defer only
     // Phone; explicit phone/setup/removal commands retain the full pinned check.
     let installed;
     try { installed = await timing.phase(environment, 'launcher.ensure', () => ensureBinary(spec, { ...options,
       environment, registrationSource,
       cache: options.cache || cacheDirectory(environment, platform),
-      checkOnly: removing || setup?.checkOnly || false, reportCached: Boolean(setup),
+      checkOnly: removing || setup?.checkOnly || false, reportCached: Boolean(setup), reuseSelected: !removing,
       includePhone: removing || Boolean(setup) || argv[0] === 'phone',
       progress: options.progress || stageReporter(options.stderr || process.stderr) })); }
     catch (error) {

package/packaging/npm/lib/setup.js

@@ -14,7 +14,7 @@ function stageReporter(stderr) {
     archive: 'Verifying archive...',
     extract: 'Extracting runtime...',
     validate: 'Validating runtime files...',
-    publish: 'Publishing runtime cache...',
+    publish: 'Publishing runtime...',
     'validate-published': 'Validating published runtime...',
     ready: 'Pinned runtime is ready.'
   };

package/packaging/npm/release.json

@@ -1,35 +1,35 @@
 {
   "schema": 1,
-  "version": "0.5.106",
-  "commit": "f7fcecb80596225d9e7902b9527b4645cb3d7002",
+  "version": "0.5.108",
+  "commit": "bcd3e47ee369cdbf209688fb8333b7b582e292cb",
   "repository": "Shinick-Han/stackbite",
   "platforms": {
     "win32-x64": {
-      "asset": "stackbite-0.5.106-windows-x64-f7fcecb80596.zip",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.106/stackbite-0.5.106-windows-x64-f7fcecb80596.zip",
-      "sha256": "5af24d41d166ef5c68ca2aa1ffa833364fb3cb3bab6688e5a1491e1d49a923a1",
-      "size": 96328588,
-      "root": "stackbite-0.5.106-windows-x64-f7fcecb80596",
-      "manifestSha256": "2a278815c956e7ad8b45c7019e0dc654c99525a4e534ec5b33905ec7e7eb7259",
-      "metadataSha256": "f2689110874ba778e7c816b7188f0930e8b477d0588586494cd5e01d4640a8ca"
+      "asset": "stackbite-0.5.108-windows-x64-bcd3e47ee369.zip",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.108/stackbite-0.5.108-windows-x64-bcd3e47ee369.zip",
+      "sha256": "416b55e30a6b3670b74477e078515b927ffa61f01d1aadb255a41a30d5145c7a",
+      "size": 82803119,
+      "root": "stackbite-0.5.108-windows-x64-bcd3e47ee369",
+      "manifestSha256": "8d00d3cbe4ddb913c06392427be2e0b6a8162d88fdb3bcb2fa573fb55a95d34c",
+      "metadataSha256": "4fdcdaeeab139ac774f67c61c27bb32ba07a3151df059f7918cd042f6b89a72e"
     },
     "linux-x64": {
-      "asset": "stackbite-0.5.106-linux-x86_64-f7fcecb80596.tar.gz",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.106/stackbite-0.5.106-linux-x86_64-f7fcecb80596.tar.gz",
-      "sha256": "79728b2038bb9ba04850da7638e01d4cbcc74141616b6a0cbec7c29a28dc7fef",
-      "size": 77540472,
-      "root": "stackbite-0.5.106-linux-x86_64-f7fcecb80596",
-      "manifestSha256": "6de0565cc64b891c066a0c4c930a6b31117912c68739711e676e19dede8232b6",
-      "metadataSha256": "7927af2f0b5625ae00677b48cd32842d3f42d9c1507803d68471835276168490"
+      "asset": "stackbite-0.5.108-linux-x86_64-bcd3e47ee369.tar.gz",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.108/stackbite-0.5.108-linux-x86_64-bcd3e47ee369.tar.gz",
+      "sha256": "83fba4c60508d2a4fcbaa276c51e8eb7db9f2f762e2f28228b9b6ece9ac10327",
+      "size": 82791962,
+      "root": "stackbite-0.5.108-linux-x86_64-bcd3e47ee369",
+      "manifestSha256": "36dfdbf9f1fc5dcdc882e438ff855065d3456f6674dea115fd219b6e7a7893fb",
+      "metadataSha256": "ee20086e1c78590a83dab038dce86e0b28d288fc6d0665f00c041644777340ad"
     },
     "darwin-arm64": {
-      "asset": "stackbite-0.5.106-macos-arm64-f7fcecb80596.tar.gz",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.106/stackbite-0.5.106-macos-arm64-f7fcecb80596.tar.gz",
-      "sha256": "cf19aa0008059e79d67bc6233be85c5a27f489587a0fe8a655802e04082cd3e6",
-      "size": 33517046,
-      "root": "stackbite-0.5.106-macos-arm64-f7fcecb80596",
-      "manifestSha256": "cfec4e35e68ae347b16ff5a447c658c17a205edfdc18e377c4d56d46635cdc28",
-      "metadataSha256": "2cce940de463bac26eca2ff638318434cab8c241ffa4f76989cfe573ab680aee"
+      "asset": "stackbite-0.5.108-macos-arm64-bcd3e47ee369.tar.gz",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.108/stackbite-0.5.108-macos-arm64-bcd3e47ee369.tar.gz",
+      "sha256": "3d1afcb0b7c197cf76691bff3807f8b11bfecda2c93e70f67a7b44c71f312299",
+      "size": 38100942,
+      "root": "stackbite-0.5.108-macos-arm64-bcd3e47ee369",
+      "manifestSha256": "0e1c7f4958fe4852d2e25732e18ef85523fe2a2047647362837cacf8243bed45",
+      "metadataSha256": "cac6ffae5862aa0cb5f3b51c62c798c042ae0bcc3ed06172d1f74632c77848e1"
     }
   }
 }