sideby 0.15.0 → 0.16.0

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261017T115526-c6b039"}
+{"id":"20261017T131419-98017e"}

package/dist/src/cli/commands.d.ts

@@ -71,6 +71,11 @@ export declare function cmdUi(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdUpdate(a: ParsedArgs, io: Io): Promise<number>;
 /** The internal `sideby update-check` the CLI starts detached: one Update Check, then Auto Update if it is on. */
 export declare function cmdUpdateCheck(_a: ParsedArgs, _io: Io): Promise<number>;
+/**
+ * `sideby local [on|off]` (ADR-0024): which side the global `sideby` runs, and a switch between the newest Local
+ * Build (`pnpm local` builds it) and the npm package. Shows the change first and exits 10 without `--yes`.
+ */
+export declare function cmdLocal(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdApp(a: ParsedArgs, io: Io): Promise<number>;
 /**
  * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:

package/dist/src/cli/commands.js

@@ -1346,6 +1346,89 @@ export async function cmdUpdateCheck(_a, _io) {
     await backgroundCheck(paths, process.env, config, () => backgroundPanelPort(paths));
     return 0;
 }
+/**
+ * `sideby local [on|off]` (ADR-0024): which side the global `sideby` runs, and a switch between the newest Local
+ * Build (`pnpm local` builds it) and the npm package. Shows the change first and exits 10 without `--yes`.
+ */
+export async function cmdLocal(a, io) {
+    const usage = 'usage: sideby local [on|off] [--yes] [--json]';
+    const sub = a.positionals[0];
+    if (a.positionals.length > 1 || (sub !== undefined && sub !== 'on' && sub !== 'off'))
+        throw new UsageError(usage);
+    const lb = await import('../core/local-build.js');
+    const asJson = a.flags.has('json');
+    const d = await lb.localDirs(process.env);
+    if (!d)
+        throw new UserError('`npm prefix -g` failed; switching needs npm on PATH and an npm global install of sideby');
+    const s = await lb.localStatus(d);
+    const now = new Date();
+    const build = (l) => `${l.version}-dev · ${l.commit || 'no commit'}${l.dirty ? '+' : ''}${l.builtAt ? `, built ${clock(l.builtAt, now)}` : ''}`;
+    if (sub === undefined) {
+        if (asJson)
+            json(io, { ...s, switched: false });
+        else {
+            io.out(s.running === 'local' && s.local
+                ? `The global sideby runs the local build ${build(s.local)}.`
+                : s.running === 'npm'
+                    ? 'The global sideby runs the npm package.'
+                    : 'The global sideby is not an npm global install; switching supports `npm install -g sideby` only.');
+            if (s.running === 'local')
+                io.out(c.dim('Back to the release: sideby local off'));
+            else if (s.running === 'npm' && s.local)
+                io.out(c.dim(`A local build is kept (${build(s.local)}): sideby local on`));
+        }
+        return 0;
+    }
+    const to = sub === 'on' ? 'local' : 'npm';
+    const blocked = lb.switchBlocker(s, to);
+    if (blocked) {
+        if (asJson)
+            json(io, { ...s, to, switched: false, blocked });
+        else
+            io.err(c.yellow(`sideby cannot switch: ${blocked}`));
+        return 1;
+    }
+    if (s.running === to) {
+        if (asJson)
+            json(io, { ...s, to, switched: false });
+        else
+            io.out(`${c.green('✓')} The global sideby already runs the ${to === 'local' ? 'local build' : 'npm package'}.`);
+        return 0;
+    }
+    if (!a.flags.has('yes')) {
+        if (asJson)
+            json(io, { ...s, to, switched: false });
+        else {
+            io.out(to === 'local' && s.local
+                ? `Switching runs the local build ${build(s.local)} instead of the npm package. It is not rebuilt: \`pnpm local\` in the checkout builds a new one.`
+                : `Switching goes back to the npm package: the kept ${s.kept ?? 'copy'} when it is the latest, else \`npm install -g sideby@latest\`.`);
+            io.out(c.cyan(`\nRun it with \`sideby local ${sub} --yes\`.`));
+        }
+        return 10;
+    }
+    const { backgroundPanelPort } = await import('../panel/background.js');
+    const paths = resolvePaths(process.env);
+    const r = await lb.switchLocal(paths, d, to, process.env, {
+        panelPort: () => backgroundPanelPort(paths),
+        ...(asJson ? {} : { onOutput: (t) => process.stderr.write(t) }),
+    });
+    if (asJson)
+        json(io, {
+            ...(await lb.localStatus(d)),
+            to,
+            switched: r.ok,
+            message: r.message,
+            restartedPanel: r.restartedPanel,
+        });
+    else if (r.ok) {
+        io.out(`${c.green('✓')} ${r.message}.`);
+        if (r.restartedPanel)
+            io.out(c.dim('The background panel restarted with it; open panels reload by themselves.'));
+    }
+    else
+        io.err(c.red(`✗ ${r.message}`));
+    return r.ok ? 0 : 1;
+}
 export async function cmdApp(a, io) {
     const sub = a.positionals[0];
     const usage = 'usage: sideby app install [--url <url>] | sideby app uninstall';

package/dist/src/cli/json-schemas.js

@@ -333,6 +333,25 @@ export const OUTPUT_SCHEMAS = {
         changed: Type.Boolean(),
     }),
     'update-auto': Type.Object({ schemaVersion: Version, auto: Type.Boolean(), changed: Type.Boolean() }),
+    local: Type.Object({
+        schemaVersion: Version,
+        running: Type.Union([Type.Literal('local'), Type.Literal('npm'), Type.Null()], {
+            description: 'What the global sideby runs: the Local Build, an npm package, or neither (not an npm global install).',
+        }),
+        local: Type.Union([Type.Object({ commit: Str, dirty: Type.Boolean(), builtAt: Str, version: Str }), Type.Null()], {
+            description: 'The newest Local Build, the one `on` switches to; null when `pnpm local` never ran.',
+        }),
+        kept: Type.Union([Str, Type.Null()], {
+            description: 'The npm package version kept aside while a Local Build runs.',
+        }),
+        to: Type.Optional(Type.Union([Type.Literal('local'), Type.Literal('npm')])),
+        switched: Type.Boolean({
+            description: 'A switch ran and succeeded; false for status, a preview (exit 10) or a failure.',
+        }),
+        blocked: Type.Optional(Type.String({ description: 'Why the switch cannot run, with what to do.' })),
+        message: Type.Optional(Str),
+        restartedPanel: Type.Optional(Type.Boolean()),
+    }, { title: 'sideby local --json' }),
     list: Type.Object({
         schemaVersion: Version,
         families: Type.Array(FamilyInfo),

package/dist/src/cli/main.js

@@ -72,10 +72,12 @@ Usage:
                                       rewrite the config's shellInitFile with them
   sideby plugins                      list loaded plugins and load errors
   sideby update [--yes]               update sideby to the newest version (shows the command first)
+  sideby local [on|off] [--yes]       for sideby developers: switch the global sideby between the
+                                      last local build (pnpm local) and the npm package
 
 Options:
   --json        machine-readable output (list, new, next, alias, doctor, quota, tune, model, remote-control, handoff,
-                families, plugins, app, desktop, browser, update)
+                families, plugins, app, desktop, browser, update, local)
   -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop, browser
   -v, --version show the version
 
@@ -249,6 +251,7 @@ const COMMANDS = {
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
     update: { flags: ['json', 'yes'], valued: ['auto'] },
+    local: { flags: ['json', 'yes'] },
     'update-check': { flags: [] },
 };
 /** Commands that never print an Update Notice: their output is read by a shell or an agent, or they are internal. */
@@ -477,6 +480,8 @@ async function dispatch(cmd, parsed, io, cmds) {
             return await cmds.cmdUpdate(parsed, io);
         case 'update-check':
             return await cmds.cmdUpdateCheck(parsed, io);
+        case 'local':
+            return await cmds.cmdLocal(parsed, io);
     }
     return 2;
 }

package/dist/src/core/local-build.d.ts

@@ -0,0 +1,63 @@
+import type { Env } from '../types.ts';
+import type { Paths } from './paths.ts';
+import { type LocalBuild } from './version.ts';
+export interface LocalDirs {
+    /** `$XDG_DATA_HOME/sideby-dev`: `pkg` (the running build), `old/<id>`, `npm` (the package it replaced). */
+    dev: string;
+    /** npm's global prefix: `<prefix>/lib/node_modules/sideby` and `<prefix>/bin/sideby`. */
+    prefix: string;
+}
+export declare const pkgDir: (d: LocalDirs) => string;
+export declare const globalPkg: (d: LocalDirs) => string;
+export declare const devDir: (env: Env) => string;
+/** Where the switch works, with npm's global prefix from `npm prefix -g`; null when npm cannot be asked. */
+export declare function localDirs(env: Env): Promise<LocalDirs | null>;
+export declare function kind(p: string): Promise<'link' | 'dir' | 'file' | null>;
+/**
+ * Points the global npm package at `pkg`. A real npm install moves to `<dev>/npm` first, so going back needs no
+ * network; a link elsewhere (npm link) is replaced. Returns what it did, for the summary.
+ */
+export declare function linkGlobal(d: LocalDirs): Promise<string>;
+/** Undoes linkGlobal: the npm package it moved comes back; false when there is none to restore (install it). */
+export declare function unlinkGlobal(d: LocalDirs): Promise<boolean>;
+/** The version of the npm package kept aside by linkGlobal, or null when none was kept or it cannot be read. */
+export declare const keptVersion: (d: LocalDirs) => Promise<string | null>;
+/**
+ * Going back to npm: put the kept package back when it is the newest published one (or the registry cannot be
+ * asked), else install `latest`. After a release the kept copy is the version before it.
+ */
+export declare function offPlan(kept: string | null, latest: string | null): 'restore' | 'install';
+export interface LocalStatus {
+    /** What the global `sideby` runs: the Local Build in `pkg`, an npm package, or neither (not installed, a link elsewhere). */
+    running: 'local' | 'npm' | null;
+    /** The newest Local Build, the one `on` switches to; null when `pnpm local` never ran here. */
+    local: (LocalBuild & {
+        version: string;
+    }) | null;
+    /** The npm package kept aside while a Local Build runs; null when none is. */
+    kept: string | null;
+}
+export declare function localStatus(d: LocalDirs): Promise<LocalStatus>;
+export type LocalTarget = 'local' | 'npm';
+/** Why `to` cannot run from this status, or null when it can. Every reason says what to do. */
+export declare function switchBlocker(s: LocalStatus, to: LocalTarget): string | null;
+export interface SwitchResult {
+    ok: boolean;
+    message: string;
+    /** What the global `sideby` runs afterwards. */
+    running: LocalStatus['running'];
+    /** True when it already ran `to`, and nothing changed. */
+    unchanged?: boolean;
+    restartedPanel: boolean;
+    /** Another install held the lock; nothing ran. */
+    busy?: boolean;
+}
+/**
+ * Puts `to` behind the global `sideby`. `local` links the newest Local Build; `npm` restores the kept package or
+ * installs `latest` (a failed install links the Local Build back, so `sideby` never goes missing). Afterwards a
+ * background Panel on `panelPort` starts again from the new code. One install at a time (the Update lock).
+ */
+export declare function switchLocal(paths: Paths, d: LocalDirs, to: LocalTarget, env: Env, opts?: {
+    panelPort?: () => Promise<number | null>;
+    onOutput?: (text: string) => void;
+}): Promise<SwitchResult>;

package/dist/src/core/local-build.js

@@ -0,0 +1,189 @@
+// Switching the global `sideby` between a Local Build and the npm package (ADR-0024). `pnpm local` builds and calls
+// these; `sideby local` and the Panel's version popover switch between the newest Local Build and npm without the
+// checkout. Only an npm global install is handled: `<prefix>/lib/node_modules/sideby` is the folder every caller
+// resolves, a link to `<dev>/pkg` while a Local Build runs.
+import { lstat, mkdir, readFile, readlink, rename, rm, symlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { compareVersions, fetchLatest, restartPanelByName, runProgram, takeInstallLock } from './update.js';
+import { parseLocalBuild } from './version.js';
+const BIN = 'dist/src/cli/main.js';
+export const pkgDir = (d) => join(d.dev, 'pkg');
+export const globalPkg = (d) => join(d.prefix, 'lib', 'node_modules', 'sideby');
+const globalBin = (d) => join(d.prefix, 'bin', 'sideby');
+export const devDir = (env) => join(env.XDG_DATA_HOME || join(env.HOME || homedir(), '.local', 'share'), 'sideby-dev');
+/** Where the switch works, with npm's global prefix from `npm prefix -g`; null when npm cannot be asked. */
+export async function localDirs(env) {
+    const r = await runProgram('npm', ['prefix', '-g'], { env }).catch(() => null);
+    const prefix = r && r.code === 0 ? r.output.trim().split('\n').at(-1)?.trim() : '';
+    return prefix ? { dev: devDir(env), prefix } : null;
+}
+export async function kind(p) {
+    try {
+        const s = await lstat(p);
+        return s.isSymbolicLink() ? 'link' : s.isDirectory() ? 'dir' : 'file';
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Points the global npm package at `pkg`. A real npm install moves to `<dev>/npm` first, so going back needs no
+ * network; a link elsewhere (npm link) is replaced. Returns what it did, for the summary.
+ */
+export async function linkGlobal(d) {
+    const target = globalPkg(d);
+    const pkg = pkgDir(d);
+    let did = 'the global sideby already runs the local build';
+    const k = await kind(target);
+    if (k !== 'link' || (await readlink(target)) !== pkg) {
+        if (k === 'dir') {
+            await rm(join(d.dev, 'npm'), { recursive: true, force: true });
+            await rename(target, join(d.dev, 'npm'));
+            did = `the npm package moved to ${join(d.dev, 'npm')}; the global sideby now runs the local build`;
+        }
+        else {
+            if (k)
+                await rm(target, { force: true });
+            did = 'the global sideby now runs the local build';
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await symlink(pkg, target, 'dir');
+    }
+    const bin = globalBin(d);
+    const want = relative(dirname(bin), join(target, BIN));
+    if ((await kind(bin)) !== 'link' || (await readlink(bin)) !== want) {
+        await rm(bin, { force: true });
+        await mkdir(dirname(bin), { recursive: true });
+        await symlink(want, bin);
+    }
+    return did;
+}
+/** Undoes linkGlobal: the npm package it moved comes back; false when there is none to restore (install it). */
+export async function unlinkGlobal(d) {
+    const target = globalPkg(d);
+    if ((await kind(target)) === 'link')
+        await rm(target, { force: true });
+    else if (await kind(target))
+        return true; // a real package is already there
+    if (!(await kind(join(d.dev, 'npm'))))
+        return false;
+    await rename(join(d.dev, 'npm'), target);
+    return true;
+}
+async function versionOf(dir) {
+    try {
+        const v = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')).version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The version of the npm package kept aside by linkGlobal, or null when none was kept or it cannot be read. */
+export const keptVersion = (d) => versionOf(join(d.dev, 'npm'));
+/**
+ * Going back to npm: put the kept package back when it is the newest published one (or the registry cannot be
+ * asked), else install `latest`. After a release the kept copy is the version before it.
+ */
+export function offPlan(kept, latest) {
+    if (!kept)
+        return 'install';
+    if (!latest)
+        return 'restore';
+    return (compareVersions(kept, latest) ?? -1) >= 0 ? 'restore' : 'install';
+}
+export async function localStatus(d) {
+    const k = await kind(globalPkg(d));
+    const running = k === 'link'
+        ? (await readlink(globalPkg(d))) === pkgDir(d)
+            ? 'local'
+            : null
+        : k === 'dir'
+            ? 'npm'
+            : null;
+    let local = null;
+    try {
+        const b = parseLocalBuild(JSON.parse(await readFile(join(pkgDir(d), 'dist', 'build.json'), 'utf8')));
+        const version = await versionOf(pkgDir(d));
+        if (b && version)
+            local = { ...b, version };
+    }
+    catch {
+        // no Local Build here
+    }
+    return { running, local, kept: await keptVersion(d) };
+}
+/** Why `to` cannot run from this status, or null when it can. Every reason says what to do. */
+export function switchBlocker(s, to) {
+    if (s.running === null)
+        return 'the global sideby is not an npm global install; switching supports `npm install -g sideby` only';
+    if (to === 'local' && !s.local)
+        return 'there is no local build yet; run `pnpm local` in the sideby checkout';
+    return null;
+}
+/**
+ * Puts `to` behind the global `sideby`. `local` links the newest Local Build; `npm` restores the kept package or
+ * installs `latest` (a failed install links the Local Build back, so `sideby` never goes missing). Afterwards a
+ * background Panel on `panelPort` starts again from the new code. One install at a time (the Update lock).
+ */
+export async function switchLocal(paths, d, to, env, opts = {}) {
+    const before = await localStatus(d);
+    const fail = (message, extra = {}) => ({
+        ok: false,
+        message,
+        running: before.running,
+        restartedPanel: false,
+        ...extra,
+    });
+    const blocked = switchBlocker(before, to);
+    if (blocked)
+        return fail(blocked);
+    if (before.running === to)
+        return {
+            ok: true,
+            unchanged: true,
+            message: to === 'local'
+                ? 'the global sideby already runs the local build'
+                : 'the global sideby already runs the npm package',
+            running: to,
+            restartedPanel: false,
+        };
+    const release = await takeInstallLock(paths);
+    if (!release)
+        return fail('a sideby update is running; wait for it to finish, then switch again', { busy: true });
+    let message;
+    try {
+        if (to === 'local') {
+            await linkGlobal(d);
+            message = `the global sideby runs the local build ${before.local?.commit ?? ''}`.trim();
+        }
+        else {
+            const latest = await fetchLatest(env).catch(() => null);
+            if (offPlan(before.kept, latest) === 'restore') {
+                await unlinkGlobal(d);
+                message = `the global sideby runs the npm package ${before.kept} again`;
+            }
+            else {
+                const want = latest ?? 'latest';
+                await rm(globalPkg(d), { force: true });
+                const r = await runProgram('npm', ['install', '-g', `sideby@${want}`], {
+                    env,
+                    ...(opts.onOutput ? { onOutput: opts.onOutput } : {}),
+                });
+                if (r.code !== 0) {
+                    await linkGlobal(d);
+                    return fail(`\`npm install -g sideby@${want}\` failed (exit ${r.code}); the local build stays. Run it yourself to see why`);
+                }
+                await rm(join(d.dev, 'npm'), { recursive: true, force: true });
+                message = `the global sideby runs the npm package ${want}`;
+            }
+        }
+    }
+    finally {
+        await release().catch(() => { });
+    }
+    const port = opts.panelPort ? await opts.panelPort().catch(() => null) : null;
+    const restartedPanel = port !== null && (await restartPanelByName(env, port));
+    return { ok: true, message, running: to, restartedPanel };
+}

package/dist/src/core/update.d.ts

@@ -91,6 +91,12 @@ export interface UpdateDeps {
 }
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
 export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
+/** Runs a program through the swappable machine (tests bind `exec`); a Local Build switch installs with it. */
+export declare const runProgram: UpdateDeps['exec'];
+/** Starts the background Panel again from the code `sideby` now names; see `UpdateDeps.restartPanel`. */
+export declare const restartPanelByName: (env: Env, port: number) => Promise<boolean>;
+/** The lock every install shares (`update-install.lock`), so a Local Build switch never races an Update. */
+export declare const takeInstallLock: (paths: Paths) => Promise<(() => Promise<void>) | null>;
 /** -1, 0 or 1 like a sort comparator; a prerelease sorts before its release. Null when either is not a version. */
 export declare function compareVersions(a: string, b: string): number | null;
 /** `latest` is newer than `current`. */

package/dist/src/core/update.js

@@ -102,6 +102,14 @@ export function bindUpdateDeps(deps) {
     };
 }
 const deps = () => ({ ...realDeps, ...override });
+/** Runs a program through the swappable machine (tests bind `exec`); a Local Build switch installs with it. */
+export const runProgram = (file, args, opts) => deps().exec(file, args, opts);
+/** Starts the background Panel again from the code `sideby` now names; see `UpdateDeps.restartPanel`. */
+export const restartPanelByName = (env, port) => deps()
+    .restartPanel(env, port)
+    .catch(() => false);
+/** The lock every install shares (`update-install.lock`), so a Local Build switch never races an Update. */
+export const takeInstallLock = (paths) => takeLock(paths, 'update-install.lock').catch(() => null);
 // Build metadata is limited to what semver allows, so a version never carries a terminal escape into the notice.
 const VERSION = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
 function parseVersion(v) {

package/dist/src/panel/handler.d.ts

@@ -102,6 +102,11 @@ export interface PanelUpdate {
      * Local Build, which `pnpm local --off` brings back to npm together with the skill.
      */
     skillUpdate?: import('../core/update.ts').SkillUpdatePlan;
+    /**
+     * The switch between a Local Build and the npm package (ADR-0024): present only while a Local Build runs or one is
+     * kept next to an npm install, so a plain install never sees it.
+     */
+    localSwitch?: import('../core/local-build.ts').LocalStatus;
 }
 export interface PanelState {
     schemaVersion: 1;

package/dist/src/panel/handler.js

@@ -76,8 +76,40 @@ async function updateState(rt, readOnly) {
         canRun: Boolean(plan?.canRun),
         skill: SKILL_INSTALL,
         ...(skillUpdate ? { skillUpdate } : {}),
+        ...(await localSwitchState(rt, method)),
     };
 }
+// npm's global prefix, asked once per process: the page reads the state every 20 s and `npm prefix -g` takes a while.
+let localDirsMemo = null;
+async function localDirsFor(rt) {
+    const lb = await import('../core/local-build.js');
+    localDirsMemo ??= lb.localDirs(rt.env).then((d) => {
+        if (!d)
+            localDirsMemo = null; // ask again next time
+        return d;
+    });
+    return localDirsMemo;
+}
+// An npm install knows its prefix; only a running Local Build needs npm asked where the global package is.
+async function switchDirs(rt, method) {
+    const lb = await import('../core/local-build.js');
+    return method.prefix ? { dev: lb.devDir(rt.env), prefix: method.prefix } : localDirsFor(rt);
+}
+async function localSwitchState(rt, method) {
+    if (method.kind !== 'local' && method.kind !== 'npm')
+        return {};
+    try {
+        const lb = await import('../core/local-build.js');
+        const d = await switchDirs(rt, method);
+        if (!d)
+            return {};
+        const s = await lb.localStatus(d);
+        return s.running === 'local' || (s.running === 'npm' && s.local) ? { localSwitch: s } : {};
+    }
+    catch {
+        return {};
+    }
+}
 /** The `handoff` map of the Panel state, from the statuses and Quota already read for the page. */
 export function handoffByFamily(rt, accounts, now) {
     const out = {};
@@ -696,6 +728,37 @@ export function createPanelHandler(opts) {
                 };
             },
         },
+        // The Local Build switch (ADR-0024): without `confirm` the current status; with it, `to` goes behind the global
+        // `sideby` and a background Panel restarts from it. The page then waits for the new build and reloads.
+        '/api/local': {
+            async run(body) {
+                if (!updates)
+                    throw new HttpError(403, 'updates are managed by the page that shows this panel');
+                const to = body.to;
+                if (to !== 'local' && to !== 'npm')
+                    throw new HttpError(400, '"to" must be "local" or "npm"');
+                const rt = await getRuntime();
+                const lb = await import('../core/local-build.js');
+                const d = await switchDirs(rt, await update.installMethod(rt.env));
+                if (!d)
+                    throw new UserError('`npm prefix -g` failed; switching needs npm on PATH and an npm global install');
+                if (!optBool(body, 'confirm'))
+                    return { ...(await lb.localStatus(d)), to, switched: false };
+                const { backgroundPanelPort } = await import('./background.js');
+                const r = await lb.switchLocal(rt.paths, d, to, rt.env, {
+                    panelPort: () => backgroundPanelPort(rt.paths),
+                });
+                if (!r.ok)
+                    throw new UserError(r.message);
+                return {
+                    ...(await lb.localStatus(d)),
+                    to,
+                    switched: !r.unchanged,
+                    message: r.message,
+                    restartedPanel: r.restartedPanel,
+                };
+            },
+        },
         // The Auto Update switch: config `update.auto`, shown as a diff first like every config change.
         '/api/update/settings': {
             writes: (body) => body.confirm === true,

package/dist/src/panel/i18n.d.ts

@@ -30,6 +30,13 @@ declare const en: {
     'upd.verTitle': string;
     'upd.local': string;
     'upd.localDirty': string;
+    'loc.toNpm': string;
+    'loc.toNpmHint': string;
+    'loc.toLocal': string;
+    'loc.toLocalHint': string;
+    'loc.switching': string;
+    'loc.stuck': string;
+    'loc.reload': string;
     'upd.open': string;
     'upd.autoIsOn': string;
     'upd.autoIsOff': string;

package/dist/src/panel/i18n.js

@@ -32,6 +32,13 @@ const en = {
     'upd.verTitle': 'sideby {v} · check for updates',
     'upd.local': 'Local build from this checkout, built {at}.',
     'upd.localDirty': 'Local build from this checkout, with changes not committed yet, built {at}.',
+    'loc.toNpm': 'Switch to the release',
+    'loc.toNpmHint': 'Go back to the version published on npm; switch here again to come back.',
+    'loc.toLocal': 'Switch to the local build',
+    'loc.toLocalHint': 'A local build is kept: {b}, built {at}. It is not rebuilt; pnpm local in the checkout builds a new one.',
+    'loc.switching': 'Switching…',
+    'loc.stuck': 'Switched, but this page still runs the old code. Reload it; a panel started with sideby ui needs a restart.',
+    'loc.reload': 'Reload page',
     'upd.open': 'Update…',
     'upd.autoIsOn': 'Auto Update: on',
     'upd.autoIsOff': 'Auto Update: off',
@@ -774,6 +781,13 @@ const zh = {
     'upd.verTitle': '当前 sideby {v} · 检查更新',
     'upd.local': '本地构建，来自仓库代码，构建于 {at}。',
     'upd.localDirty': '本地构建，含还没提交的改动，构建于 {at}。',
+    'loc.toNpm': '切换到正式版',
+    'loc.toNpmHint': '回到 npm 上发布的版本，之后可以在这里再切回来。',
+    'loc.toLocal': '切换到本地构建',
+    'loc.toLocalHint': '本机留着一份本地构建：{b}，构建于 {at}。切换不会重新构建；要新的就在仓库里运行 pnpm local。',
+    'loc.switching': '正在切换…',
+    'loc.stuck': '已经切换，但这个页面还在跑旧代码。刷新页面；用 sideby ui 打开的面板要重启一下。',
+    'loc.reload': '刷新页面',
     'upd.open': '更新…',
     'upd.autoIsOn': '自动更新：开',
     'upd.autoIsOff': '自动更新：关',

package/dist/src/panel/page-script.js

@@ -273,6 +273,7 @@ const MAIN = String.raw `
     x: 'M6 6l12 12M18 6L6 18',
     arrowUp: 'M12 19V5M5 12l7-7 7 7',
     arrowDown: 'M12 5v14M5 12l7 7 7-7',
+    swap: 'M7 4 3 8l4 4M3 8h14M17 20l4-4-4-4M21 16H7',
     // Lucide "pin" (ISC license)
     pin: 'M12 17v5M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z',
     bot: 'M6 9h12a2 2 0 0 1 2 2v6a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2v-6a2 2 0 0 1 2-2zM12 5v4M9.5 13.5v1M14.5 13.5v1',
@@ -3698,11 +3699,55 @@ const MAIN = String.raw `
         vp.checking ? spinner() : icon('refresh'), vp.checking ? t('upd.checking') : t('upd.check'))))
     }
     if (vp.error) kids.push(errorNote(vp.error, null))
+    const sw = localSwitchKids(u)
+    if (sw) kids.push(sw)
     if (u && !BOOT.readOnly && !isLocal(u))
       kids.push(h('p', { class: 'muted small popover-foot' }, t(u.auto ? 'upd.autoIsOn' : 'upd.autoIsOff'), ' · ',
         h('button', { class: 'link-btn', type: 'button', onclick: toDialog }, t('upd.settings'))))
     return kids
   }
+  // The switch between a Local Build and the npm package (ADR-0024), only where the state offers it: the other side,
+  // one button. After the switch the page waits for the server to run the new build and reloads into it.
+  const vs = { busy: false, to: null, waitUntil: 0, stuck: false, error: null }
+  function localSwitchKids(u) {
+    const ls = u && u.localSwitch
+    if (!ls || BOOT.readOnly) return null
+    // While it switches the state already shows the other side; keep the words of the side clicked.
+    const toNpm = vs.busy ? vs.to === 'npm' : ls.running === 'local'
+    if (!toNpm && !ls.local) return null
+    const l = ls.local
+    const build = l ? l.version + '-dev · ' + (l.commit || '?') + (l.dirty ? '+' : '') : ''
+    const kids = [h('p', { class: 'muted small' }, toNpm ? t('loc.toNpmHint') : t('loc.toLocalHint', { b: build, at: l.builtAt ? clock(l.builtAt) : '' }))]
+    if (vs.stuck) {
+      kids.push(h('p', { class: 'small' }, t('loc.stuck')))
+      kids.push(h('div', { class: 'popover-actions' }, h('button', { class: 'btn btn-sm btn-primary', type: 'button', onclick: () => location.reload() }, icon('refresh'), t('loc.reload'))))
+    } else {
+      kids.push(h('div', { class: 'popover-actions' }, h('button', { class: 'btn btn-sm', type: 'button', disabled: vs.busy, 'aria-busy': vs.busy ? 'true' : null, onclick: () => localSwitchTo(toNpm ? 'npm' : 'local') },
+        vs.busy ? spinner() : icon('swap'), vs.busy ? t('loc.switching') : t(toNpm ? 'loc.toNpm' : 'loc.toLocal'))))
+    }
+    if (vs.error) kids.push(errorNote(vs.error, null))
+    return h('div', { class: 'popover-foot' }, kids)
+  }
+  async function localSwitchTo(to) {
+    vs.busy = true
+    vs.to = to
+    vs.error = null
+    vs.stuck = false
+    renderVerPop()
+    try {
+      await api('/api/local', { to, confirm: true })
+    } catch (e) {
+      // A background Panel restarting from the new code may drop this answer: wait for the build all the same.
+      if (!e.network) { vs.busy = false; vs.error = e; renderVerPop(); return }
+    }
+    vs.waitUntil = Date.now() + 20000
+    localWait()
+  }
+  function localWait() {
+    if (S.newBuild) { location.reload(); return }
+    if (Date.now() > vs.waitUntil) { vs.busy = false; vs.stuck = true; renderVerPop(); return }
+    setTimeout(() => { void load({ silent: true }).then(localWait, localWait) }, 1500)
+  }
   async function verPopCheck() {
     vp.checking = true
     vp.error = null

package/dist/src/panel/page-styles.js

@@ -200,8 +200,10 @@ code, .mono { font-family: var(--mono); font-size: 0.92em; }
 .tag-login { font-weight: 400; }
 .login-detail { flex-direction: column; gap: 8px; }
 .login-detail .rd-note { margin: 0; }
-.login-dirs { display: flex; flex-direction: column; border: 1px solid var(--border); border-radius: var(--ctl-radius); background: var(--surface); }
-.login-dir { display: grid; grid-template-columns: minmax(120px, 1fr) auto var(--l-w) minmax(0, 1.4fr) auto auto auto; column-gap: 14px; align-items: center; padding: 6px 6px 6px 12px; }
+/* The directories share one set of columns (subgrid), so a wider cell in one line moves every line alike. */
+.login-dirs { display: grid; grid-template-columns: minmax(120px, 1fr) auto var(--l-w) minmax(0, 1.4fr) auto auto auto; column-gap: 14px; border: 1px solid var(--border); border-radius: var(--ctl-radius); background: var(--surface); }
+.login-dir { grid-column: 1 / -1; display: grid; grid-template-columns: subgrid; align-items: center; padding: 6px 6px 6px 12px; }
+.login-dir > * { justify-self: start; min-width: 0; }
 .login-dir + .login-dir { border-top: 1px solid var(--border); }
 .login-dir .ld-name { display: flex; align-items: center; gap: 6px; min-width: 0; }
 .login-dir .ld-name .name { font-weight: var(--strong-weight); }
@@ -697,7 +699,8 @@ select:is(:hover, :focus) { --chevron: var(--text); }
   .stat:nth-child(n) { border-top: 0; }
   .stat:nth-child(4) { border-left: 1px solid var(--border); }
   .row-end .icon-btn { width: 36px; height: 36px; }
-  .login-dir { grid-template-columns: minmax(0, 1fr) auto auto; row-gap: 6px; }
+  .login-dirs { grid-template-columns: minmax(0, 1fr); }
+  .login-dir { grid-template-columns: minmax(0, 1fr) auto auto; column-gap: 14px; row-gap: 6px; }
   .login-dir .usage, .login-dir .health { display: none; }
   .grid { grid-template-columns: 1fr; }
   .panel { padding: 14px; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Run work, personal and API-key accounts at the same time, without their configs drifting apart.",
   "license": "MIT",
   "author": "Adonis0123 (https://github.com/Adonis0123)",

package/schemas/local.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/local.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "running",
+    "local",
+    "kept",
+    "switched"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "running": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "local"
+        },
+        {
+          "type": "string",
+          "const": "npm"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "What the global sideby runs: the Local Build, an npm package, or neither (not an npm global install)."
+    },
+    "local": {
+      "anyOf": [
+        {
+          "type": "object",
+          "required": [
+            "commit",
+            "dirty",
+            "builtAt",
+            "version"
+          ],
+          "properties": {
+            "commit": {
+              "type": "string"
+            },
+            "dirty": {
+              "type": "boolean"
+            },
+            "builtAt": {
+              "type": "string"
+            },
+            "version": {
+              "type": "string"
+            }
+          }
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The newest Local Build, the one `on` switches to; null when `pnpm local` never ran."
+    },
+    "kept": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The npm package version kept aside while a Local Build runs."
+    },
+    "to": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "local"
+        },
+        {
+          "type": "string",
+          "const": "npm"
+        }
+      ]
+    },
+    "switched": {
+      "type": "boolean",
+      "description": "A switch ran and succeeded; false for status, a preview (exit 10) or a failure."
+    },
+    "blocked": {
+      "type": "string",
+      "description": "Why the switch cannot run, with what to do."
+    },
+    "message": {
+      "type": "string"
+    },
+    "restartedPanel": {
+      "type": "boolean"
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
+    }
+  },
+  "title": "sideby local --json"
+}

package/skills/sideby/SKILL.md

@@ -2,7 +2,7 @@
 name: sideby
 description: Use when the user runs, or wants to run, several AI coding accounts (Claude Code, Codex, Grok Build, pi) side by side. Covers installing sideby and setting up a new account ("install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x", "再加一个 Codex 账号"), explaining what accounts share and what stays separate ("what do my accounts share?", "这些账号共享了什么"), showing which account a session is ("show [cc001] in the status line", "加上账号标识"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, moving the current task to another account ("用 cc008 继续", "交回 cc008"), adding a short command (alias), and repairing drifted account directories (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json`; the agent does every step except browser sign-in, filling in secrets and starting interactive sessions, which it hands to the user as one command (inside an Auto Handoff session, `sideby handoff ready --to` moves the task itself).
 metadata:
-  version: "0.15.0"
+  version: "0.16.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help
@@ -45,6 +45,7 @@ Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique
 | Turn quota checks on or off, or refresh fetched quota | `sideby quota check <family> on|off --json`, `sideby quota [family] --refresh --json` | `references/quota.md` |
 | Set the model, effort or Remote Control | `sideby model <ref> --json`, `sideby remote-control --json` | `references/panel.md` |
 | Turn Auto Update on or off | `sideby update --auto on|off --json` | `references/update.md` |
+| Switch between a local build of sideby and the release ("切换到正式版", "切回 dev 版本") | `sideby local --json`, `sideby local on|off --json` (exits 10 first) | `references/update.md` |
 | Repair drift or permissions | `sideby doctor [ref] --json`, then `--fix` after they agree | `references/diagnose.md` |
 | Keep working because an account hit its limit | `sideby next <family> --json` | `references/handoff.md` |
 | Turn on Auto Handoff ("自动交接", "hand over when quota runs low"), see what it still needs, hand this session over now, or pick an account with room for a subtask | `sideby handoff status --json`, `sideby handoff enable --json` (exit 10 first), `sideby handoff ready`, `sideby next <family> --json` | `references/handoff.md` |

package/skills/sideby/references/update.md

@@ -18,3 +18,12 @@ What to do:
 ## Auto Update
 
 When the user asks to change Auto Update, run `sideby update --auto on|off --json`. It saves immediately and returns `auto` and `changed` (exit 0, including no-op). It keeps the Update Check setting and does not check or install in this invocation. It needs no `--yes`; ordinary `sideby update --json` still previews an installation with exit 10. Never enable Auto Update unless the user asks.
+
+## Local Build and the release
+
+For people who work on sideby itself. A Local Build (`pnpm local` in a sideby checkout) runs the checkout's code behind the global `sideby`. When the user asks to go back to the release, or to the local build again ("切换到正式版", "切回 dev 版本"):
+
+1. Run `sideby local --json`. `running` is what runs now (`local` or `npm`), `local` the kept Local Build (`version`, `commit`, `dirty`, `builtAt`), `kept` the npm version set aside.
+2. Run `sideby local off --json` (back to npm) or `sideby local on --json` (the kept Local Build). It exits `10` with the change; after their yes, add `--yes`. `on` does not rebuild: `pnpm local` in the checkout makes a new build. `blocked` (exit 1) says why it cannot and what to do.
+3. A background panel restarts by itself and open panels reload; a `sideby ui` in a terminal needs a restart.
+