sideby 0.11.0 → 0.12.0

package/dist/src/core/config.js

@@ -93,6 +93,14 @@ export const ConfigSchema = Type.Object({
         description: 'Make `sideby shell-init` also define Host-named functions (`claude`, `codex`, `grok`) that resume a session by id in the Account that holds it. Off by default.',
     })),
     handoff: Type.Optional(HandoffSchema),
+    update: Type.Optional(Type.Object({
+        check: Type.Optional(Type.Boolean({
+            description: 'Ask the npm registry once a day whether a newer sideby exists, and say so after a command and in the Panel. On by default; `NO_UPDATE_NOTIFIER` or `SIDEBY_NO_UPDATE_NOTIFIER` also turn it off.',
+        })),
+        auto: Type.Optional(Type.Boolean({
+            description: 'Install a newer version by itself after a check, when no `sideby run` is running and the version is not a major one. Off by default.',
+        })),
+    }, { additionalProperties: false, description: 'Update Check and Auto Update (ADR-0021).' })),
     shellInitFile: Type.Optional(Type.Object({
         zsh: Type.Optional(Type.String({ minLength: 1 })),
         bash: Type.Optional(Type.String({ minLength: 1 })),
@@ -158,8 +166,8 @@ async function configTarget(file) {
     return (await lstatOrNull(file))?.isSymbolicLink() ? ((await realpathOrNull(file)) ?? file) : file;
 }
 /**
- * Re-reads the config file, lets `edit` change one top-level `key` (the only two sideby writes are `aliases` and
- * `handoff`, spec §3.10), and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
+ * Re-reads the config file, lets `edit` change one top-level `key` (sideby writes only `aliases`, `handoff`,
+ * `accounts` and `update`, spec §3.10), and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
  * with a trailing newline, atomically, keeping the file's mode (0600 for a new file). Refuses, without writing, a
  * file that is not valid JSON or not a valid config, a result that is not a valid config, or a file that changed
  * while sideby wrote it. `edit` returns null to leave the file alone; `dryRun` returns the change without writing.
@@ -224,6 +232,13 @@ async function editConfigAliases(file, retry, edit) {
 export function editConfigHandoff(file, edit, opts = {}) {
     return editConfigKey(file, 'handoff', 'run the command', (current) => edit(current ?? {}), opts);
 }
+/**
+ * The Panel's Auto Update switch (spec §3.23): changes the config `update` key with `edit` (see `editConfigKey` for
+ * how the file is written). With `dryRun`, shows the change without writing.
+ */
+export function editConfigUpdate(file, edit, opts = {}) {
+    return editConfigKey(file, 'update', 'change the setting', (current) => edit(current ?? {}), opts);
+}
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is
  * written). With `dryRun`, shows the change without writing.

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

@@ -0,0 +1,209 @@
+import type { Env } from '../types.ts';
+import type { Paths } from './paths.ts';
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export declare const CHECK_INTERVAL_MS: number;
+export declare const NOTICE_INTERVAL_MS: number;
+/** After a failed check (offline, a mirror without the endpoint) the next one waits this long. */
+export declare const RETRY_INTERVAL_MS: number;
+/** A failed Auto Update of one version is tried again after this long (a mirror may not have it yet). */
+export declare const AUTO_RETRY_MS: number;
+export declare const RELEASE_NOTES: (v: string) => string;
+/** What `update.json` in the state directory holds. Every field is optional; a broken file reads as `{}`. */
+export interface UpdateCache {
+    /** When the registry last answered. */
+    checkedAt?: string;
+    /** When a check was last tried, answered or not. */
+    triedAt?: string;
+    /** The `latest` dist-tag it answered. */
+    latest?: string;
+    /** When a background check last looked at Auto Update (installed, or waited for a running session). */
+    autoTriedAt?: string;
+    /** The last Update Notice the CLI printed. */
+    notified?: {
+        version: string;
+        at: string;
+    };
+    /** The last Auto Update; `shown` once the CLI has said so. */
+    auto?: {
+        from: string;
+        to: string;
+        at: string;
+        ok: boolean;
+        message: string;
+        shown?: boolean;
+    };
+}
+export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source';
+export interface InstallMethod {
+    kind: InstallKind;
+    /** The installed package folder (real path). */
+    packageDir: string;
+    /** True when sideby can run the Update itself (npm, pnpm or bun global, and npm's folders are writable). */
+    canUpdate: boolean;
+    /** Why it cannot, in a phrase that follows "sideby cannot update itself: ". */
+    reason?: string;
+    /** npm only: the prefix whose `lib/node_modules` holds sideby. */
+    prefix?: string;
+}
+/** Swapped in tests through `bindUpdateDeps`; the real machine otherwise. */
+export interface UpdateDeps {
+    fetch: typeof fetch;
+    now: () => Date;
+    /** Real path of the running sideby package. */
+    packageDir: () => Promise<string>;
+    writable: (dir: string) => Promise<boolean>;
+    alive: (pid: number) => boolean;
+    /** Runs a program, streaming its output to `onOutput`; resolves with the exit code and the whole output. */
+    exec: (file: string, args: readonly string[], opts: {
+        env: Env;
+        onOutput?: (text: string) => void;
+    }) => Promise<{
+        code: number;
+        output: string;
+    }>;
+    /** Starts `sideby ui --background --no-open --port <port>` from the newly installed code, detached; false when it could not start. */
+    restartPanel: (env: Env, port: number) => Promise<boolean>;
+}
+/** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
+export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
+/** -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`. */
+export declare const isNewer: (latest: string | undefined, current: string) => latest is string;
+/**
+ * The jump keeps the major version (0.11 → 0.12, 1.2 → 1.9). Auto Update only takes these; 0.x → 1.0 or 1.x → 2.0
+ * only gets a notice.
+ */
+export declare function sameLine(from: string, to: string): boolean;
+/** True in CI, where a notice is noise and a check is a request nobody reads. */
+export declare const inCi: (env: Env) => boolean;
+type UpdateSettings = {
+    update?: {
+        check?: boolean;
+        auto?: boolean;
+    };
+};
+/** Why Update Checks are off, or null when they are on (spec §3.23). */
+export declare function checksOff(env: Env, config: UpdateSettings): string | null;
+export declare function readUpdateCache(paths: Paths): Promise<UpdateCache>;
+/**
+ * Merges a change into the cache file. The file is read again first, and `change` may be a function of what is there
+ * now, so a writer that decides from an older read (the CLI marking an Auto Update shown) never overwrites a newer
+ * field another process wrote meanwhile.
+ */
+export declare function updateUpdateCache(paths: Paths, change: Partial<UpdateCache> | ((now: UpdateCache) => Partial<UpdateCache>)): Promise<UpdateCache>;
+/** A check is due: no answer within a day, and no attempt within the hour (so being offline costs one try an hour). */
+export declare function checkDue(cache: UpdateCache, now: Date): boolean;
+/**
+ * Auto Update is on and the cache names a newer version it has not installed: never tried, or a failed try a day
+ * ago. Lets the CLI start a background check even when a Panel already ran today's check.
+ */
+export declare function autoPending(cache: UpdateCache, current: string, config: UpdateSettings, now: Date): boolean;
+/** Asks the registry for the `latest` dist-tag. Throws with a message that names the registry and what to do. */
+export declare function fetchLatest(env: Env): Promise<string>;
+/** Runs one Update Check and records it, answered or not. Never throws. */
+export declare function refreshUpdateCheck(paths: Paths, env: Env): Promise<UpdateCache>;
+/**
+ * The Update Notice line the CLI may print now, or null. Once per new version per day; `current` is the running
+ * version.
+ */
+export declare function noticeLine(cache: UpdateCache, current: string, now: Date): string | null;
+/** What the CLI says once about the last Auto Update, or null. */
+export declare function autoUpdateLine(cache: UpdateCache): string | null;
+/**
+ * What the CLI does after a command (spec §3.23), decided from the cache: the lines to print (the Auto Update result,
+ * 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 declare function afterCommandPlan(cache: UpdateCache, current: string, config: UpdateSettings, env: Env, now: Date): {
+    lines: string[];
+    record: ((cur: UpdateCache) => Partial<UpdateCache>) | null;
+    startCheck: boolean;
+};
+/** Where the running copy comes from (spec §3.23 table); reads only paths. */
+export declare function installMethod(env: Env): Promise<InstallMethod>;
+/**
+ * The command an Update runs (or that the user runs) for `version`; `run` is set only when sideby may run it. With
+ * `SIDEBY_UPDATE_REGISTRY`, installs use that registry too, so the version the check found is the one fetched.
+ */
+export declare function updateCommand(method: InstallMethod, version: string, env?: Env): {
+    text: string;
+    run?: {
+        file: string;
+        args: string[];
+    };
+};
+/**
+ * Records that this process runs a Host (`run`, `login`, `next`, `resume`) so an Auto Update waits for it; returns the
+ * function that removes the record. Failing to write the record never stops a Launch.
+ */
+export declare function markRunning(paths: Paths, pid?: number): Promise<() => Promise<void>>;
+/** Pids of sideby processes that run a Host now; records of processes that ended are removed. */
+export declare function runningSessions(paths: Paths): Promise<number[]>;
+export interface UpdatePlan {
+    current: string;
+    latest: string;
+    available: boolean;
+    method: InstallMethod;
+    /** The command for the user to see; `canRun` says whether sideby runs it after a confirmation. */
+    command: string;
+    canRun: boolean;
+    releaseNotes: string;
+}
+export declare function planFrom(method: InstallMethod, current: string, latest: string, env?: Env): UpdatePlan;
+/** The Install Method as outputs show it: no folder of this machine. */
+export declare const shownMethod: (m: InstallMethod) => {
+    kind: InstallKind;
+    canUpdate: boolean;
+    reason?: string | undefined;
+};
+/** The plan as `sideby update --json` and the Panel show it (schemas/update.json). */
+export declare function shownPlan(plan: UpdatePlan): {
+    current: string;
+    latest: string;
+    available: boolean;
+    method: {
+        kind: InstallKind;
+        canUpdate: boolean;
+        reason?: string | undefined;
+    };
+    command: string;
+    canRun: boolean;
+    releaseNotes: string;
+};
+/** Asks the registry now (whatever the switches say: the user asked) and returns what an Update would do. */
+export declare function planUpdate(paths: Paths, env: Env): Promise<UpdatePlan>;
+export interface UpdateResult {
+    ok: boolean;
+    /** Exit code of the install command; absent when it did not run. */
+    code?: number;
+    output: string;
+    message: string;
+    /** A background Panel was running and is starting again from the new code. */
+    restartedPanel: boolean;
+    /** Another Update held the lock; nothing ran. */
+    busy?: boolean;
+}
+/**
+ * Runs the Update the plan names, then starts a running background Panel again from the new code. The caller has
+ * shown the plan and got a confirmation (or this is an Auto Update). One Update runs at a time on this machine (the
+ * CLI, a Panel and an Auto Update share the lock). `panelPort` gives the port of the background Panel to restart, or
+ * null when none runs. A successful Update is recorded as said, so no notice for it follows.
+ */
+export declare function applyUpdate(paths: Paths, plan: UpdatePlan, env: Env, opts?: {
+    onOutput?: (text: string) => void;
+    panelPort?: () => Promise<number | null>;
+}): Promise<UpdateResult>;
+/** What keeps an Auto Update from installing `plan` until the user acts (an install it cannot update, a major version). */
+export declare function lastingBlocker(plan: UpdatePlan): string | null;
+/**
+ * Whether an Auto Update may install `plan` now (spec §3.23), and if not, why. Running sessions are looked up
+ * last because that removes records of ended processes.
+ */
+export declare function autoUpdateBlocker(paths: Paths, plan: UpdatePlan): Promise<string | null>;
+/**
+ * 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.
+ */
+export declare function backgroundCheck(paths: Paths, env: Env, config: UpdateSettings, panelPort: () => Promise<number | null>): Promise<void>;
+export {};