stackbite 0.5.14 → 0.5.15

package/README.md

@@ -15,16 +15,41 @@ Choose one method. For a single run, use the public npm package:
 npx --yes stackbite
 ```
 
-For a persistent command, install it globally and then run it:
+For a persistent command, install it globally, prepare the runtime, then launch:
 
 ```sh
 npm install --global stackbite
+stackbite setup
 stackbite
 ```
 
-Both methods download the verified native runtime on first execution. Global
-installation alone installs the small launcher; its first `stackbite` invocation
-downloads the runtime. Running both installation methods is unnecessary.
+Global installation installs the small launcher without a postinstall download.
+`stackbite setup` downloads and fully validates its pinned runtime without starting
+the app or backend. It prints short stages to stderr. If setup is omitted, the
+first launch prepares the runtime with the same stages. Cached launches remain
+quiet and fully validate the runtime every time. Running both installation methods
+is unnecessary.
+
+The same preparation command works through npx:
+
+```sh
+npx --yes stackbite setup
+```
+
+Check a prepared runtime offline with `stackbite setup --check`. The launcher
+checks all pinned file hashes, identity, inventory and link boundaries, without
+downloading, extracting, writing cache files, or starting the app/backend. It exits
+with status 0 when valid and status 1 when absent or invalid; an absent cache needs
+`stackbite setup`. Only `setup` and `setup --check` are accepted setup forms.
+The launcher check is read-only; npx itself may install its npm package before
+invoking it, so use the installed command for an entirely offline check.
+
+Binary caches use `%LOCALAPPDATA%\Stackbite\cache` on Windows and
+`${XDG_CACHE_HOME:-~/.cache}/stackbite` on Linux. `LOCALAPPDATA`, `XDG_CACHE_HOME`
+and `HOME` overrides retain their normal behavior. These caches are separate from
+application state. Interrupted preparation removes only its own temporary staging
+directory and can be retried. An invalid existing runtime is reported and left in
+place; setup does not delete or overwrite it.
 
 Update a registry installation with `npm install --global stackbite@latest`.
 
@@ -33,14 +58,15 @@ Update a registry installation with `npm install --global stackbite@latest`.
 Run the package attached to the verified GitHub release:
 
 ```sh
-npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.14/stackbite-0.5.14.tgz
+npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15.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.14/stackbite-0.5.14.tgz
+npm install --global https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15.tgz
+stackbite setup
 stackbite
 ```
 
@@ -70,18 +96,30 @@ 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.
+For app commands, the launcher inherits terminal input/output and passes CLI
+arguments directly to the native app. Its `setup` command only prepares/checks the
+runtime. 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
 
+Measure bounded fake runtime preparation and warm verification without network or
+app processes:
+
+```sh
+node packaging/npm/test/measure-setup.js
+```
+
+The measurement reports fixture sizes and each preparation stage plus warm check
+and launch validation costs. It uses disposable cache data and an inert child
+stub; its timings are not measurements of released native bundles or providers.
+
 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.14
+python scripts/prepare_npm_release.py --version 0.5.15
 npm test
 npm pack
 ```

package/package.json

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

package/packaging/npm/lib/bootstrap.js

@@ -6,7 +6,8 @@ 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 { cacheDirectory, existingCacheDirectory } = require('./cache');
+const { parseSetup, stageReporter } = require('./setup');
 const packageVersion = require('../../../package.json').version;
 
 function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}) {
@@ -95,28 +96,46 @@ async function validatePayload(directory, spec) {
   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 } = {}) {
+async function ensureBinary(spec, { cache = cacheDirectory(), downloadImpl = download, extractImpl = extractArchive,
+  checkOnly = false, reportCached = false, progress = () => {} } = {}) {
   cache = path.resolve(cache);
-  await safeDirectory(cache);
+  if (checkOnly) {
+    if (!await existingCacheDirectory(cache)) fail('Pinned runtime is not cached; run stackbite setup.');
+  } else 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) };
+  if (await exists(target)) {
+    if (checkOnly || reportCached) progress('validate');
+    const installed = { home: target, executable: await validatePayload(target, spec) };
+    if (checkOnly || reportCached) progress('ready');
+    return installed;
+  }
+  if (checkOnly) fail('Pinned runtime is not cached; run stackbite setup.');
   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 });
+    progress('download');
     await downloadImpl(spec, archive);
     // Recheck at the extraction boundary, including for injected test transports.
+    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);
     const payload = path.join(extraction, spec.root);
+    progress('validate');
     await validatePayload(payload, spec);
+    progress('publish');
     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) };
+    // Validate at the final path, including a concurrent publisher's payload.
+    progress('validate-published');
+    const installed = { home: target, executable: await validatePayload(target, spec) };
+    progress('ready');
+    return installed;
   } finally {
     // Only this mkdtemp handle is owned by this invocation.
     if (!inside(cache, staging) || path.dirname(staging) !== cache) fail('Unsafe staging cleanup path');
@@ -138,11 +157,15 @@ async function launchNative(executable, argv, environment, { spawnImpl = spawn,
   });
 }
 async function main(argv = process.argv.slice(2), options = {}) {
+  const setup = parseSetup(argv);
   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) });
+  const installed = await ensureBinary(spec, { ...options, cache: options.cache || cacheDirectory(environment, platform),
+    checkOnly: setup?.checkOnly || false, reportCached: Boolean(setup),
+    progress: options.progress || stageReporter(options.stderr || process.stderr) });
+  if (setup) return { code: 0, signal: null };
   // The bundled runtime owns state discovery and migration for every entrypoint.
   return launchNative(installed.executable, argv, { ...environment,
     STACKBITE_HOME: path.resolve(installed.home) }, options);

package/packaging/npm/lib/cache.js

@@ -1,10 +1,23 @@
 'use strict';
 const path = require('node:path');
 const os = require('node:os');
+const fs = require('node:fs/promises');
+const { fail } = require('./common');
 
 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 };
+// Check every ancestor without creating anything, including for an absent cache.
+async function existingCacheDirectory(directory) {
+  directory = path.resolve(directory);
+  const parent = path.dirname(directory);
+  if (parent !== directory && !await existingCacheDirectory(parent)) return false;
+  let info;
+  try { info = await fs.lstat(directory); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  if (!info.isDirectory() || info.isSymbolicLink()) fail('Cache directory contains a link or non-directory');
+  return true;
+}
+module.exports = { cacheDirectory, existingCacheDirectory };

package/packaging/npm/lib/setup.js

@@ -0,0 +1,24 @@
+'use strict';
+
+function parseSetup(argv) {
+  if (argv[0] !== 'setup') return null;
+  if (argv.length === 1) return { checkOnly: false };
+  if (argv.length === 2 && argv[1] === '--check') return { checkOnly: true };
+  throw new Error('Usage: stackbite setup [--check]');
+}
+
+// Only static text goes to stderr: no URLs, environment, credentials or state.
+function stageReporter(stderr) {
+  const messages = {
+    download: 'Downloading pinned runtime...',
+    archive: 'Verifying archive...',
+    extract: 'Extracting runtime...',
+    validate: 'Validating runtime files...',
+    publish: 'Publishing runtime cache...',
+    'validate-published': 'Validating published runtime...',
+    ready: 'Pinned runtime is ready.'
+  };
+  return stage => stderr.write(`Stackbite: ${messages[stage]}\n`);
+}
+
+module.exports = { parseSetup, stageReporter };

package/packaging/npm/release.json

@@ -1,26 +1,26 @@
 {
   "schema": 1,
-  "version": "0.5.14",
-  "commit": "c6d3785cd4214aacaaead109498a8f054ef64844",
+  "version": "0.5.15",
+  "commit": "c62e74d00187186f8c7f9fe6b80ce80d0aed00dc",
   "repository": "Shinick-Han/stackbite",
   "platforms": {
     "win32-x64": {
-      "asset": "stackbite-0.5.14-windows-x64-c6d3785cd421.zip",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.14/stackbite-0.5.14-windows-x64-c6d3785cd421.zip",
-      "sha256": "414ef2c1bafddf92003b9389bd259304cc4e07f6948b87933338e18b7af032f2",
-      "size": 37060664,
-      "root": "stackbite-0.5.14-windows-x64-c6d3785cd421",
-      "manifestSha256": "d5283ac3758b1553dd1ec92fb1aeeca8c42b852271f851df520110f6fba388b6",
-      "metadataSha256": "e0816868d7380b0ff4c14533b0563aee60ca0f065ec776a4b125ce8035dab87d"
+      "asset": "stackbite-0.5.15-windows-x64-c62e74d00187.zip",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15-windows-x64-c62e74d00187.zip",
+      "sha256": "f9c9483e0a63a05dde48ff77f0c90cf02138b0344b7335d4bd1ce3210ed8b693",
+      "size": 37096893,
+      "root": "stackbite-0.5.15-windows-x64-c62e74d00187",
+      "manifestSha256": "e2d466a8b747b1028ddcf41a1274c9eb0dd29d8583575fafb9d15fb96561d50e",
+      "metadataSha256": "e79c47fa501317285c08fb57c213354abeff9b3cc333f4e9260eacc90919303d"
     },
     "linux-x64": {
-      "asset": "stackbite-0.5.14-linux-x86_64-c6d3785cd421.tar.gz",
-      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.14/stackbite-0.5.14-linux-x86_64-c6d3785cd421.tar.gz",
-      "sha256": "afd04f63cf1df2b95dc5816b772d6c4a093933496db202681db38576eaa2d915",
-      "size": 21859949,
-      "root": "stackbite-0.5.14-linux-x86_64-c6d3785cd421",
-      "manifestSha256": "4c4d12f3a06124adbcdebb597d925406c05947d4b526f36234d4da9ad3f15df9",
-      "metadataSha256": "2ad33dbdba97c140cb0b18842cfc93dbbd137f64c12400a33e774368343eb7b5"
+      "asset": "stackbite-0.5.15-linux-x86_64-c62e74d00187.tar.gz",
+      "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15-linux-x86_64-c62e74d00187.tar.gz",
+      "sha256": "fe64f4f640d63f993137c441b9037d6130cec5677dc01d70b8abee69c8ba10e1",
+      "size": 21897574,
+      "root": "stackbite-0.5.15-linux-x86_64-c62e74d00187",
+      "manifestSha256": "a3afdd606ec2e45a970eecef2d2df16594587390dd3fbe8028865fa3968f3e64",
+      "metadataSha256": "ecfbaa1e0e96f9a8c814719c039b95f4f1859781ab7b95d00e8c4254956ac74d"
     }
   }
 }