@withbuddi/buddi 0.1.0-pre.38 → 0.1.0-pre.39

package/packages/install/dist/upgrade.js

@@ -39,7 +39,7 @@
 import { execFile } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { request } from 'node:http';
-import { open, readFile } from 'node:fs/promises';
+import { open, readFile, realpath, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 /*
@@ -53,6 +53,7 @@ import { compareSemver, parseSemver } from '@buddi/core/semver';
 import { atomicJson, launchAgentLabel, SERVICE_UNIT_VAR } from './environment.js';
 import { JobStore } from './backup.js';
 import { createPostgresCheck } from './postgres-check.js';
+import { APP_BUNDLE, appLayout, insideAppBundle, placeRelease, pruneReleases, releaseDir, stageRelease, switchCurrent } from './app-layout.js';
 const run = promisify(execFile);
 /** Where `buddi` is published, and where the check and the install both look. */
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
@@ -177,6 +178,7 @@ export async function readUpgradeState(data, current) {
             ...(typeof check.latest === 'string' ? { latest: check.latest } : {}),
             ...(typeof check.latest === 'string' && typeof check.latestNotes === 'string' ? { latestNotes: check.latestNotes } : {}),
             ...(typeof check.error === 'string' ? { error: check.error } : {}),
+            ...(typeof check.processing === 'string' && check.processing === check.latest ? { processing: check.processing } : {}),
         },
         current,
         ...(typeof parsed.registry === 'string' ? { registry: parsed.registry } : {}),
@@ -188,17 +190,177 @@ export async function writeUpgradeState(data, state) {
     await atomicJson(upgradeStateFile(data), { ...state, history: state.history.slice(-HISTORY_LIMIT) });
 }
 export function versionView(state) {
+    const newer = isNewer(state.check.latest, state.current);
+    const processing = newer && state.check.processing !== undefined && state.check.processing === state.check.latest ? state.check.processing : undefined;
     return {
         current: state.current,
         ...(state.check.latest === undefined ? {} : { latest: state.check.latest }),
         ...(state.check.latest === undefined || state.check.latestNotes === undefined ? {} : { latestNotes: state.check.latestNotes }),
         ...(state.check.lastAt === undefined ? {} : { checkedAt: state.check.lastAt }),
         checkEnabled: state.check.enabled,
-        updateAvailable: isNewer(state.check.latest, state.current),
+        updateAvailable: newer && processing === undefined,
         ...(state.check.error === undefined ? {} : { error: state.check.error }),
+        ...(processing === undefined ? {} : { processing: { version: processing, message: processingSentence(processing) } }),
         history: state.history,
     };
 }
+/** What the sheet and a failed install say while npm has not served a fresh version's tarball yet. */
+export function processingSentence(version) {
+    return `npm is still processing ${version}; try again in a few minutes.`;
+}
+/**
+ * Where npm serves a version's tarball by convention: `<registry>/@withbuddi/buddi/-/buddi-<version>.tgz`.
+ * Only the fallback: the version document's `dist.tarball` is what npm itself downloads.
+ */
+export function tarballUrl(registry, version) {
+    return `${registry.replace(/\/+$/, '')}/${PACKAGE_NAME}/-/${PACKAGE_NAME.split('/').pop()}-${version}.tgz`;
+}
+/**
+ * The credentials npm itself would send to this registry, read from the
+ * owner's npmrc (`NPM_CONFIG_USERCONFIG`, else `~/.npmrc`): `_authToken` as a
+ * bearer, `_auth` or `username` + `_password` as basic. The longest
+ * `//host/path/:` key the registry URL starts with wins, as in npm, and
+ * `${VAR}` is read from the environment. Nothing found is no headers: the
+ * public registry needs none.
+ *
+ * Read so the check and the install see the same registry: a mirror that wants
+ * a token answered the anonymous check 401, which once read as "still
+ * processing" for ever.
+ */
+export function registryAuth(registry, env, read = file => readFileSync(file, 'utf8')) {
+    const file = env.NPM_CONFIG_USERCONFIG ?? env.npm_config_userconfig ?? (env.HOME ? path.join(env.HOME, '.npmrc') : undefined);
+    if (file === undefined)
+        return {};
+    let text;
+    try {
+        text = read(file);
+    }
+    catch {
+        return {};
+    }
+    let url;
+    try {
+        url = new URL(registry.replace(/\/+$/, '') + '/');
+    }
+    catch {
+        return {};
+    }
+    const nerf = `//${url.host}${url.pathname}`;
+    const entries = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith(';'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const value = trimmed.slice(eq + 1).trim().replace(/^"(.*)"$/, '$1').replace(/\$\{([^}]+)\}/g, (_, name) => env[name] ?? '');
+        entries.set(trimmed.slice(0, eq).trim(), value);
+    }
+    const scopes = [...new Set([...entries.keys()].filter(k => k.startsWith('//') && k.includes('/:')).map(k => k.slice(0, k.lastIndexOf('/:') + 1)))]
+        .filter(scope => nerf.startsWith(scope))
+        .sort((a, b) => b.length - a.length);
+    for (const scope of scopes) {
+        const token = entries.get(`${scope}:_authToken`);
+        if (token)
+            return { authorization: `Bearer ${token}` };
+        const auth = entries.get(`${scope}:_auth`);
+        if (auth)
+            return { authorization: `Basic ${auth}` };
+        const user = entries.get(`${scope}:username`), password = entries.get(`${scope}:_password`);
+        if (user && password)
+            return { authorization: `Basic ${Buffer.from(`${user}:${Buffer.from(password, 'base64').toString('utf8')}`).toString('base64')}` };
+    }
+    return {};
+}
+/** Credentials go to the registry's own origin only, never to a host a document names. */
+export function authFor(url, registry, auth) {
+    if (auth === undefined || Object.keys(auth).length === 0)
+        return {};
+    try {
+        return new URL(url).origin === new URL(registry).origin ? auth : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Does npm serve this version's tarball yet?
+ *
+ * The tarball is the one the version document names (`dist.tarball`), asked
+ * with the registry's credentials. Only a 404 (of the document or the
+ * tarball) is "still processing": that is what npmjs answers in the minutes
+ * after a publish. A registry that refuses HEAD (405, 501) is asked for one
+ * byte instead. Anything else — a 401 or 403 from a mirror, a 5xx — is not a
+ * publish in progress and is not reported as one: the install that follows
+ * says what is actually wrong. A transport failure throws.
+ */
+export async function tarballServed(registry, version, http, opts = {}) {
+    const base = registry.replace(/\/+$/, '');
+    let url = opts.tarball;
+    if (url === undefined || url === '') {
+        const doc = await http(`${base}/${PACKAGE_PATH}/${version}`, {
+            method: 'GET',
+            headers: { accept: 'application/json', ...authFor(base, base, opts.auth) },
+            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        });
+        if (doc.status === 404)
+            return false;
+        if (doc.status === 200) {
+            const body = await doc.json().catch(() => undefined);
+            if (typeof body?.dist?.tarball === 'string' && body.dist.tarball !== '')
+                url = body.dist.tarball;
+        }
+    }
+    if (url === undefined || url === '')
+        url = tarballUrl(base, version);
+    const headers = authFor(url, base, opts.auth);
+    const head = await http(url, { method: 'HEAD', headers, signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
+    if (head.status >= 200 && head.status < 300)
+        return true;
+    if (head.status === 404)
+        return false;
+    if (head.status === 405 || head.status === 501) {
+        try {
+            const ranged = await http(url, { method: 'GET', headers: { ...headers, range: 'bytes=0-0' }, signal: AbortSignal.timeout(CHECK_TIMEOUT_MS), maxBytes: 64 * 1024 });
+            return ranged.status !== 404;
+        }
+        catch {
+            // A server that ignored the range and started sending the whole tarball is serving it.
+            return true;
+        }
+    }
+    return true;
+}
+/**
+ * npm's own words for *this package's* tarball not being served (yet): `E404`
+ * and a 404 line naming `@withbuddi/buddi`. A 404 for anything else — a
+ * dependency, a mirror's missing path — is not a publish in progress, and
+ * keeps npm's own words.
+ */
+export function isNotFound(error) {
+    // The "npm install <spec> failed:" this module puts in front names the package itself.
+    const said = error.replace(/npm (install|cache add) \S+ failed:/g, '');
+    if (!/\bE404\b/.test(said))
+        return false;
+    return said.split('\n').some(line => /\b404\b/.test(line) && /@withbuddi(\/|%2f)buddi\b/i.test(line));
+}
+/**
+ * What npm said, safe to keep in the history and show on the dashboard:
+ * credentials in URLs and npmrc-style tokens masked, terminal escapes and
+ * other control characters dropped, the last eight lines.
+ */
+export function sanitizeNpmOutput(text) {
+    return text
+        // eslint-disable-next-line no-control-regex
+        .replace(/\u001b\[[0-9;]*[A-Za-z]/g, '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '')
+        .replace(/(\w+:\/\/)[^\s/@:]+(:[^\s/@]*)?@/g, '$1***@')
+        .replace(/(_authToken|_auth|_password)(\s*[=:]\s*)\S+/gi, '$1$2***')
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/g, '$1 ***')
+        .trim().split('\n').slice(-8).join('\n');
+}
 /** Release notes longer than this are cut; `build.mjs` keeps them to 8 KB. */
 export const NOTES_LIMIT = 8 * 1024;
 /**
@@ -210,10 +372,11 @@ export const NOTES_LIMIT = 8 * 1024;
  * same document carries the release notes (`buddi.notes`, written by
  * `scripts/release/build.mjs`), so they cost no second request.
  */
-export async function fetchLatestRelease(registry, http) {
-    const response = await http(`${registry.replace(/\/+$/, '')}/${PACKAGE_PATH}/latest`, {
+export async function fetchLatestRelease(registry, http, auth) {
+    const base = registry.replace(/\/+$/, '');
+    const response = await http(`${base}/${PACKAGE_PATH}/latest`, {
         method: 'GET',
-        headers: { accept: 'application/json' },
+        headers: { accept: 'application/json', ...authFor(base, base, auth) },
         signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
     });
     if (response.status !== 200)
@@ -225,10 +388,11 @@ export async function fetchLatestRelease(registry, http) {
     // and a number on the dashboard. It gets to name a version, and nothing else.
     if (!isVersion(body.version))
         throw new Error(`the registry named "${body.version}", which is not a version`);
+    const tarball = typeof body.dist?.tarball === 'string' && body.dist.tarball !== '' ? { tarball: body.dist.tarball } : {};
     const notes = typeof body.buddi === 'object' && body.buddi !== null ? body.buddi.notes : undefined;
     if (typeof notes !== 'string' || notes.trim() === '')
-        return { version: body.version };
-    return { version: body.version, notes: notes.trim().slice(0, NOTES_LIMIT) };
+        return { version: body.version, ...tarball };
+    return { version: body.version, notes: notes.trim().slice(0, NOTES_LIMIT), ...tarball };
 }
 /**
  * Read the layout back off the install root rather than trusting npm's config.
@@ -278,6 +442,10 @@ export const NOT_GLOBAL = 'This buddi was installed inside another project; upgr
  */
 export function upgradeTarget(root, opts = {}) {
     const platform = opts.platform ?? process.platform;
+    // The bundle is signed: npm must never write there. buddi.app upgrades it
+    // through its own layout (`app-layout.ts`) when it is the one running buddi.
+    if (insideAppBundle(root))
+        return { error: APP_BUNDLE };
     const target = installTarget(root, platform);
     if (target.global)
         return target;
@@ -354,7 +522,7 @@ export function createInstaller(opts = {}) {
     const failed = (verb, spec, err) => {
         const stderr = err?.stderr;
         const text = (stderr ?? (err instanceof Error ? err.message : String(err))).toString().trim();
-        return new Error(`npm ${verb} ${spec} failed: ${text.split('\n').slice(-8).join('\n')}`);
+        return new Error(`npm ${verb} ${spec} failed: ${sanitizeNpmOutput(text)}`);
     };
     return async (spec, where) => {
         if (!isLocalTarball(spec)) {
@@ -402,6 +570,11 @@ export function createInstaller(opts = {}) {
  * into nothing, leaving the installation down until the next login.
  */
 export function restartPlan(facts) {
+    // buddi.app is this supervisor's parent: it starts the launcher `current`
+    // points at again as soon as this exits with APP_RESTART_EXIT (app-layout.ts).
+    if (facts.appLayout === true) {
+        return { mode: 'app', reason: 'buddi.app starts the release `current` points at again' };
+    }
     if (facts.platform === 'darwin' && facts.label !== '' && facts.xpcServiceName === facts.label) {
         return { mode: 'launchd', reason: 'launchd keeps this job alive and runs the launcher from the install root' };
     }
@@ -424,9 +597,9 @@ export function restartPlan(facts) {
  * owner actually asked for.
  */
 export async function handOver(opts) {
-    const plan = opts.plan ?? restartPlan({ platform: process.platform, label: launchAgentLabel(opts.ctx.data), serviceUnit: process.env[SERVICE_UNIT_VAR] ?? opts.env[SERVICE_UNIT_VAR], xpcServiceName: process.env.XPC_SERVICE_NAME ?? opts.env.XPC_SERVICE_NAME });
+    const plan = opts.plan ?? restartPlan({ platform: process.platform, label: launchAgentLabel(opts.ctx.data), serviceUnit: process.env[SERVICE_UNIT_VAR] ?? opts.env[SERVICE_UNIT_VAR], xpcServiceName: process.env.XPC_SERVICE_NAME ?? opts.env.XPC_SERVICE_NAME, appLayout: appLayout(opts.env) !== undefined });
     const log = opts.log ?? ((line) => console.error(line));
-    if (plan.mode === 'launchd' || plan.mode === 'systemd') {
+    if (plan.mode === 'launchd' || plan.mode === 'systemd' || plan.mode === 'app') {
         log(`supervisor: exiting for the upgrade; ${plan.reason}.`);
         return { plan, ok: true, attempts: 0 };
     }
@@ -505,11 +678,15 @@ export async function statusOnSocket(socket, timeoutMs = 2_000) {
  * dashboard is not available in that state — the gateway is deliberately not
  * started — so this has to be complete on its own.
  */
-export function recoverySentence(entry) {
+export function recoverySentence(entry, opts = {}) {
     const where = entry.step === 'starting' ? 'while starting' : 'while migrating';
-    return `Upgrade to ${entry.to} failed ${where}: ${entry.error ?? 'unknown error'}. ` +
-        `The backup taken first is ${entry.backup ?? 'not available'}. ` +
-        `Reinstall with \`npm install -g ${PACKAGE_NAME}@${entry.from}\` and run \`buddi backup restore ${entry.backup ?? '<backup>'}\`.`;
+    const head = `Upgrade to ${entry.to} failed ${where}: ${entry.error ?? 'unknown error'}. ` +
+        `The backup taken first is ${entry.backup ?? 'not available'}. `;
+    if (opts.app === true) {
+        // buddi.app keeps the release that ran before; its menu goes back to it.
+        return head + `In the buddi menu, choose Advanced → Restart with the Previous Version (${entry.from}), then restore ${entry.backup ?? 'that backup'} in Settings → Backups.`;
+    }
+    return head + `Reinstall with \`npm install -g ${PACKAGE_NAME}@${entry.from}\` and run \`buddi backup restore ${entry.backup ?? '<backup>'}\`.`;
 }
 function message(err) {
     return err instanceof Error ? err.message : String(err);
@@ -519,10 +696,16 @@ export function createUpgradeService(opts) {
     const log = opts.log ?? ((line) => console.error(line));
     const jobs = new JobStore();
     const registry = registryFor(ctx.env);
+    /** What npm would send this registry; the check asks with the same. */
+    const auth = registryAuth(registry, ctx.env);
     const checkInterval = opts.checkIntervalMs ?? (Number(ctx.env.BUDDI_UPGRADE_CHECK_INTERVAL_MS) || CHECK_INTERVAL_MS);
     const install = opts.install ?? createInstaller();
     const checkPostgres = opts.checkPostgres ?? createPostgresCheck({ env: ctx.env });
     const backupWait = opts.backupWaitMs ?? BACKUP_WAIT_MS;
+    /** buddi.app's releases folder, when the app runs this installation. */
+    const releases = appLayout(ctx.env);
+    const npm = opts.npm ?? (async (bin, argv, where) => await run(bin, argv, where));
+    const dressed = (view) => releases === undefined ? view : { ...view, app: true };
     let running;
     /** Has the code under this process already been replaced? See `perform`. */
     let replaced = false;
@@ -539,13 +722,17 @@ export function createUpgradeService(opts) {
             return await save({ ...state, check: { ...state.check, lastAt: at, error: 'this installation has no outbound transport' } });
         }
         try {
-            const latest = await fetchLatestRelease(registry, opts.http);
+            const latest = await fetchLatestRelease(registry, opts.http, auth);
+            // npm names a fresh version minutes before it serves the tarball; until
+            // it does, the version is known but not offered (Upgrade would 404).
+            const served = !isNewer(latest.version, current) || await tarballServed(registry, latest.version, opts.http, { tarball: latest.tarball, auth });
             // A check that answered clears the error a check that did not left, and
             // the notes are always the ones this answer carried: notes kept from an
             // older `latest` would describe the wrong release.
             return await save({ ...state, check: {
                     enabled: state.check.enabled, lastAt: at, latest: latest.version,
                     ...(latest.notes === undefined ? {} : { latestNotes: latest.notes }),
+                    ...(served ? {} : { processing: latest.version }),
                 } });
         }
         catch (err) {
@@ -586,10 +773,12 @@ export function createUpgradeService(opts) {
         if (asked !== undefined) {
             return isVersion(asked) ? { version: asked } : { error: `"${asked}" is not a version this can install.` };
         }
-        const known = (await read()).check.latest;
-        if (isNewer(known, current))
-            return { version: known };
+        const kept = (await read()).check;
+        if (isNewer(kept.latest, current) && kept.processing === undefined)
+            return { version: kept.latest };
         const state = await runCheck();
+        if (state.check.processing !== undefined)
+            return { error: processingSentence(state.check.processing) };
         if (isVersion(state.check.latest))
             return { version: state.check.latest };
         return { error: state.check.error ?? 'the registry did not name a version to upgrade to' };
@@ -615,6 +804,8 @@ export function createUpgradeService(opts) {
             else
                 log(`upgrade: ${step} failed: ${error}`);
         };
+        if (releases !== undefined)
+            return await performInApp(job, version, releases, give, startedAt, (next) => { to = next; }, (taken) => { archive = taken; });
         // Where npm may write, decided before anything is stopped or archived.
         const target = upgradeTarget(ctx.root);
         if ('error' in target)
@@ -626,27 +817,18 @@ export function createUpgradeService(opts) {
                 return await give('checking', resolved.error, false);
             to = resolved.version;
             spec = `${PACKAGE_NAME}@${resolved.version}`;
+            // Asked before the backup and the stop: a version npm is still
+            // processing would only reach npm's 404 after both.
+            if (opts.http !== undefined) {
+                const served = await tarballServed(registry, to, opts.http, { auth }).catch(() => undefined);
+                if (served === false)
+                    return await give('checking', processingSentence(to), false);
+            }
         }
-        /*
-         * The backup is encrypted exactly as the schedule says, because that
-         * setting is the owner's answer to "may an archive of everything sit on
-         * this disk in the clear", and an upgrade is not an exception to it.
-         */
-        const schedule = await backup.schedule().catch(() => undefined);
-        const encrypt = schedule?.encryptLocal !== false;
-        if (encrypt && !backup.hasVault()) {
-            return await give('backup', 'This installation has no vault, so the backup an upgrade takes first cannot be encrypted. Turn off "Encrypt local backups" in Settings, or set up a vault.', false);
-        }
-        jobs.phase(job, 'backup', 'taking a backup before anything changes');
-        const started = backup.create(encrypt);
-        if ('status' in started)
-            return await give('backup', started.error, false);
-        const done = await settled(started, backupWait);
-        if (done === undefined)
-            return await give('backup', 'the backup did not finish within twenty minutes', false);
-        if (done.phase !== 'done')
-            return await give('backup', done.error ?? 'the backup did not finish', false);
-        archive = done.report?.archive;
+        const taken = await takeBackup(job);
+        if ('error' in taken)
+            return await give('backup', taken.error, false);
+        archive = taken.archive;
         jobs.phase(job, 'stopping', 'stopping the gateway; the database stays up');
         await opts.stopGateway();
         jobs.phase(job, 'installing', `installing ${spec}`);
@@ -654,7 +836,9 @@ export function createUpgradeService(opts) {
             await install(spec, { registry, root: ctx.root, target });
         }
         catch (err) {
-            return await give('installing', message(err), true);
+            // npm's 404 wall for a version it has not served yet is one sentence here.
+            const said = message(err);
+            return await give('installing', tarball === undefined && isNotFound(said) ? processingSentence(to) : said, true);
         }
         /*
          * What is on disk now, rather than what was asked for. npm can be pointed
@@ -698,6 +882,104 @@ export function createUpgradeService(opts) {
                 return await give('verifying', `${refused} It is still running on ${current}.`, true);
             }
         }
+        await handOverTo(job, to, startedAt, archive);
+    };
+    /**
+     * The backup every upgrade takes first. Encrypted exactly as the schedule
+     * says, because that setting is the owner's answer to "may an archive of
+     * everything sit on this disk in the clear", and an upgrade is not an
+     * exception to it.
+     */
+    const takeBackup = async (job) => {
+        const schedule = await backup.schedule().catch(() => undefined);
+        const encrypt = schedule?.encryptLocal !== false;
+        if (encrypt && !backup.hasVault()) {
+            return { error: 'This installation has no vault, so the backup an upgrade takes first cannot be encrypted. Turn off "Encrypt local backups" in Settings, or set up a vault.' };
+        }
+        jobs.phase(job, 'backup', 'taking a backup before anything changes');
+        const started = backup.create(encrypt);
+        if ('status' in started)
+            return { error: started.error };
+        const done = await settled(started, backupWait);
+        if (done === undefined)
+            return { error: 'the backup did not finish within twenty minutes' };
+        if (done.phase !== 'done')
+            return { error: done.error ?? 'the backup did not finish' };
+        return { archive: done.report?.archive };
+    };
+    /**
+     * buddi.app's upgrade: the new release goes into `<releases>/buddi-<v>`,
+     * verified and checked while the gateway still runs, and only then is there
+     * a backup, a stop and the switch of `current`. See `app-layout.ts`.
+     */
+    const performInApp = async (job, version, dir, give, startedAt, setTo, setArchive) => {
+        if (ctx.env.BUDDI_UPGRADE_SOURCE?.trim())
+            return await give('checking', 'buddi.app upgrades from the registry only; BUDDI_UPGRADE_SOURCE is for npm installations.', false);
+        const resolved = await resolveVersion(version);
+        if ('error' in resolved)
+            return await give('checking', resolved.error, false);
+        const to = resolved.version;
+        setTo(to);
+        if (opts.http === undefined)
+            return await give('checking', 'this installation has no outbound transport', false);
+        const served = await tarballServed(registry, to, opts.http, { auth }).catch(() => undefined);
+        if (served === false)
+            return await give('checking', processingSentence(to), false);
+        const base = await realpath(dir).catch(() => dir);
+        if ((path.resolve(ctx.root) + path.sep).startsWith(releaseDir(base, to) + path.sep)) {
+            return await give('checking', `${to} is the version running.`, false);
+        }
+        /*
+         * Everything is checked in a staging folder of its own, and only a release
+         * that passed every check is renamed into `buddi-<v>`: a failed retry never
+         * touches a `buddi-<v>` that `previous` (after a rollback) still points at.
+         */
+        jobs.phase(job, 'installing', `downloading and verifying ${to}`);
+        let staged;
+        try {
+            staged = await stageRelease({ releases: dir, version: to, registry, http: opts.http, exec: npm, log, auth, ...(opts.provenanceChain === undefined ? {} : { chain: opts.provenanceChain }) });
+        }
+        catch (err) {
+            const said = message(err);
+            return await give('installing', isNotFound(said) ? processingSentence(to) : said, false);
+        }
+        const dropStaging = async () => { await rm(staged.staging, { recursive: true, force: true }).catch(() => { }); };
+        if (ctx.state.database !== 'external') {
+            jobs.phase(job, 'verifying', `checking that ${to} can start its database`);
+            const verdict = await checkPostgres(staged.root);
+            if (!verdict.ok) {
+                await dropStaging();
+                return await give('verifying', `${verdict.error} buddi did not switch to ${to}. It is still running on ${current}.`, false);
+            }
+        }
+        let placed;
+        try {
+            placed = await placeRelease(dir, to, staged.staging, log);
+        }
+        catch (err) {
+            await dropStaging();
+            return await give('installing', `could not put ${to} in place: ${message(err)}`, false);
+        }
+        // Only what neither link uses goes: a kept `buddi-<v>` that `previous` names stays.
+        const discard = async () => { await pruneReleases(dir).catch(() => []); };
+        const taken = await takeBackup(job);
+        if ('error' in taken) {
+            await discard();
+            return await give('backup', taken.error, false);
+        }
+        setArchive(taken.archive);
+        jobs.phase(job, 'stopping', 'stopping the gateway; the database stays up');
+        await opts.stopGateway();
+        try {
+            await switchCurrent(dir, placed.root, ctx.root);
+        }
+        catch (err) {
+            return await give('installing', `could not switch to ${to}: ${message(err)}`, true);
+        }
+        await handOverTo(job, to, startedAt, taken.archive);
+    };
+    /** The point of no return, shared by both layouts. */
+    const handOverTo = async (job, to, startedAt, archive) => {
         replaced = true;
         jobs.phase(job, 'restarting', `handing over to ${to}`);
         /*
@@ -733,14 +1015,14 @@ export function createUpgradeService(opts) {
     return {
         current,
         async view() {
-            return versionView(await read());
+            return dressed(versionView(await read()));
         },
         async check() {
-            return versionView(await runCheck());
+            return dressed(versionView(await runCheck()));
         },
         async setCheckEnabled(enabled) {
             const state = await read();
-            return versionView(await save({ ...state, check: { ...state.check, enabled } }));
+            return dressed(versionView(await save({ ...state, check: { ...state.check, enabled } })));
         },
         start(version) {
             if (version !== undefined && !isVersion(version)) {
@@ -852,7 +1134,7 @@ export function upgradeDoctorLines(view, phase) {
     if (last !== undefined) {
         lines.push(`Last upgrade: ${last.from} to ${last.to}, ${last.outcome}${last.step === undefined ? '' : ` at ${last.step}`}`);
         if (phase === 'upgrade-failed' && last.outcome === 'failed')
-            lines.push(recoverySentence(last));
+            lines.push(recoverySentence(last, { app: view.app === true }));
     }
     return lines;
 }