stackbite 0.5.13 → 0.5.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,108 +1,146 @@
1
- # Stackbite through npm and npx
2
-
3
- Work Stack organizes the work. Stackbite gets it moving.
4
-
5
- Node.js 20 or newer is required. The portable runtime is available for Windows x64
6
- and Linux x64 with glibc; macOS, ARM and musl/Alpine builds are not supplied yet.
7
- Python installation and compilation are unnecessary. Archive extraction requires
8
- `tar` (included in current Windows and common Linux distributions).
9
-
10
- ## Install without an account
11
-
12
- Choose one method. For a single run, use the public npm package:
13
-
14
- ```sh
15
- npx --yes stackbite
16
- ```
17
-
18
- For a persistent command, install it globally and then run it:
19
-
20
- ```sh
21
- npm install --global stackbite
22
- stackbite
23
- ```
24
-
25
- Both methods download the verified native runtime on first execution. Global
26
- installation alone installs the small launcher; its first `stackbite` invocation
27
- downloads the runtime. Running both installation methods is unnecessary.
28
-
29
- Update a registry installation with `npm install --global stackbite@latest`.
30
-
31
- ## Direct GitHub package
32
-
33
- Run the package attached to the verified GitHub release:
34
-
35
- ```sh
36
- npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.13/stackbite-0.5.13.tgz
37
- ```
38
-
39
- Arguments go after the package URL, for example `--version` or `--status`. For a
40
- persistent command, install that same package globally:
41
-
42
- ```sh
43
- npm install --global https://github.com/Shinick-Han/stackbite/releases/download/v0.5.13/stackbite-0.5.13.tgz
44
- stackbite
45
- ```
46
-
47
- The core source repository remains private at `Shinick-Han/helm`. The separate
48
- public `Shinick-Han/stackbite` repository distributes only this thin launcher and
49
- verified compiled runtime releases; installers need no GitHub or npm login.
50
- Registry-free distribution does not require publishing rights on npm.
51
- The small JavaScript package downloads the
52
- exact pinned native release on first execution, verifies its archive and file
53
- checksums and product identity, then reuses a persistent binary cache. There is no
54
- postinstall download or provider installation. An offline cached launch is possible;
55
- the first launch needs access to GitHub release downloads.
56
-
57
- For a GitHub URL installation, install the package URL from the newer release.
58
- Each npm package pins one native release; the portable app's own `stackbite update`
59
- does not change the npm package version.
60
-
61
- ## Existing data and processes
62
-
63
- `STACKBITE_STATE_DIR` is the explicit state override. The bundled native runtime
64
- owns state discovery and migration for both npm and direct launches. It reuses
65
- existing configured state and keeps live databases, authentication and records
66
- in place. New state uses `%LOCALAPPDATA%\Stackbite\state` or
67
- `${XDG_STATE_HOME:-~/.local/state}/stackbite`.
68
- Rooms, Seats, authentication, provider configuration, journals and Work Stack
69
- contracts are not renamed or migrated. Binary cache data is separate from this
70
- state. Installing or launching the npm package does not stop an existing backend.
71
- Check the connected server's capabilities before using newly added runtime features.
72
-
73
- The launcher inherits terminal input/output and passes CLI arguments directly to
74
- the native app. It does not insert a second screen renderer or an agent provider.
75
- Global npm installation creates only the `stackbite` command; it does not claim an
76
- external `helm` command or replace independent Kubernetes tooling.
77
-
78
- ## Maintainer release steps
79
-
80
- Build and verify both native platform archives first. Prepare the pinned manifest
81
- from their exact extracted bundles and archive bytes:
82
-
83
- ```sh
84
- python scripts/prepare_npm_release.py --version 0.5.13
85
- npm test
86
- npm pack
87
- ```
88
-
89
- Keep `package.json` and `packaging/npm/release.json` versions equal. Inspect `npm
90
- pack --dry-run` before publishing; the package must include the launcher and pinned
91
- manifest, and exclude native runtimes, installed state, credentials, tests and
92
- development worktrees. Test the packed package with `npx` on both platforms.
93
-
94
- Attach `stackbite-<version>.tgz` and its SHA-256 sidecar to the corresponding GitHub
95
- release in the public distribution repository. Copy only the npm file allowlist to
96
- that repository; never push the private core history, state, personal notes or
97
- credentials. Native archives must retain dependency license notices. Publishing
98
- the short name requires an authenticated owner account:
99
-
100
- ```sh
101
- npm login --registry=https://registry.npmjs.org
102
- npm publish --access public --registry=https://registry.npmjs.org
103
- ```
104
-
105
- Complete any registry-required authentication interactively; do not put credentials
106
- in this repository, prompts or package files. The repository currently specifies
107
- `UNLICENSED` for the JavaScript wrapper instead of inventing a license for the app;
108
- native runtime dependency notices remain in each platform archive.
1
+ # Stackbite through npm and npx
2
+
3
+ Work Stack organizes the work. Stackbite gets it moving.
4
+
5
+ Node.js 20 or newer is required. The portable runtime is available for Windows x64
6
+ and Linux x64 with glibc; macOS, ARM and musl/Alpine builds are not supplied yet.
7
+ Python installation and compilation are unnecessary. Archive extraction requires
8
+ `tar` (included in current Windows and common Linux distributions).
9
+
10
+ ## Install without an account
11
+
12
+ Choose one method. For a single run, use the public npm package:
13
+
14
+ ```sh
15
+ npx --yes stackbite
16
+ ```
17
+
18
+ For a persistent command, install it globally, prepare the runtime, then launch:
19
+
20
+ ```sh
21
+ npm install --global stackbite
22
+ stackbite setup
23
+ stackbite
24
+ ```
25
+
26
+ Global installation installs the small launcher without a postinstall download.
27
+ `stackbite setup` downloads and fully validates its pinned runtime without starting
28
+ the app or backend. It prints short stages to stderr. If setup is omitted, the
29
+ first launch prepares the runtime with the same stages. Cached launches remain
30
+ quiet and fully validate the runtime every time. Running both installation methods
31
+ is unnecessary.
32
+
33
+ The same preparation command works through npx:
34
+
35
+ ```sh
36
+ npx --yes stackbite setup
37
+ ```
38
+
39
+ Check a prepared runtime offline with `stackbite setup --check`. The launcher
40
+ checks all pinned file hashes, identity, inventory and link boundaries, without
41
+ downloading, extracting, writing cache files, or starting the app/backend. It exits
42
+ with status 0 when valid and status 1 when absent or invalid; an absent cache needs
43
+ `stackbite setup`. Only `setup` and `setup --check` are accepted setup forms.
44
+ The launcher check is read-only; npx itself may install its npm package before
45
+ invoking it, so use the installed command for an entirely offline check.
46
+
47
+ Binary caches use `%LOCALAPPDATA%\Stackbite\cache` on Windows and
48
+ `${XDG_CACHE_HOME:-~/.cache}/stackbite` on Linux. `LOCALAPPDATA`, `XDG_CACHE_HOME`
49
+ and `HOME` overrides retain their normal behavior. These caches are separate from
50
+ application state. Interrupted preparation removes only its own temporary staging
51
+ directory and can be retried. An invalid existing runtime is reported and left in
52
+ place; setup does not delete or overwrite it.
53
+
54
+ Update a registry installation with `npm install --global stackbite@latest`.
55
+
56
+ ## Direct GitHub package
57
+
58
+ Run the package attached to the verified GitHub release:
59
+
60
+ ```sh
61
+ npx --yes https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15.tgz
62
+ ```
63
+
64
+ Arguments go after the package URL, for example `--version` or `--status`. For a
65
+ persistent command, install that same package globally:
66
+
67
+ ```sh
68
+ npm install --global https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15.tgz
69
+ stackbite setup
70
+ stackbite
71
+ ```
72
+
73
+ The core source repository remains private at `Shinick-Han/helm`. The separate
74
+ public `Shinick-Han/stackbite` repository distributes only this thin launcher and
75
+ verified compiled runtime releases; installers need no GitHub or npm login.
76
+ Registry-free distribution does not require publishing rights on npm.
77
+ The small JavaScript package downloads the
78
+ exact pinned native release on first execution, verifies its archive and file
79
+ checksums and product identity, then reuses a persistent binary cache. There is no
80
+ postinstall download or provider installation. An offline cached launch is possible;
81
+ the first launch needs access to GitHub release downloads.
82
+
83
+ For a GitHub URL installation, install the package URL from the newer release.
84
+ Each npm package pins one native release; the portable app's own `stackbite update`
85
+ does not change the npm package version.
86
+
87
+ ## Existing data and processes
88
+
89
+ `STACKBITE_STATE_DIR` is the explicit state override. The bundled native runtime
90
+ owns state discovery and migration for both npm and direct launches. It reuses
91
+ existing configured state and keeps live databases, authentication and records
92
+ in place. New state uses `%LOCALAPPDATA%\Stackbite\state` or
93
+ `${XDG_STATE_HOME:-~/.local/state}/stackbite`.
94
+ Rooms, Seats, authentication, provider configuration, journals and Work Stack
95
+ contracts are not renamed or migrated. Binary cache data is separate from this
96
+ state. Installing or launching the npm package does not stop an existing backend.
97
+ Check the connected server's capabilities before using newly added runtime features.
98
+
99
+ For app commands, the launcher inherits terminal input/output and passes CLI
100
+ arguments directly to the native app. Its `setup` command only prepares/checks the
101
+ runtime. It does not insert a second screen renderer or an agent provider.
102
+ Global npm installation creates only the `stackbite` command; it does not claim an
103
+ external `helm` command or replace independent Kubernetes tooling.
104
+
105
+ ## Maintainer release steps
106
+
107
+ Measure bounded fake runtime preparation and warm verification without network or
108
+ app processes:
109
+
110
+ ```sh
111
+ node packaging/npm/test/measure-setup.js
112
+ ```
113
+
114
+ The measurement reports fixture sizes and each preparation stage plus warm check
115
+ and launch validation costs. It uses disposable cache data and an inert child
116
+ stub; its timings are not measurements of released native bundles or providers.
117
+
118
+ Build and verify both native platform archives first. Prepare the pinned manifest
119
+ from their exact extracted bundles and archive bytes:
120
+
121
+ ```sh
122
+ python scripts/prepare_npm_release.py --version 0.5.15
123
+ npm test
124
+ npm pack
125
+ ```
126
+
127
+ Keep `package.json` and `packaging/npm/release.json` versions equal. Inspect `npm
128
+ pack --dry-run` before publishing; the package must include the launcher and pinned
129
+ manifest, and exclude native runtimes, installed state, credentials, tests and
130
+ development worktrees. Test the packed package with `npx` on both platforms.
131
+
132
+ Attach `stackbite-<version>.tgz` and its SHA-256 sidecar to the corresponding GitHub
133
+ release in the public distribution repository. Copy only the npm file allowlist to
134
+ that repository; never push the private core history, state, personal notes or
135
+ credentials. Native archives must retain dependency license notices. Publishing
136
+ the short name requires an authenticated owner account:
137
+
138
+ ```sh
139
+ npm login --registry=https://registry.npmjs.org
140
+ npm publish --access public --registry=https://registry.npmjs.org
141
+ ```
142
+
143
+ Complete any registry-required authentication interactively; do not put credentials
144
+ in this repository, prompts or package files. The repository currently specifies
145
+ `UNLICENSED` for the JavaScript wrapper instead of inventing a license for the app;
146
+ native runtime dependency notices remain in each platform archive.
package/package.json CHANGED
@@ -1,25 +1,25 @@
1
- {
2
- "name": "stackbite",
3
- "version": "0.5.13",
4
- "description": "Verified native Stackbite CLI bootstrapper",
5
- "license": "UNLICENSED",
6
- "engines": {
7
- "node": ">=20"
8
- },
9
- "bin": {
10
- "stackbite": "packaging/npm/bin/stackbite.js"
11
- },
12
- "files": [
13
- "packaging/npm/bin/",
14
- "packaging/npm/lib/",
15
- "packaging/npm/release.json"
16
- ],
17
- "scripts": {
18
- "test": "node --test packaging/npm/test/*.test.js"
19
- },
20
- "repository": {
21
- "type": "git",
22
- "url": "https://github.com/Shinick-Han/stackbite.git"
23
- },
24
- "homepage": "https://github.com/Shinick-Han/stackbite"
25
- }
1
+ {
2
+ "name": "stackbite",
3
+ "version": "0.5.15",
4
+ "description": "Verified native Stackbite CLI bootstrapper",
5
+ "license": "UNLICENSED",
6
+ "engines": {
7
+ "node": ">=20"
8
+ },
9
+ "bin": {
10
+ "stackbite": "packaging/npm/bin/stackbite.js"
11
+ },
12
+ "files": [
13
+ "packaging/npm/bin/",
14
+ "packaging/npm/lib/",
15
+ "packaging/npm/release.json"
16
+ ],
17
+ "scripts": {
18
+ "test": "node --test packaging/npm/test/*.test.js"
19
+ },
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "https://github.com/Shinick-Han/stackbite.git"
23
+ },
24
+ "homepage": "https://github.com/Shinick-Han/stackbite"
25
+ }
@@ -6,7 +6,8 @@ const { createHash } = require('node:crypto');
6
6
  const { LIMITS, fail, memberPath, inside, hashFile, readSmall, exists, safeDirectory } = require('./common');
7
7
  const { download } = require('./download');
8
8
  const { extractArchive } = require('./archive');
9
- const { cacheDirectory } = require('./cache');
9
+ const { cacheDirectory, existingCacheDirectory } = require('./cache');
10
+ const { parseSetup, stageReporter } = require('./setup');
10
11
  const packageVersion = require('../../../package.json').version;
11
12
 
12
13
  function releaseSpec(manifest, platform = process.platform, arch = process.arch, runtime = {}) {
@@ -95,28 +96,46 @@ async function validatePayload(directory, spec) {
95
96
  if (spec.platform === 'linux' && process.platform !== 'win32' && !(image.mode & 0o111)) fail('Native release executable has no execute permission');
96
97
  return executable;
97
98
  }
98
- async function ensureBinary(spec, { cache = cacheDirectory(), downloadImpl = download, extractImpl = extractArchive } = {}) {
99
+ async function ensureBinary(spec, { cache = cacheDirectory(), downloadImpl = download, extractImpl = extractArchive,
100
+ checkOnly = false, reportCached = false, progress = () => {} } = {}) {
99
101
  cache = path.resolve(cache);
100
- await safeDirectory(cache);
102
+ if (checkOnly) {
103
+ if (!await existingCacheDirectory(cache)) fail('Pinned runtime is not cached; run stackbite setup.');
104
+ } else await safeDirectory(cache);
101
105
  const target = path.join(cache, `${spec.version}-${spec.commit}-${spec.key}-${spec.sha256}`);
102
- if (await exists(target)) return { home: target, executable: await validatePayload(target, spec) };
106
+ if (await exists(target)) {
107
+ if (checkOnly || reportCached) progress('validate');
108
+ const installed = { home: target, executable: await validatePayload(target, spec) };
109
+ if (checkOnly || reportCached) progress('ready');
110
+ return installed;
111
+ }
112
+ if (checkOnly) fail('Pinned runtime is not cached; run stackbite setup.');
103
113
  const staging = await fs.mkdtemp(path.join(cache, '.staging-'));
104
114
  try {
105
115
  const archive = path.join(staging, spec.asset), extraction = path.join(staging, 'extract');
106
116
  await fs.mkdir(extraction, { mode: 0o700 });
117
+ progress('download');
107
118
  await downloadImpl(spec, archive);
108
119
  // Recheck at the extraction boundary, including for injected test transports.
120
+ progress('archive');
109
121
  if ((await fs.stat(archive)).size !== spec.size || await hashFile(archive, LIMITS.download) !== spec.sha256) fail('Pinned archive SHA-256 or size mismatch');
122
+ progress('extract');
110
123
  await extractImpl(archive, extraction, spec);
111
124
  const payload = path.join(extraction, spec.root);
125
+ progress('validate');
112
126
  await validatePayload(payload, spec);
127
+ progress('publish');
113
128
  try { await fs.rename(payload, target); }
114
129
  catch (error) {
115
130
  // Another process may have installed the same immutable payload first.
116
131
  // Never delete/rewrite its directory or try a destructive rename retry.
117
132
  if (!await exists(target)) throw error;
118
133
  }
119
- return { home: target, executable: await validatePayload(target, spec) };
134
+ // Validate at the final path, including a concurrent publisher's payload.
135
+ progress('validate-published');
136
+ const installed = { home: target, executable: await validatePayload(target, spec) };
137
+ progress('ready');
138
+ return installed;
120
139
  } finally {
121
140
  // Only this mkdtemp handle is owned by this invocation.
122
141
  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,
138
157
  });
139
158
  }
140
159
  async function main(argv = process.argv.slice(2), options = {}) {
160
+ const setup = parseSetup(argv);
141
161
  const manifest = options.manifest || require('../release.json');
142
162
  const platform = options.platform || process.platform;
143
163
  const environment = options.environment || process.env;
144
164
  const spec = releaseSpec(manifest, platform, options.arch || process.arch, options);
145
- const installed = await ensureBinary(spec, { ...options, cache: options.cache || cacheDirectory(environment, platform) });
165
+ const installed = await ensureBinary(spec, { ...options, cache: options.cache || cacheDirectory(environment, platform),
166
+ checkOnly: setup?.checkOnly || false, reportCached: Boolean(setup),
167
+ progress: options.progress || stageReporter(options.stderr || process.stderr) });
168
+ if (setup) return { code: 0, signal: null };
146
169
  // The bundled runtime owns state discovery and migration for every entrypoint.
147
170
  return launchNative(installed.executable, argv, { ...environment,
148
171
  STACKBITE_HOME: path.resolve(installed.home) }, options);
@@ -1,10 +1,23 @@
1
1
  'use strict';
2
2
  const path = require('node:path');
3
3
  const os = require('node:os');
4
+ const fs = require('node:fs/promises');
5
+ const { fail } = require('./common');
4
6
 
5
7
  function cacheDirectory(environment = process.env, platform = process.platform, home = os.homedir()) {
6
8
  return platform === 'win32'
7
9
  ? path.resolve(environment.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Stackbite', 'cache')
8
10
  : path.resolve(environment.XDG_CACHE_HOME || path.join(environment.HOME || home, '.cache'), 'stackbite');
9
11
  }
10
- module.exports = { cacheDirectory };
12
+ // Check every ancestor without creating anything, including for an absent cache.
13
+ async function existingCacheDirectory(directory) {
14
+ directory = path.resolve(directory);
15
+ const parent = path.dirname(directory);
16
+ if (parent !== directory && !await existingCacheDirectory(parent)) return false;
17
+ let info;
18
+ try { info = await fs.lstat(directory); }
19
+ catch (error) { if (error.code === 'ENOENT') return false; throw error; }
20
+ if (!info.isDirectory() || info.isSymbolicLink()) fail('Cache directory contains a link or non-directory');
21
+ return true;
22
+ }
23
+ module.exports = { cacheDirectory, existingCacheDirectory };
@@ -0,0 +1,24 @@
1
+ 'use strict';
2
+
3
+ function parseSetup(argv) {
4
+ if (argv[0] !== 'setup') return null;
5
+ if (argv.length === 1) return { checkOnly: false };
6
+ if (argv.length === 2 && argv[1] === '--check') return { checkOnly: true };
7
+ throw new Error('Usage: stackbite setup [--check]');
8
+ }
9
+
10
+ // Only static text goes to stderr: no URLs, environment, credentials or state.
11
+ function stageReporter(stderr) {
12
+ const messages = {
13
+ download: 'Downloading pinned runtime...',
14
+ archive: 'Verifying archive...',
15
+ extract: 'Extracting runtime...',
16
+ validate: 'Validating runtime files...',
17
+ publish: 'Publishing runtime cache...',
18
+ 'validate-published': 'Validating published runtime...',
19
+ ready: 'Pinned runtime is ready.'
20
+ };
21
+ return stage => stderr.write(`Stackbite: ${messages[stage]}\n`);
22
+ }
23
+
24
+ module.exports = { parseSetup, stageReporter };
@@ -1,26 +1,26 @@
1
1
  {
2
2
  "schema": 1,
3
- "version": "0.5.13",
4
- "commit": "1f9566f7beeb3c65047a78225c898515ad4daf1c",
3
+ "version": "0.5.15",
4
+ "commit": "c62e74d00187186f8c7f9fe6b80ce80d0aed00dc",
5
5
  "repository": "Shinick-Han/stackbite",
6
6
  "platforms": {
7
7
  "win32-x64": {
8
- "asset": "stackbite-0.5.13-windows-x64-1f9566f7beeb.zip",
9
- "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.13/stackbite-0.5.13-windows-x64-1f9566f7beeb.zip",
10
- "sha256": "bf99f38caae227615630a21f50164e75851ec1cc7b86b3beba05ec7c422e9bd6",
11
- "size": 37054024,
12
- "root": "stackbite-0.5.13-windows-x64-1f9566f7beeb",
13
- "manifestSha256": "21da147603c380b6c451dbf23de04713294c6bc7e31c0f1bd499f3008df61f5e",
14
- "metadataSha256": "c09a29cc8bb734e5a0a71d1f07ba20ca9c8d44117889f68ba1e41e96ea784a20"
8
+ "asset": "stackbite-0.5.15-windows-x64-c62e74d00187.zip",
9
+ "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15-windows-x64-c62e74d00187.zip",
10
+ "sha256": "f9c9483e0a63a05dde48ff77f0c90cf02138b0344b7335d4bd1ce3210ed8b693",
11
+ "size": 37096893,
12
+ "root": "stackbite-0.5.15-windows-x64-c62e74d00187",
13
+ "manifestSha256": "e2d466a8b747b1028ddcf41a1274c9eb0dd29d8583575fafb9d15fb96561d50e",
14
+ "metadataSha256": "e79c47fa501317285c08fb57c213354abeff9b3cc333f4e9260eacc90919303d"
15
15
  },
16
16
  "linux-x64": {
17
- "asset": "stackbite-0.5.13-linux-x86_64-1f9566f7beeb.tar.gz",
18
- "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.13/stackbite-0.5.13-linux-x86_64-1f9566f7beeb.tar.gz",
19
- "sha256": "e2277298ae038c31036522d5f7d8815f9250a1a46db338f35692e5141430bd66",
20
- "size": 21758373,
21
- "root": "stackbite-0.5.13-linux-x86_64-1f9566f7beeb",
22
- "manifestSha256": "f4919ff43530dbb445b00ed68d3af7c1aa33ad3bb1dfd657d8ef18bf8e38ca62",
23
- "metadataSha256": "fa3c3f3a35bb40a65fbbb0c4823d092b2ca500121bd8ac48323a0317eb3c8b7c"
17
+ "asset": "stackbite-0.5.15-linux-x86_64-c62e74d00187.tar.gz",
18
+ "url": "https://github.com/Shinick-Han/stackbite/releases/download/v0.5.15/stackbite-0.5.15-linux-x86_64-c62e74d00187.tar.gz",
19
+ "sha256": "fe64f4f640d63f993137c441b9037d6130cec5677dc01d70b8abee69c8ba10e1",
20
+ "size": 21897574,
21
+ "root": "stackbite-0.5.15-linux-x86_64-c62e74d00187",
22
+ "manifestSha256": "a3afdd606ec2e45a970eecef2d2df16594587390dd3fbe8028865fa3968f3e64",
23
+ "metadataSha256": "ecfbaa1e0e96f9a8c814719c039b95f4f1859781ab7b95d00e8c4254956ac74d"
24
24
  }
25
25
  }
26
26
  }