@christoph-teichmeister/shub 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# shub launcher
 
-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.
+Installs, updates and starts [shub](https://github.com/christoph-teichmeister/shub), your session hub: all your
+Claude Code sessions in one window. Linux and macOS (Windows only inside WSL2), Node 24+, tmux 3.3+, Claude Code.
+
+```sh
+npm i -g @christoph-teichmeister/shub && shub install && shub service install
+```
+
+| Command                                  | What it does                                                                  |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| `shub` / `shub start`                    | runs the installed version                                                    |
+| `shub install [--channel stable\|beta]`  | downloads and installs the latest release                                     |
+| `shub update [--to <version>] [--check]` | installs a newer release and restarts shub; rolls back if it does not come up |
+| `shub rollback`                          | switches back to the previous version                                         |
+| `shub service install\|uninstall`        | systemd user unit (Linux) or launchd agent (macOS)                            |
+| `shub doctor`                            | checks Node, tmux, Claude Code, Docker and the port                           |
+
+Every other command (`shub status`, `shub session start`, ...) goes to the installed version's CLI.
+
+Releases are verified before they are installed: the archive's SHA-256 must be in a `SHA256SUMS` signed with the
+shub release key (`release-keys.pem`). Versions live in `~/.local/share/shub/versions/` (`SHUB_HOME`), `current`
+points at the active one, the last two stay for rollback.

package/dist/doctor.js

@@ -0,0 +1,97 @@
+// `shub doctor`: is this machine ready for shub, and if not, what is missing.
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, existsSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { delimiter, join } from 'node:path';
+const atLeast = (have, need) => have[0] > need[0] || (have[0] === need[0] && have[1] >= need[1]);
+export async function doctor(d) {
+    const nodeOk = atLeast(d.nodeVersion.split('.').map(Number), [24, 0]);
+    const tmux = d.tmuxVersion();
+    const tmuxNum = /(\d+)\.(\d+)/.exec(tmux ?? '');
+    const tmuxOk = !!tmuxNum && atLeast([Number(tmuxNum[1]), Number(tmuxNum[2])], [3, 3]);
+    const claude = d.which('claude');
+    const docker = d.exists(d.dockerSocket);
+    const port = await d.portState(d.port);
+    return [
+        {
+            name: 'Node',
+            ok: nodeOk,
+            detail: nodeOk ? `Node ${d.nodeVersion}` : `Node ${d.nodeVersion} found, shub needs 24 or newer`,
+        },
+        {
+            name: 'tmux',
+            ok: tmuxOk,
+            detail: tmuxOk
+                ? tmux
+                : tmux
+                    ? `${tmux} found, shub needs 3.3 or newer`
+                    : 'tmux is not installed: shub needs 3.3 or newer (apt install tmux, brew install tmux)',
+        },
+        {
+            name: 'Claude Code',
+            ok: !!claude,
+            detail: claude ?? 'claude is not on PATH: install Claude Code and make sure `claude` runs in a terminal',
+        },
+        {
+            name: 'Docker',
+            ok: docker,
+            optional: true,
+            detail: docker
+                ? d.dockerSocket
+                : `no Docker socket at ${d.dockerSocket} (optional: the services panel stays empty)`,
+        },
+        {
+            name: 'Port',
+            ok: port !== 'busy',
+            detail: port === 'free'
+                ? `127.0.0.1:${d.port} is free`
+                : port === 'shub'
+                    ? `shub already answers on 127.0.0.1:${d.port}`
+                    : `127.0.0.1:${d.port} is used by another program: stop it or set SHUB_PORT`,
+        },
+    ];
+}
+function which(command, path = process.env.PATH ?? '') {
+    for (const dir of path.split(delimiter)) {
+        const file = join(dir, command);
+        try {
+            accessSync(file, constants.X_OK);
+            return file;
+        }
+        catch {
+            // next
+        }
+    }
+    return null;
+}
+async function portState(port) {
+    const free = await new Promise((resolve) => {
+        const server = createServer()
+            .once('error', () => resolve(false))
+            .listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+    });
+    if (free)
+        return 'free';
+    const health = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(2000) })
+        .then((r) => r.json())
+        .catch(() => null);
+    return health?.ok ? 'shub' : 'busy';
+}
+export function realDoctorDeps(env = process.env, port) {
+    return {
+        nodeVersion: process.versions.node,
+        tmuxVersion: () => {
+            try {
+                return execFileSync('tmux', ['-V'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            }
+            catch {
+                return null;
+            }
+        },
+        which: (c) => which(c, env.PATH),
+        exists: existsSync,
+        dockerSocket: env.DOCKER_SOCKET ?? '/var/run/docker.sock',
+        port,
+        portState,
+    };
+}

package/dist/releases.js

@@ -0,0 +1,82 @@
+// Where releases come from: the GitHub releases of christoph-teichmeister/shub, nothing else.
+// Tests point SHUB_TEST_RELEASES at a local fixture (file:// or http://127.0.0.1) with its own release-keys.pem.
+import { copyFile, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { pemKeys } from "./signing.js";
+export const REPO = 'christoph-teichmeister/shub';
+// ponytail: first page only; 100 releases cover months of betas. Page through (Link header) when they do not.
+const API_URL = `https://api.github.com/repos/${REPO}/releases?per_page=100`;
+const DOWNLOAD_PREFIX = `https://github.com/${REPO}/releases/download/`;
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+export const isVersion = (v) => VERSION.test(v);
+/** Semver order, which CalVer `YYYY.M.MICRO[-beta.N]` follows: a pre-release sorts before its release. */
+export function compareVersions(a, b) {
+    const pa = VERSION.exec(a);
+    const pb = VERSION.exec(b);
+    if (!pa || !pb)
+        throw new Error(`not a version: ${pa ? b : a}`);
+    for (let i = 1; i <= 3; i++)
+        if (Number(pa[i]) !== Number(pb[i]))
+            return Number(pa[i]) - Number(pb[i]);
+    if (!pa[4] || !pb[4])
+        return (pa[4] ? -1 : 0) - (pb[4] ? -1 : 0);
+    return pa[4].localeCompare(pb[4], 'en', { numeric: true }); // beta.2 < beta.10
+}
+/** Published releases with a version tag, newest first. */
+export function parseReleases(list) {
+    return list
+        .filter((r) => !r.draft && isVersion(r.tag_name.replace(/^v/, '')))
+        .map((r) => ({
+        version: r.tag_name.replace(/^v/, ''),
+        prerelease: r.prerelease,
+        notes: r.body ?? '',
+        assets: new Map(r.assets.map((a) => [a.name, a.browser_download_url])),
+    }))
+        .sort((a, b) => compareVersions(b.version, a.version));
+}
+/** stable: the newest non-prerelease; beta: the newest of all. */
+export function latest(releases, channel) {
+    return releases.find((r) => channel === 'beta' || !r.prerelease) ?? null;
+}
+/** Notes of every release on the channel after `from` up to and including `to`, newest first. */
+export function changelog(releases, channel, from, to) {
+    return releases
+        .filter((r) => (channel === 'beta' || !r.prerelease) && compareVersions(r.version, to) <= 0)
+        .filter((r) => !from || compareVersions(r.version, from) > 0)
+        .map((r) => `## ${r.version}\n\n${r.notes.trim()}`)
+        .join('\n\n');
+}
+export const archiveName = (version, platform = `${process.platform}-${process.arch}`) => `shub-${version}-${platform}.tar.gz`;
+async function get(url) {
+    if (url.startsWith('file:'))
+        return readFile(fileURLToPath(url));
+    const res = await fetch(url, { headers: { accept: 'application/vnd.github+json', 'user-agent': 'shub-launcher' } });
+    if (!res.ok)
+        throw new Error(`GET ${url} failed: ${res.status} ${res.statusText}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+/** The real GitHub source, or the local fixture named by SHUB_TEST_RELEASES (tests only). */
+export function source(env = process.env) {
+    const test = env.SHUB_TEST_RELEASES;
+    if (test && !/^(file:\/\/|http:\/\/(127\.0\.0\.1|localhost)[:/])/.test(test)) {
+        throw new Error('SHUB_TEST_RELEASES must be a file:// or http://127.0.0.1 URL');
+    }
+    const base = test ? (test.endsWith('/') ? test : `${test}/`) : null;
+    const prefix = base ?? DOWNLOAD_PREFIX;
+    return {
+        async releases() {
+            const list = JSON.parse((await get(base ? `${base}releases.json` : API_URL)).toString('utf8'));
+            return parseReleases(list);
+        },
+        async download(url, dest) {
+            if (!url.startsWith(prefix))
+                throw new Error(`refusing to download from ${url}: not under ${prefix}`);
+            if (url.startsWith('file:'))
+                return copyFile(fileURLToPath(url), dest);
+            await writeFile(dest, await get(url));
+        },
+        async testKeys() {
+            return base ? pemKeys((await get(`${base}release-keys.pem`)).toString('utf8')) : null;
+        },
+    };
+}

package/dist/service.js

@@ -0,0 +1,146 @@
+// `shub service install|uninstall`: a systemd user unit (Linux) or a launchd agent (macOS) that runs `shub start`.
+// Sessions live in shub's tmux server, a child of the service, so stopping the service must only stop shub itself:
+// KillMode=process (systemd) and AbandonProcessGroup (launchd). The updater relies on that too.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const MARKER = 'Written by `shub service install`';
+export const UNIT = 'shub.service';
+export const LABEL = 'com.github.christoph-teichmeister.shub';
+/** Environment the service needs: PATH (tmux, claude, docker), shub's own settings. */
+function serviceEnv(o) {
+    const out = {
+        NODE_ENV: 'production',
+        SHUB_HOME: o.home,
+        PATH: o.env.PATH ?? '/usr/bin:/bin',
+    };
+    for (const key of ['SHUB_PORT', 'SHUB_PUBLIC_URL', 'SHUB_CONFIG_DIR', 'SHUB_STATE_DIR']) {
+        if (o.env[key])
+            out[key] = o.env[key];
+    }
+    return out;
+}
+export function systemdUnit(o) {
+    const env = Object.entries(serviceEnv(o)).map(([k, v]) => `Environment="${k}=${v.replace(/["\\]/g, '\\$&')}"`);
+    return [
+        `# ${MARKER}; \`shub service uninstall\` removes it.`,
+        '[Unit]',
+        'Description=shub, your session hub',
+        'After=network.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        `ExecStart="${o.node}" "${o.launcher}" start`,
+        ...env,
+        'Restart=on-failure',
+        'RestartSec=3',
+        "# Sessions live in shub's tmux server, a child of this unit: keep it (and a running update) alive across restarts.",
+        'KillMode=process',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        '',
+    ].join('\n');
+}
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export function launchdPlist(o) {
+    const env = Object.entries(serviceEnv(o))
+        .map(([k, v]) => `      <key>${xml(k)}</key><string>${xml(v)}</string>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!-- ${MARKER}; \`shub service uninstall\` removes it. -->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key><string>${LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${xml(o.node)}</string>
+      <string>${xml(o.launcher)}</string>
+      <string>start</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+${env}
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+    <!-- Sessions live in shub's tmux server: keep it (and a running update) alive across restarts. -->
+    <key>AbandonProcessGroup</key><true/>
+    <key>StandardOutPath</key><string>${xml(join(o.home, 'shub.log'))}</string>
+    <key>StandardErrorPath</key><string>${xml(join(o.home, 'shub.log'))}</string>
+  </dict>
+</plist>
+`;
+}
+const runQuiet = (cmd, args) => void execFileSync(cmd, args, { stdio: 'ignore' });
+const succeeds = (run, cmd, args) => {
+    try {
+        run(cmd, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export function service(platform = process.platform, env = process.env, run = runQuiet) {
+    const darwin = platform === 'darwin';
+    const userHome = env.HOME ?? homedir();
+    const file = darwin
+        ? join(userHome, 'Library', 'LaunchAgents', `${LABEL}.plist`)
+        : join(env.XDG_CONFIG_HOME ?? join(userHome, '.config'), 'systemd', 'user', UNIT);
+    const target = `gui/${process.getuid?.() ?? 0}`;
+    const text = () => (existsSync(file) ? readFileSync(file, 'utf8') : null);
+    const ours = () => text()?.includes(MARKER) ?? true;
+    return {
+        file,
+        install(o, force = false) {
+            if (!ours() && !force) {
+                throw new Error(`${file} exists and was not written by shub; move it away or run with --force`);
+            }
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, darwin ? launchdPlist(o) : systemdUnit(o));
+            if (darwin) {
+                succeeds(run, 'launchctl', ['bootout', `${target}/${LABEL}`]);
+                run('launchctl', ['bootstrap', target, file]);
+                return `Installed ${file} and started it. Logs: ${join(o.home, 'shub.log')}`;
+            }
+            run('systemctl', ['--user', 'daemon-reload']);
+            run('systemctl', ['--user', 'enable', '--now', UNIT]);
+            return [
+                `Installed ${file} and started it. Logs: journalctl --user -u shub -f`,
+                'To keep shub running while you are logged out: loginctl enable-linger $USER',
+            ].join('\n');
+        },
+        uninstall() {
+            if (!existsSync(file))
+                return `No service installed (${file}).`;
+            if (!ours())
+                throw new Error(`${file} was not written by shub; remove it yourself`);
+            if (darwin)
+                succeeds(run, 'launchctl', ['bootout', `${target}/${LABEL}`]);
+            else
+                succeeds(run, 'systemctl', ['--user', 'disable', '--now', UNIT]);
+            rmSync(file);
+            if (!darwin)
+                run('systemctl', ['--user', 'daemon-reload']);
+            return `Removed ${file}. Sessions in tmux keep running.`;
+        },
+        active(home) {
+            const unit = text();
+            const forHome = darwin ? `<string>${xml(home)}</string>` : `SHUB_HOME=${home}"`;
+            if (!unit?.includes(MARKER) || !unit.includes(forHome))
+                return false;
+            return darwin
+                ? succeeds(run, 'launchctl', ['print', `${target}/${LABEL}`])
+                : succeeds(run, 'systemctl', ['--user', 'is-active', '--quiet', UNIT]);
+        },
+        restart() {
+            if (darwin)
+                run('launchctl', ['kickstart', '-k', `${target}/${LABEL}`]);
+            else
+                run('systemctl', ['--user', 'restart', UNIT]);
+        },
+    };
+}

package/dist/shub.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// The shub launcher: installs signed shub releases side by side, starts the active one and updates it.
+// Commands it does not know go to the CLI of the installed app version (`shub status`, `shub session ...`).
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { doctor, realDoctorDeps } from "./doctor.js";
+import { source } from "./releases.js";
+import { service } from "./service.js";
+import { channelFor, check, healthCheck, rollback, update } from "./update.js";
+import { currentVersion, readState, shubHome, writeState } from "./versions.js";
+const env = process.env;
+const self = fileURLToPath(import.meta.url);
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const HELP = `shub — your session hub (launcher ${pkg.version})
+
+Usage: shub [command]
+
+  start                         run the installed shub (the default)
+  install [--channel stable|beta]
+                                download and install the latest release
+  update [--to <version>] [--channel stable|beta] [--check] [--json]
+                                install a newer release and restart shub
+  rollback                      switch back to the previous version
+  service install|uninstall     run shub as a systemd user unit (Linux) or launchd agent (macOS)
+  doctor                        check Node, tmux, Claude Code, Docker and the port
+  --version                     launcher and app version
+
+Every other command goes to the installed app: shub status, shub project, shub session, shub open, ...
+("shub <command> --help" for its help).
+
+Environment: SHUB_HOME (default ~/.local/share/shub), SHUB_PORT (default 4780).`;
+class UsageError extends Error {
+}
+function flags(args, valued) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const m = /^--([a-z-]+)(?:=(.*))?$/.exec(args[i]);
+        if (!m)
+            throw new UsageError(`unexpected argument "${args[i]}"`);
+        if (m[2] !== undefined)
+            out[m[1]] = m[2];
+        else if (valued.includes(m[1])) {
+            if (args[i + 1] === undefined)
+                throw new UsageError(`--${m[1]} needs a value`);
+            out[m[1]] = args[++i];
+        }
+        else
+            out[m[1]] = true;
+    }
+    return out;
+}
+const str = (v) => (typeof v === 'string' ? v : undefined);
+/** The channel picked in the app's Settings (config.json); the launcher never writes that file. */
+function configuredChannel() {
+    const dir = env.SHUB_CONFIG_DIR ?? join(env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'shub');
+    try {
+        return JSON.parse(readFileSync(join(dir, 'config.json'), 'utf8')).updateChannel;
+    }
+    catch {
+        return undefined;
+    }
+}
+function deps(home) {
+    if (env.SHUB_TEST_RELEASES)
+        console.error(`shub: test releases from ${env.SHUB_TEST_RELEASES}, not GitHub`);
+    const port = Number(env.SHUB_PORT ?? readState(home).port ?? 4780);
+    return { home, source: source(env), service: service(), health: healthCheck(port), log: (l) => console.log(l) };
+}
+function currentDir(home) {
+    try {
+        return realpathSync(join(home, 'current'));
+    }
+    catch {
+        throw new UsageError('shub is not installed yet. Run: shub install');
+    }
+}
+/** Replace this process with the app (same PID, so systemd and launchd see the app itself). */
+function exec(home, args) {
+    const dir = currentDir(home);
+    process.chdir(dir);
+    return process.execve(process.execPath, [process.execPath, ...args(dir)], {
+        ...env,
+        SHUB_HOME: home,
+        SHUB_LAUNCHER: self,
+    });
+}
+async function main(argv) {
+    if (process.platform === 'win32') {
+        throw new UsageError('shub runs on Linux and macOS. On Windows, install it inside WSL2 (wsl --install) and run it there.');
+    }
+    const home = shubHome(env);
+    const [command = 'start', ...rest] = argv;
+    switch (command) {
+        case 'start': {
+            writeState(home, { port: Number(env.SHUB_PORT ?? 4780) });
+            return exec(home, (dir) => [join(dir, 'server', 'main.ts')]);
+        }
+        case 'install': {
+            const f = flags(rest, ['channel']);
+            const current = currentVersion(home);
+            if (current)
+                return void console.log(`shub ${current} is installed. Newer versions: shub update`);
+            await update(deps(home), { channel: channelFor(str(f.channel), configuredChannel(), null) });
+            return void console.log('Next: shub service install (runs shub in the background), or shub start');
+        }
+        case 'update': {
+            const f = flags(rest, ['to', 'channel']);
+            const channel = channelFor(str(f.channel), configuredChannel(), currentVersion(home));
+            if (f.check) {
+                const result = await check(deps(home), channel);
+                if (f.json)
+                    return void console.log(JSON.stringify(result));
+                return void console.log(result.latest
+                    ? `shub ${result.latest} is available:\n\n${result.changelog}`
+                    : `shub ${result.current} is up to date (${channel}).`);
+            }
+            const result = await update(deps(home), { to: str(f.to), channel });
+            if (result && !result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        case 'rollback': {
+            flags(rest, []);
+            const result = await rollback(deps(home));
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        case 'service': {
+            const [action, ...more] = rest;
+            const f = flags(more, []);
+            const s = service();
+            if (action === 'install') {
+                currentDir(home);
+                return void console.log(s.install({ node: process.execPath, launcher: self, home, env }, !!f.force));
+            }
+            if (action === 'uninstall')
+                return void console.log(s.uninstall());
+            throw new UsageError('usage: shub service install|uninstall');
+        }
+        case 'doctor': {
+            flags(rest, []);
+            const findings = await doctor(realDoctorDeps(env, Number(env.SHUB_PORT ?? 4780)));
+            for (const f of findings)
+                console.log(`${f.ok ? 'ok  ' : f.optional ? 'note' : 'FAIL'}  ${f.name.padEnd(12)}${f.detail}`);
+            if (findings.some((f) => !f.ok && !f.optional))
+                process.exitCode = 1;
+            return;
+        }
+        case '--version':
+        case '-v':
+            return void console.log(`launcher ${pkg.version}\napp ${currentVersion(home) ?? 'not installed (shub install)'}`);
+        case '--help':
+        case '-h':
+        case 'help':
+            return void console.log(HELP);
+        default:
+            return exec(home, (dir) => ['--no-warnings', join(dir, 'cli', 'shub.ts'), ...argv]);
+    }
+}
+main(process.argv.slice(2)).catch((err) => {
+    console.error(`shub: ${err instanceof Error && !(err instanceof TypeError) ? err.message : err.stack}`);
+    process.exitCode = 1;
+});

package/dist/signing.js

@@ -0,0 +1,69 @@
+// Release integrity: SHA256SUMS lists the archives, SHA256SUMS.sig is an ed25519 signature of it (base64).
+// An archive is installed only if its hash is in a SHA256SUMS that one of the trusted keys signed.
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { createReadStream, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The PEM public key blocks in a text (release-keys.pem allows comment lines around them). */
+export function pemKeys(text) {
+    return text.match(/-----BEGIN PUBLIC KEY-----[\s\S]+?-----END PUBLIC KEY-----/g) ?? [];
+}
+function readKeys(file) {
+    try {
+        return pemKeys(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Keys shipped with this launcher plus the ones in the installed app version, so a release signed with the old
+ * key can introduce a new one (docs/RELEASING.md).
+ */
+export function trustedKeys(currentDir) {
+    const bundled = readKeys(new URL('../release-keys.pem', import.meta.url));
+    return [...new Set([...bundled, ...(currentDir ? readKeys(join(currentDir, 'release-keys.pem')) : [])])];
+}
+export function sha256(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        createReadStream(file)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('end', () => resolve(hash.digest('hex')))
+            .on('error', reject);
+    });
+}
+/** `sha256sum` format: "<hex>  <name>" per line. */
+export function parseSums(text) {
+    const sums = new Map();
+    for (const line of text.split('\n')) {
+        const m = /^([0-9a-f]{64}) [ *](.+)$/.exec(line.trim());
+        if (m)
+            sums.set(m[2], m[1]);
+    }
+    return sums;
+}
+export function signatureValid(sums, signatureBase64, keys) {
+    const signature = Buffer.from(signatureBase64.trim(), 'base64');
+    return keys.some((pem) => {
+        try {
+            return verify(null, sums, createPublicKey(pem), signature);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Throws unless `archive` (published as `name`) is listed with its hash in a validly signed SHA256SUMS. */
+export async function verifyArchive(opts) {
+    if (!opts.keys.length)
+        throw new Error('no release keys to verify with');
+    if (!signatureValid(opts.sums, opts.signature, opts.keys)) {
+        throw new Error('SHA256SUMS is not signed by a shub release key; refusing to install');
+    }
+    const expected = parseSums(opts.sums.toString('utf8')).get(opts.name);
+    if (!expected)
+        throw new Error(`${opts.name} is not listed in SHA256SUMS; refusing to install`);
+    if ((await sha256(opts.archive)) !== expected) {
+        throw new Error(`${opts.name} does not match its SHA256SUMS entry; refusing to install`);
+    }
+}

package/dist/update.js

@@ -0,0 +1,149 @@
+// install / update / rollback: download, verify, unpack next to the old version, switch `current`, restart the
+// service and wait for the new version's /api/health. A version that does not come up within 30 s is rolled back.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { archiveName, changelog, compareVersions, isVersion, latest } from "./releases.js";
+import { trustedKeys, verifyArchive } from "./signing.js";
+import { currentVersion, lock, prune, readState, switchTo, versionDir, writeState, } from "./versions.js";
+/** Channel to follow: the flag, else the app's setting, else the kind of version that runs now. */
+export function channelFor(flag, configured, current) {
+    const pick = flag ?? configured;
+    if (pick === 'stable' || pick === 'beta')
+        return pick;
+    if (pick !== undefined)
+        throw new Error(`unknown channel "${pick}" (stable or beta)`);
+    return current?.includes('-') ? 'beta' : 'stable';
+}
+export async function check(deps, channel) {
+    const current = currentVersion(deps.home);
+    const releases = await deps.source.releases();
+    const newest = latest(releases, channel);
+    if (!newest || (current && compareVersions(newest.version, current) <= 0))
+        return { current, channel };
+    return { current, channel, latest: newest.version, changelog: changelog(releases, channel, current, newest.version) };
+}
+async function fetchVerified(deps, version) {
+    const release = (await deps.source.releases()).find((r) => r.version === version);
+    if (!release)
+        throw new Error(`there is no release ${version}`);
+    const name = archiveName(version, deps.platform);
+    const urls = [name, 'SHA256SUMS', 'SHA256SUMS.sig'].map((n) => {
+        const url = release.assets.get(n);
+        if (!url)
+            throw new Error(`release ${version} has no ${n}${n === name ? ' (no build for this platform)' : ''}`);
+        return url;
+    });
+    const dir = join(deps.home, 'downloads', `${version}.${process.pid}`);
+    const partial = join(deps.home, 'versions', `.${version}.${process.pid}.partial`);
+    mkdirSync(dir, { recursive: true });
+    try {
+        const [archive, sums, sig] = [name, 'SHA256SUMS', 'SHA256SUMS.sig'].map((n) => join(dir, n));
+        deps.log(`Downloading ${name}`);
+        await deps.source.download(urls[0], archive);
+        await deps.source.download(urls[1], sums);
+        await deps.source.download(urls[2], sig);
+        const current = currentVersion(deps.home);
+        const keys = (await deps.source.testKeys()) ?? trustedKeys(current ? versionDir(deps.home, current) : null);
+        await verifyArchive({ archive, name, sums: readFileSync(sums), signature: readFileSync(sig, 'utf8'), keys });
+        deps.log('Signature and checksum verified');
+        mkdirSync(partial, { recursive: true });
+        execFileSync('tar', ['-xzf', archive, '-C', partial, '--no-same-owner'], { stdio: 'ignore' });
+        if (!existsSync(join(partial, 'server', 'main.ts')))
+            throw new Error(`${name} has no server/main.ts`);
+        renameSync(partial, versionDir(deps.home, version));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+        rmSync(partial, { recursive: true, force: true });
+    }
+}
+function record(deps, last, patch = {}) {
+    writeState(deps.home, { ...patch, last });
+    deps.log(last.message);
+    return last;
+}
+/** Switch to `to`, restart and health-check it when shub runs as a service; switch back if it does not come up. */
+async function activate(deps, to, verb) {
+    const from = currentVersion(deps.home);
+    const before = readState(deps.home).previous;
+    const at = new Date().toISOString();
+    switchTo(deps.home, to);
+    writeState(deps.home, { previous: from ?? undefined });
+    if (!deps.service.active(deps.home)) {
+        const message = from ? `${verb} ${to}. Restart shub to use it.` : `Installed ${to}.`;
+        return record(deps, { at, from, to, ok: true, message });
+    }
+    deps.log(`Restarting shub with ${to}`);
+    deps.service.restart();
+    const timeout = deps.healthTimeoutMs ?? 30_000;
+    if (await deps.health(to, timeout))
+        return record(deps, { at, from, to, ok: true, message: `${verb} ${to}.` });
+    const seconds = Math.round(timeout / 1000);
+    if (!from)
+        return record(deps, { at, from, to, ok: false, message: `${to} did not answer within ${seconds} s.` });
+    switchTo(deps.home, from);
+    deps.service.restart();
+    return record(deps, {
+        at,
+        from,
+        to,
+        ok: false,
+        message: `${to} did not answer /api/health within ${seconds} s; rolled back to ${from}.`,
+    }, { previous: before });
+}
+/** Install `to` (or the newest release on the channel) and switch to it. */
+export async function update(deps, opts) {
+    if (opts.to !== undefined && !isVersion(opts.to))
+        throw new Error(`not a version: ${opts.to}`);
+    const unlock = lock(deps.home);
+    try {
+        const current = currentVersion(deps.home);
+        const target = opts.to ?? (await check(deps, opts.channel)).latest;
+        if (!target && !current)
+            throw new Error(`there is no ${opts.channel} release yet`);
+        if (!target || target === current) {
+            deps.log(`shub ${current} is up to date (${opts.channel}).`);
+            return null;
+        }
+        if (!existsSync(versionDir(deps.home, target)))
+            await fetchVerified(deps, target);
+        const result = await activate(deps, target, compareVersions(target, current ?? target) < 0 ? 'Switched to' : 'Updated to');
+        for (const v of prune(deps.home))
+            deps.log(`Removed old version ${v}`);
+        return result;
+    }
+    finally {
+        unlock();
+    }
+}
+export async function rollback(deps) {
+    const unlock = lock(deps.home);
+    try {
+        const previous = readState(deps.home).previous;
+        if (!previous || !existsSync(versionDir(deps.home, previous)))
+            throw new Error('there is no previous version to roll back to');
+        return await activate(deps, previous, 'Rolled back to');
+    }
+    finally {
+        unlock();
+    }
+}
+/** Polls http://127.0.0.1:<port>/api/health until it reports `version`. */
+export function healthCheck(port) {
+    return async (version, timeoutMs) => {
+        const until = Date.now() + timeoutMs;
+        while (Date.now() < until) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(2000) });
+                if (res.ok && (await res.json()).version === version)
+                    return true;
+            }
+            catch {
+                // not up yet
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        return false;
+    };
+}

package/dist/versions.js

@@ -0,0 +1,85 @@
+// App versions side by side: <home>/versions/<version>/, <home>/current -> versions/<version>.
+// <home>/launcher.json remembers the previous version and the last update result (the app shows it in Settings).
+import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { compareVersions, isVersion } from "./releases.js";
+export function shubHome(env = process.env) {
+    return env.SHUB_HOME ?? join(env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), 'shub');
+}
+export const versionDir = (home, version) => join(home, 'versions', version);
+export function currentVersion(home) {
+    try {
+        return basename(readlinkSync(join(home, 'current')));
+    }
+    catch {
+        return null;
+    }
+}
+export function installedVersions(home) {
+    const dir = join(home, 'versions');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(isVersion)
+        .sort((a, b) => compareVersions(b, a));
+}
+export function readState(home) {
+    try {
+        return JSON.parse(readFileSync(join(home, 'launcher.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeState(home, patch) {
+    const next = { ...readState(home), ...patch };
+    const file = join(home, 'launcher.json');
+    mkdirSync(home, { recursive: true });
+    writeFileSync(`${file}.${process.pid}.tmp`, JSON.stringify(next, null, 2) + '\n');
+    renameSync(`${file}.${process.pid}.tmp`, file);
+    return next;
+}
+/** Points `current` at an installed version in one rename, so a reader never sees a missing link. */
+export function switchTo(home, version) {
+    if (!existsSync(versionDir(home, version)))
+        throw new Error(`version ${version} is not installed`);
+    const tmp = join(home, `current.${process.pid}.tmp`);
+    rmSync(tmp, { force: true });
+    symlinkSync(join('versions', version), tmp);
+    renameSync(tmp, join(home, 'current'));
+}
+/** Keeps current, previous and the newest others, three in all (the last two plus current); returns the removed. */
+export function prune(home) {
+    const pinned = new Set([currentVersion(home), readState(home).previous].filter((v) => !!v));
+    const removed = installedVersions(home)
+        .filter((v) => !pinned.has(v))
+        .slice(Math.max(0, 3 - pinned.size));
+    for (const v of removed)
+        rmSync(versionDir(home, v), { recursive: true, force: true });
+    return removed;
+}
+function running(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** One update at a time; a lock left by a dead process is taken over. */
+export function lock(home) {
+    mkdirSync(home, { recursive: true });
+    const file = join(home, 'update.lock');
+    try {
+        writeFileSync(file, String(process.pid), { flag: 'wx' });
+    }
+    catch {
+        const pid = Number(readFileSync(file, 'utf8'));
+        if (pid > 0 && pid !== process.pid && running(pid))
+            throw new Error(`another update is running (pid ${pid})`);
+        writeFileSync(file, String(process.pid));
+    }
+    return () => rmSync(file, { force: true });
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@christoph-teichmeister/shub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Launcher for shub, your session hub: installs, updates and starts signed shub releases.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/christoph-teichmeister/shub.git",
+    "directory": "launcher"
+  },
+  "bin": {
+    "shub": "dist/shub.js"
+  },
+  "files": [
+    "dist",
+    "release-keys.pem"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/release-keys.pem

@@ -0,0 +1,7 @@
+Public keys that sign shub releases (ed25519). An archive is installed only when SHA256SUMS carries a valid
+signature from one of these keys, or from one in the release-keys.pem of the installed app version.
+Rotation: docs/RELEASING.md.
+
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA3GqPSkgj4f9Unv1UYF8kHutUYzk3r/IZhVauvoa7h5U=
+-----END PUBLIC KEY-----