sideby 0.14.0 → 0.16.0

package/dist/src/core/update.js

@@ -6,7 +6,7 @@ import { access, constants, mkdir, open, readdir, readFile, realpath, rm, stat }
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileAtomic } from './fs-safe.js';
-import { gitRootOf, installedSkills, SKILL_INSTALL, SKILL_UPDATE } from './skill-check.js';
+import { installedSkills, SKILL_UPDATE, SKILL_UPDATE_SHOWN, skillOwnerRepo } from './skill-check.js';
 import { localBuild, packageVersion, parseLocalBuild } from './version.js';
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -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) {
@@ -151,21 +159,25 @@ export function sameLine(from, to) {
 const set = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
 /** True in CI, where a notice is noise and a check is a request nobody reads. */
 export const inCi = (env) => set(env.CI) || set(env.CONTINUOUS_INTEGRATION) || set(env.BUILD_NUMBER);
-/** Why Update Checks are off, or null when they are on (spec §3.23). */
-export function checksOff(env, config, local = localBuild() !== null) {
+/** Why Update Checks are off, with a code for the Panel, or null when they are on (spec §3.23). */
+export function checksOffWhy(env, config, local = localBuild() !== null) {
     // A Local Build (ADR-0024) follows the checkout: a notice or an Auto Update would only replace it with npm's.
     if (local)
-        return 'this is a local build (pnpm local)';
+        return { code: 'local-build', text: 'this is a local build (pnpm local)' };
     if (set(env.SIDEBY_NO_UPDATE_NOTIFIER))
-        return 'SIDEBY_NO_UPDATE_NOTIFIER is set';
+        return { code: 'env', text: 'SIDEBY_NO_UPDATE_NOTIFIER is set' };
     if (set(env.NO_UPDATE_NOTIFIER))
-        return 'NO_UPDATE_NOTIFIER is set';
+        return { code: 'env', text: 'NO_UPDATE_NOTIFIER is set' };
     if (config.update?.check === false)
-        return 'config update.check is false';
+        return { code: 'config', text: 'config update.check is false' };
     if (inCi(env))
-        return 'running in CI';
+        return { code: 'ci', text: 'running in CI' };
     return null;
 }
+/** Why Update Checks are off, or null when they are on (spec §3.23). */
+export function checksOff(env, config, local = localBuild() !== null) {
+    return checksOffWhy(env, config, local)?.text ?? null;
+}
 // ---- registry
 /** The registry checks and installs use: `SIDEBY_UPDATE_REGISTRY` (http or https only), else npm's. */
 function registryOf(env) {
@@ -217,6 +229,18 @@ export async function readUpdateCache(paths) {
                 message: a.message,
                 ...(a.shown ? { shown: true } : {}),
             };
+        const sn = d.skillNotified;
+        if (sn && str(sn.version) && str(sn.at))
+            out.skillNotified = { version: sn.version, at: sn.at };
+        const sa = d.skillAuto;
+        if (sa && str(sa.to) && str(sa.at) && typeof sa.ok === 'boolean' && str(sa.message))
+            out.skillAuto = {
+                to: sa.to,
+                at: sa.at,
+                ok: sa.ok,
+                message: sa.message,
+                ...(sa.shown ? { shown: true } : {}),
+            };
         return out;
     }
     catch {
@@ -352,6 +376,44 @@ export function autoUpdateLine(cache) {
         ? `sideby updated itself from ${a.from} to ${a.to} (${RELEASE_NOTES(a.to)})`
         : `sideby could not update itself to ${a.to}: ${a.message}`;
 }
+/** What the CLI says once about the skill Auto Update brought up to date alone, or null. */
+export function skillAutoLine(cache) {
+    const a = cache.skillAuto;
+    if (!a || a.shown)
+        return null;
+    return a.ok
+        ? `sideby updated the sideby skill agents read to ${a.to}`
+        : `sideby could not update the sideby skill to ${a.to}: ${a.message}`;
+}
+/** The skill part of a `SkillUpdatePlan` toward the running version, as `afterCommandPlan` takes it. */
+export const skillBehind = (plan, current) => plan?.outdated
+    ? { installed: plan.installed.find((v) => v !== current) ?? null, canRun: plan.canRun }
+    : null;
+/**
+ * The line about a skill behind this version the CLI may print now (spec §3.23), or null: once a day per CLI version,
+ * and never while Auto Update is on (the background check brings the skill along) and sideby may update it.
+ */
+export function skillNoticeLine(cache, current, config, skill, now) {
+    if (!skill || (config.update?.auto === true && skill.canRun))
+        return null;
+    const n = cache.skillNotified;
+    if (n && n.version === current && age(n.at, now) < NOTICE_INTERVAL_MS)
+        return null;
+    return `the sideby skill agents read is for ${skill.installed ?? 'an older sideby'} (this sideby is ${current}) · run \`sideby update\``;
+}
+/**
+ * Auto Update is on, the CLI is the newest version the cache knows, and the skill is behind it where sideby may
+ * update it, not tried for this version yet (or a failed try a day ago). A newer CLI waiting is left to the Update
+ * of the CLI: the skills tool fetches the default branch, which would put the skill ahead of this CLI.
+ */
+export function skillAutoPending(cache, current, config, skill, now) {
+    if (config.update?.auto !== true || !skill?.canRun || isNewer(cache.latest, current))
+        return false;
+    const a = cache.skillAuto;
+    if (!a || a.to !== current)
+        return true;
+    return !a.ok && !(age(a.at, now) < AUTO_RETRY_MS);
+}
 /**
  * The `_notice` for a `--json` output, from the cached Update Check and the versions of the installed sideby skills
  * (`null` for one written before skills had a version); null when there is nothing to say or checks are off. It
@@ -383,27 +445,40 @@ export function jsonNotice(cache, current, config, env, skills, skillCommand) {
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
  * writes `record` with `updateUpdateCache` and starts the check; nothing here touches the machine.
  */
-export function afterCommandPlan(cache, current, config, env, now) {
+export function afterCommandPlan(cache, current, config, env, now, skill = null) {
     if (checksOff(env, config))
         return { lines: [], record: null, startCheck: false };
     const lines = [];
     const auto = autoUpdateLine(cache);
+    const skillAuto = skillAutoLine(cache);
     const notice = noticeLine(cache, current, now);
-    if (auto)
-        lines.push(auto);
-    if (notice)
-        lines.push(notice);
+    // A newer CLI's notice already leads to `sideby update`, which brings the skill along.
+    const skillNotice = notice ? null : skillNoticeLine(cache, current, config, skill, now);
+    for (const l of [auto, skillAuto, notice, skillNotice])
+        if (l)
+            lines.push(l);
     const shownAuto = cache.auto;
+    const shownSkillAuto = cache.skillAuto;
     const record = lines.length
         ? (cur) => ({
             // Mark only the Auto Update that was printed; a newer one written meanwhile stays to be said.
             ...(auto && cur.auto && cur.auto.at === shownAuto?.at && cur.auto.to === shownAuto.to
                 ? { auto: { ...cur.auto, shown: true } }
                 : {}),
+            ...(skillAuto && cur.skillAuto && cur.skillAuto.at === shownSkillAuto?.at
+                ? { skillAuto: { ...cur.skillAuto, shown: true } }
+                : {}),
             ...(notice ? { notified: { version: cache.latest, at: now.toISOString() } } : {}),
+            ...(skillNotice ? { skillNotified: { version: current, at: now.toISOString() } } : {}),
         })
         : null;
-    return { lines, record, startCheck: checkDue(cache, now) || autoPending(cache, current, config, now) };
+    return {
+        lines,
+        record,
+        startCheck: checkDue(cache, now) ||
+            autoPending(cache, current, config, now) ||
+            skillAutoPending(cache, current, config, skill, now),
+    };
 }
 // ---- Install Method
 /** Where the running copy comes from (spec §3.23 table); reads only paths. */
@@ -421,16 +496,20 @@ export async function installMethod(env) {
         if (parseLocalBuild(JSON.parse(await readFile(join(packageDir, 'dist', 'build.json'), 'utf8'))))
             return at('local', {
                 reason: 'it is a local build; run `pnpm local --off` in the sideby checkout to go back to npm',
+                reasonCode: 'local-build',
             });
     }
     catch {
         // no build file: not a Local Build
     }
     if (p.includes('/_npx/'))
-        return at('npx', { reason: 'it runs from the npx cache, which fetches a version per call' });
+        return at('npx', {
+            reason: 'it runs from the npx cache, which fetches a version per call',
+            reasonCode: 'npx',
+        });
     // Volta keeps a global package under its own npm prefix; installing there behind its back breaks its records.
     if (p.includes('/.volta/'))
-        return at('volta', { reason: 'Volta manages this install' });
+        return at('volta', { reason: 'Volta manages this install', reasonCode: 'volta' });
     const npm = /^(.*)\/lib\/node_modules\/sideby$/.exec(p);
     if (npm) {
         const prefix = npm[1];
@@ -442,7 +521,11 @@ export async function installMethod(env) {
             prefix,
             canUpdate: !blocked.length,
             ...(blocked.length
-                ? { reason: `${blocked.join(' and ')} ${blocked.length > 1 ? 'are' : 'is'} not writable by you` }
+                ? {
+                    reason: `${blocked.join(' and ')} ${blocked.length > 1 ? 'are' : 'is'} not writable by you`,
+                    reasonCode: 'not-writable',
+                    reasonAt: blocked.join(', '),
+                }
                 : {}),
         });
     }
@@ -452,8 +535,8 @@ export async function installMethod(env) {
     if (p.includes('/.bun/install/global/'))
         return at('bun', { canUpdate: true });
     if (p.includes('/node_modules/'))
-        return at('project', { reason: 'it is a dependency of a project' });
-    return at('source', { reason: 'it runs from a source checkout' });
+        return at('project', { reason: 'it is a dependency of a project', reasonCode: 'project' });
+    return at('source', { reason: 'it runs from a source checkout', reasonCode: 'source' });
 }
 /**
  * The command an Update runs (or that the user runs) for `version`; `run` is set only when sideby may run it. With
@@ -548,6 +631,8 @@ export const shownMethod = (m) => ({
     kind: m.kind,
     canUpdate: m.canUpdate,
     ...(m.reason ? { reason: m.reason } : {}),
+    ...(m.reasonCode ? { reasonCode: m.reasonCode } : {}),
+    ...(m.reasonAt ? { reasonAt: m.reasonAt } : {}),
 });
 /** The plan as `sideby update --json` and the Panel show it (schemas/update.json). */
 export function shownPlan(plan) {
@@ -575,14 +660,17 @@ export async function skillUpdatePlan(home, target) {
         canRun: true,
     };
     for (const s of skills) {
-        const root = await gitRootOf(s.dir);
+        // A git repository owns the skill unless the skills tool records installing it there (spec §3.23).
+        const root = await skillOwnerRepo(s.dir);
         if (root) {
             const at = root.startsWith(home) ? `~${root.slice(home.length)}` : root;
             return {
                 ...plan,
-                command: SKILL_INSTALL,
+                command: SKILL_UPDATE_SHOWN,
                 canRun: false,
                 reason: `the skill is in the git repository ${at}, so sideby leaves it alone; update it where that repository comes from`,
+                reasonCode: 'skill-in-git',
+                reasonAt: at,
             };
         }
     }
@@ -609,6 +697,27 @@ export async function applySkillUpdate(plan, env, onOutput) {
         ? { ok: true, message: 'updated the sideby skill' }
         : { ok: false, message: `\`${plan.command}\` failed (exit ${r.code}); run it yourself to see why` };
 }
+/**
+ * Updates only the sideby skill, for a CLI that is already current (`sideby update`, the Panel, Auto Update). Holds
+ * the same lock as an Update, so a skill update never runs beside one; null when there was nothing to do.
+ */
+export async function applySkillOnly(paths, plan, env, onOutput) {
+    if (!plan?.outdated || !plan.canRun)
+        return null;
+    const release = await takeLock(paths, 'update-install.lock').catch(() => null);
+    if (!release)
+        return {
+            ok: false,
+            busy: true,
+            message: 'another sideby update is running; wait for it to finish, then run `sideby update` again',
+        };
+    try {
+        return await applySkillUpdate(plan, env, onOutput);
+    }
+    finally {
+        await release().catch(() => { });
+    }
+}
 /**
  * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
  * desktop app is installed, runs `sideby app install` again from the new code. The caller has
@@ -689,6 +798,22 @@ export async function autoUpdateBlocker(paths, plan) {
         return `a session is running (pid ${running.join(', ')})`;
     return null;
 }
+/**
+ * The skill half of Auto Update (spec §3.23): with the CLI current, a skill behind it is updated alone and the result
+ * recorded once per version, so a failure waits a day.
+ */
+async function skillAutoSync(paths, env, config, cache, current, now) {
+    const plan = await skillUpdatePlan(paths.home, current).catch(() => null);
+    if (!skillAutoPending(cache, current, config, skillBehind(plan, current), now))
+        return;
+    const r = await applySkillOnly(paths, plan ?? undefined, env);
+    // A manual Update holding the lock is not a failure; the next command looks again.
+    if (!r || r.busy)
+        return;
+    await updateUpdateCache(paths, {
+        skillAuto: { to: current, at: deps().now().toISOString(), ok: r.ok, message: r.message },
+    });
+}
 /**
  * Body of the detached `sideby update-check`: an Update Check when one is due, then an Auto Update when config
  * `update.auto` is on and nothing blocks it. Only one runs at a time; it never throws.
@@ -705,9 +830,16 @@ export async function backgroundCheck(paths, env, config, panelPort) {
         if (checkDue(cache, now))
             cache = await refreshUpdateCheck(paths, env);
         const current = packageVersion();
-        if (!autoPending(cache, current, config, now))
+        if (!autoPending(cache, current, config, now)) {
+            await skillAutoSync(paths, env, config, cache, current, now);
             return;
-        const plan = planFrom(await installMethod(env), current, cache.latest, env);
+        }
+        // The skill teaches agents the new version's commands, so an Auto Update carries it as `sideby update` does.
+        const skill = await skillUpdatePlan(paths.home, cache.latest).catch(() => null);
+        const plan = {
+            ...planFrom(await installMethod(env), current, cache.latest, env),
+            ...(skill ? { skill } : {}),
+        };
         await updateUpdateCache(paths, { autoTriedAt: now.toISOString() });
         // A blocker only the user can lift is said once and looked at again a day later, like a failed install; a
         // running session only delays it (the next look is within the hour).

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

@@ -81,12 +81,15 @@ export interface PanelUpdate {
     checkedAt?: string;
     /** Why Update Checks are off; absent when they are on. */
     checksOff?: string;
+    checksOffCode?: update.ChecksOffCode;
     /** Config `update.auto`. */
     auto: boolean;
     method: {
         kind: update.InstallKind;
         canUpdate: boolean;
         reason?: string;
+        reasonCode?: update.ReasonCode;
+        reasonAt?: string;
     };
     /** The command an Update runs, or the one to run by hand when `canRun` is false. */
     command?: string;
@@ -94,8 +97,16 @@ export interface PanelUpdate {
     releaseNotes?: string;
     /** The command that installs the sideby skill by hand. */
     skill: string;
-    /** The installed sideby skill, which an Update brings along (spec §3.23); absent when none is installed. */
+    /**
+     * The installed sideby skill, which an Update brings along (spec §3.23); absent when none is installed, and for a
+     * 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

@@ -53,7 +53,7 @@ let checking = null;
  */
 async function updateState(rt, readOnly) {
     const current = packageVersion();
-    const off = update.checksOff(rt.env, rt.config);
+    const off = update.checksOffWhy(rt.env, rt.config);
     const cache = await update.readUpdateCache(rt.paths);
     if (!off && !readOnly && !checking && update.checkDue(cache, new Date()))
         checking = update.refreshUpdateCheck(rt.paths, rt.env).finally(() => {
@@ -61,23 +61,55 @@ async function updateState(rt, readOnly) {
         });
     const method = await update.installMethod(rt.env);
     const plan = cache.latest ? update.shownPlan(update.planFrom(method, current, cache.latest, rt.env)) : null;
-    const skillUpdate = await update
-        .skillUpdatePlan(rt.paths.home, plan?.available ? plan.latest : current)
-        .catch(() => null);
+    const skillUpdate = method.kind === 'local'
+        ? null
+        : await update.skillUpdatePlan(rt.paths.home, plan?.available ? plan.latest : current).catch(() => null);
     return {
         current,
         ...(cache.latest ? { latest: cache.latest } : {}),
         available: Boolean(plan?.available),
         ...(cache.checkedAt ? { checkedAt: cache.checkedAt } : {}),
-        ...(off ? { checksOff: off } : {}),
+        ...(off ? { checksOff: off.text, checksOffCode: off.code } : {}),
         auto: rt.config.update?.auto === true,
         method: update.shownMethod(method),
         ...(plan ? { command: plan.command, releaseNotes: plan.releaseNotes } : {}),
         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 = {};
@@ -329,6 +361,11 @@ function displayBody(body) {
                 throw new HttpError(400, '"accounts" must be an object');
             out.accounts = Object.fromEntries(Object.entries(v).map(([f, list]) => [f, names(list, `"accounts.${f}"`)]));
         }
+        else if (k === 'pinned') {
+            if (!v || typeof v !== 'object' || Array.isArray(v))
+                throw new HttpError(400, '"pinned" must be an object');
+            out.pinned = Object.fromEntries(Object.entries(v).map(([f, list]) => [f, names(list, `"pinned.${f}"`)]));
+        }
         else
             throw new HttpError(400, `unknown key "${k}"`);
     }
@@ -661,6 +698,17 @@ export function createPanelHandler(opts) {
                 const shown = update.shownPlan(plan);
                 if (!optBool(body, 'confirm'))
                     return { ...shown, updated: false };
+                // The CLI is current and the skill is behind: `skill: true` updates it alone, as `sideby update --yes` does.
+                if (optBool(body, 'skill')) {
+                    if (plan.available || plan.method.kind === 'local')
+                        return { ...shown, updated: false, changed: true };
+                    const r = await update.applySkillOnly(rt.paths, plan.skill, rt.env);
+                    if (!r)
+                        return { ...shown, updated: false, changed: true };
+                    if (!r.ok)
+                        throw new UserError(r.message);
+                    return { ...shown, updated: false, skillUpdated: true, message: r.message };
+                }
                 // A confirmation that runs nothing always says why: the registry names another version (or none newer) now.
                 if (body.version !== plan.latest || !plan.available)
                     return { ...shown, updated: false, changed: true };
@@ -680,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,