sideby 0.0.0-stage → 0.2.1

package/dist/src/core/shell-init.js

@@ -0,0 +1,84 @@
+// The shell functions `sideby shell-init` prints, and the optional files (config `shellInitFile`) sideby keeps
+// in sync with them whenever it adds an Account or an alias.
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ALIAS_NAME, aliasProblem, RESERVED_ALIASES } from './config.js';
+import { realpathOrNull, statOrNull, writeFileAtomic } from './fs-safe.js';
+import { expandUserPath } from './paths.js';
+export const SHELLS = ['zsh', 'bash'];
+/** First line of every generated script; an existing file without it is never overwritten. */
+export const SHELL_INIT_HEADER = '# sideby shell-init: one function per account, plus aliases from the sideby config';
+const quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+const SHELL_VAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A shell `case` pattern for a session id: 36 characters with dashes where a UUID has them. */
+const SESSION_ID_GLOB = '????????-????-????-????-????????????';
+/**
+ * The Host-named function for one routed Family, or null when its names are not safe in a shell (spec §3.15). It
+ * starts sideby only when an argument looks like a session id, so a plain Host command costs nothing extra.
+ * `function name {` because zsh expands an alias of the same name in `name() {`.
+ */
+function resumeRouteFunction(r) {
+    if (!ALIAS_NAME.test(r.bin) || RESERVED_ALIASES.has(r.bin) || !SHELL_VAR.test(r.selectVar))
+        return null;
+    const id = SESSION_ID_GLOB;
+    return [
+        `function ${r.bin} { local a; if [ -z "\${${r.selectVar}-}" ]; then for a in "$@"; do case $a in ${id}|--resume=${id})`,
+        ` command sideby resume ${quote(r.family)} -- "$@"; return;; esac; done; fi; command ${r.bin} "$@"; }`,
+    ].join('');
+}
+/**
+ * The script for one shell, ending in a newline: exactly what `sideby shell-init <shell>` prints. zsh and bash
+ * read the same function syntax, so the shell only names the file it goes to.
+ */
+export function shellInitScript(accounts, aliases, routes = []) {
+    const lines = [SHELL_INIT_HEADER];
+    for (const acc of accounts)
+        lines.push(`sideby-${acc.family}-${acc.name}() { command sideby run ${quote(acc.ref)} -- "$@"; }`);
+    // An alias function runs the alias itself, so `sideby run` reads its Account and arguments from the config.
+    for (const alias of Object.keys(aliases ?? {}))
+        if (!aliasProblem(alias))
+            lines.push(`${alias}() { command sideby run ${quote(alias)} -- "$@"; }`);
+    // An Alias with the Host's name wins: it already starts a chosen Account.
+    for (const r of routes) {
+        const fn = aliases && Object.hasOwn(aliases, r.bin) ? null : resumeRouteFunction(r);
+        if (fn)
+            lines.push(fn);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Writes `content` to the configured file atomically (temp file in the same directory, then rename), keeping its
+ * mode (0644 for a new file). Refuses a relative path and an existing file that sideby did not generate, so a
+ * mistyped `shellInitFile` can never replace a shell rc file.
+ */
+export async function writeShellInitFile(shell, configured, home, content) {
+    const base = { shell, path: configured };
+    const expanded = expandUserPath(configured, home);
+    if (!expanded)
+        return { ...base, ok: false, message: `shellInitFile.${shell} must be an absolute or ~/ path` };
+    try {
+        // Follow a link (a dotfiles manager may link the file) and replace the real file.
+        const target = (await realpathOrNull(expanded)) ?? expanded;
+        const st = await statOrNull(target);
+        if (st && !st.isFile())
+            return { ...base, ok: false, message: `${configured} is not a regular file` };
+        if (st) {
+            const current = await readFile(target, 'utf8');
+            if (current === content)
+                return { ...base, ok: true, action: 'unchanged' };
+            if (current.trim() && !current.startsWith(SHELL_INIT_HEADER))
+                return {
+                    ...base,
+                    ok: false,
+                    message: `${configured} was not written by sideby shell-init; move it aside or point shellInitFile.${shell} at another file`,
+                };
+        }
+        else
+            await mkdir(dirname(target), { recursive: true });
+        await writeFileAtomic(target, content, st ? st.mode & 0o777 : 0o644);
+        return { ...base, ok: true, action: 'written' };
+    }
+    catch (err) {
+        return { ...base, ok: false, message: `cannot write ${configured}: ${err.message}` };
+    }
+}

package/dist/src/core/skill-check.d.ts

@@ -0,0 +1,11 @@
+import type { FamilyDef, Finding } from '../types.ts';
+export declare const SKILL_INSTALL = "npx skills add Adonis0123/sideby -g";
+/** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
+export declare function skillVersionOf(text: string): string | null;
+/**
+ * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
+ * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read
+ * once per Family, so the result for one Family never depends on which others are checked with it. Findings
+ * are general and belong to that Family's Main Account.
+ */
+export declare function checkInstalledSkills(home: string, families: readonly FamilyDef[], version: string): Promise<Finding[]>;

package/dist/src/core/skill-check.js

@@ -0,0 +1,57 @@
+// Doctor's look at an installed sideby Agent Skill (spec §3.11). Read-only: a skill written for another
+// sideby version teaches commands this CLI may not have, so a version mismatch is a warning with the
+// reinstall command. Not installed is not a problem.
+import { readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { mainDirOf } from './accounts.js';
+import { tildify } from './paths.js';
+export const SKILL_INSTALL = 'npx skills add Adonis0123/sideby -g';
+/** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
+export function skillVersionOf(text) {
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+    const meta = front && /^metadata:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m.exec(front)?.[1];
+    return (meta && /^[ \t]+version:[ \t]*['"]?([^'"\s]+)/m.exec(meta)?.[1]) || null;
+}
+/**
+ * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
+ * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read
+ * once per Family, so the result for one Family never depends on which others are checked with it. Findings
+ * are general and belong to that Family's Main Account.
+ */
+export async function checkInstalledSkills(home, families, version) {
+    const places = families.flatMap((f) => [
+        { family: f, path: join(mainDirOf(f, home), 'skills', 'sideby', 'SKILL.md') },
+        ...(f.id === 'codex' ? [{ family: f, path: join(home, '.agents', 'skills', 'sideby', 'SKILL.md') }] : []),
+    ]);
+    const seen = new Set();
+    const out = [];
+    for (const { family, path } of places) {
+        let real;
+        let text;
+        try {
+            real = await realpath(path);
+            if (seen.has(`${family.id}\0${real}`))
+                continue;
+            text = await readFile(real, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        seen.add(`${family.id}\0${real}`);
+        const found = skillVersionOf(text);
+        if (found === version)
+            continue;
+        const where = tildify(path, home);
+        out.push({
+            level: 'warn',
+            account: `${family.id}:main`,
+            item: where,
+            code: 'skill.outdated',
+            message: `the sideby skill at ${where} is ${found ? `for sideby ${found}` : 'from before skills had a version'}; this sideby is ${version}`,
+            hint: `update it with \`${SKILL_INSTALL}\`, so agents learn this version's commands`,
+            source: 'core',
+            fixable: false,
+        });
+    }
+    return out;
+}

package/dist/src/core/usage-days.d.ts

@@ -0,0 +1,15 @@
+export interface DailyTokens {
+    /** Local calendar date, `YYYY-MM-DD`. */
+    date: string;
+    totalTokens: number;
+}
+/** Local calendar date of a time, `YYYY-MM-DD`. */
+export declare function localDate(at: number | Date): string;
+/**
+ * `days` buckets ending with the local day of `now`. `add` drops times outside those days, so the buckets can
+ * sum to less than a reader's rolling-window total (the oldest partial day falls outside them).
+ */
+export declare function dailyBuckets(now: Date, days?: number): {
+    daily: DailyTokens[];
+    add(at: number, tokens: number): void;
+};

package/dist/src/core/usage-days.js

@@ -0,0 +1,33 @@
+// Per-day Usage buckets shared by the built-in readers: local calendar dates, oldest first, zero-filled.
+import { USAGE_DAYS } from './quota-levels.js';
+const pad = (n) => String(n).padStart(2, '0');
+/** Local calendar date of a time, `YYYY-MM-DD`. */
+export function localDate(at) {
+    const d = at instanceof Date ? at : new Date(at);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/**
+ * `days` buckets ending with the local day of `now`. `add` drops times outside those days, so the buckets can
+ * sum to less than a reader's rolling-window total (the oldest partial day falls outside them).
+ */
+export function dailyBuckets(now, days = USAGE_DAYS) {
+    const daily = [];
+    const index = new Map();
+    for (let i = days - 1; i >= 0; i--) {
+        // Built from calendar parts, so a daylight-saving day of 23 or 25 hours still yields one entry per date.
+        const date = localDate(new Date(now.getFullYear(), now.getMonth(), now.getDate() - i));
+        const bucket = { date, totalTokens: 0 };
+        daily.push(bucket);
+        index.set(date, bucket);
+    }
+    return {
+        daily,
+        add(at, tokens) {
+            if (!Number.isFinite(at) || tokens <= 0)
+                return;
+            const bucket = index.get(localDate(at));
+            if (bucket)
+                bucket.totalTokens += tokens;
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+/** The sideby package version, read once from package.json (two levels up from src/, three from dist/src/). */
+export declare function packageVersion(): string;
+/**
+ * Identity of the code that is running: the version plus the id `pnpm build` writes to `dist/build.json`, so a
+ * rebuilt or reinstalled package differs even when its version does not. Long-running Panels compare it to
+ * notice new code. From source there is no build file (`<version>+source`). `SIDEBY_BUILD_ID` overrides the
+ * id for tests.
+ */
+export declare function buildId(env?: NodeJS.ProcessEnv): string;

package/dist/src/core/version.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+let cached;
+/** The sideby package version, read once from package.json (two levels up from src/, three from dist/src/). */
+export function packageVersion() {
+    if (cached)
+        return cached;
+    for (const rel of ['../../package.json', '../../../package.json']) {
+        try {
+            const pkg = JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+            if (pkg.name === 'sideby' && pkg.version) {
+                cached = pkg.version;
+                return cached;
+            }
+        }
+        catch {
+            // try the next layout
+        }
+    }
+    cached = '0.0.0';
+    return cached;
+}
+let cachedBuild;
+/**
+ * Identity of the code that is running: the version plus the id `pnpm build` writes to `dist/build.json`, so a
+ * rebuilt or reinstalled package differs even when its version does not. Long-running Panels compare it to
+ * notice new code. From source there is no build file (`<version>+source`). `SIDEBY_BUILD_ID` overrides the
+ * id for tests.
+ */
+export function buildId(env = process.env) {
+    if (env.SIDEBY_BUILD_ID)
+        return `${packageVersion()}+${env.SIDEBY_BUILD_ID}`;
+    if (cachedBuild)
+        return cachedBuild;
+    let id = 'source';
+    try {
+        // dist/src/core/version.js → dist/build.json; from src/ the file does not exist.
+        const data = JSON.parse(readFileSync(new URL('../../build.json', import.meta.url), 'utf8'));
+        if (typeof data.id === 'string' && data.id)
+            id = data.id;
+    }
+    catch {
+        // running from source
+    }
+    cachedBuild = `${packageVersion()}+${id}`;
+    return cachedBuild;
+}

package/dist/src/desktop/app.d.ts

@@ -0,0 +1,60 @@
+import type { Env } from '../types.ts';
+export declare const BUNDLE_ID = "dev.sideby.panel";
+export type AppPlatform = 'darwin' | 'linux';
+/** Runs a helper program; resolves false (never rejects) when it is missing or fails. */
+export type Runner = (cmd: string, args: string[]) => Promise<boolean>;
+export declare const defaultRunner: Runner;
+export interface AppContext {
+    home: string;
+    env: Env;
+    platform: NodeJS.Platform;
+    run?: Runner;
+}
+export interface InstallOptions {
+    /** Absolute path of the Node binary the launcher runs (normally `process.execPath`). */
+    node: string;
+    /** Absolute path of the sideby CLI entry. */
+    entry: string;
+    /** Open this address instead of starting the Panel, for a portal that embeds it. */
+    url?: string;
+    version: string;
+}
+export interface InstallResult {
+    platform: AppPlatform;
+    /** The app bundle (macOS) or the .desktop file (Linux). */
+    path: string;
+    files: string[];
+    mode: 'panel' | 'url';
+    url?: string;
+    node: string;
+    entry: string;
+    updated: boolean;
+    hints: string[];
+}
+export interface UninstallResult {
+    platform: AppPlatform;
+    removed: string[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+}
+/** Checks a `--url` value: an http or https address. */
+export declare function checkAppUrl(url: string): string;
+export interface LauncherSpec {
+    node: string;
+    entry: string;
+    url?: string;
+    platform: AppPlatform;
+    /** XDG directories set when installing, so the app reads the same config and state as the terminal. */
+    xdg: {
+        XDG_CONFIG_HOME?: string;
+        XDG_STATE_HOME?: string;
+    };
+}
+/** The POSIX shell launcher. It records absolute paths and falls back to `sideby` from the login shell. */
+export declare function launcherScript(s: LauncherSpec): string;
+export declare function infoPlist(version: string): string;
+export declare function desktopEntry(launcher: string): string;
+export declare function installApp(ctx: AppContext, opts: InstallOptions): Promise<InstallResult>;
+export declare function uninstallApp(ctx: AppContext): Promise<UninstallResult>;

package/dist/src/desktop/app.js

@@ -0,0 +1,316 @@
+// `sideby app install|uninstall`: a double-clickable launcher for the Panel. macOS gets ~/Applications/sideby.app,
+// Linux a .desktop entry. The launcher runs the recorded Node and sideby entry with `ui --background`, or with
+// `--url` just opens that address. Every file carries APP_MARKER, and uninstall removes only marked files.
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { chmod, mkdir, mkdtemp, open, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { UserError } from '../core/errors.js';
+import { lstatOrNull, writeFileAtomic } from '../core/fs-safe.js';
+import { APP_MARKER, encodeIcns, ICONSET, iconPng, iconSvg } from './icon.js';
+export const BUNDLE_ID = 'dev.sideby.panel';
+const APP_NAME = 'sideby';
+export const defaultRunner = (cmd, args) => new Promise((resolve) => execFile(cmd, args, { timeout: 60_000 }, (err) => resolve(!err)));
+function platformOf(ctx) {
+    if (ctx.platform === 'darwin' || ctx.platform === 'linux')
+        return ctx.platform;
+    throw new UserError(`sideby app supports macOS and Linux; on ${ctx.platform} run \`sideby ui --background\` from a shortcut instead`);
+}
+/** Checks a `--url` value: an http or https address. */
+export function checkAppUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new UserError(`--url must be a full address such as http://localhost:17333/ (got "${url}")`);
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:')
+        throw new UserError(`--url must start with http:// or https:// (got "${url}")`);
+    return u.href;
+}
+const shq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** The POSIX shell launcher. It records absolute paths and falls back to `sideby` from the login shell. */
+export function launcherScript(s) {
+    const opener = s.platform === 'darwin' ? 'open' : 'xdg-open';
+    const alert = s.platform === 'darwin'
+        ? `/usr/bin/osascript -e 'display alert "sideby could not start" message "Run sideby app install again in a terminal. Details: '"$LOG"'"' >/dev/null 2>&1`
+        : `command -v notify-send >/dev/null 2>&1 && notify-send "sideby could not start" "Run sideby app install again in a terminal. Details: $LOG"`;
+    const lines = [
+        '#!/bin/sh',
+        `# ${APP_MARKER}: written by \`sideby app install\`. Run that again after upgrading sideby or Node.`,
+        `NODE=${shq(s.node)}`,
+        `ENTRY=${shq(s.entry)}`,
+        `URL=${shq(s.url ?? '')}`,
+    ];
+    for (const [k, v] of Object.entries(s.xdg))
+        if (v)
+            lines.push(`export ${k}=${shq(v)}`);
+    lines.push(`LOG="\${XDG_STATE_HOME:-$HOME/.local/state}/sideby/launcher.log"`, 'mkdir -p "$(dirname "$LOG")" 2>/dev/null', 'if [ -n "$URL" ]; then', `  exec ${opener} "$URL"`, 'fi', 'if [ -x "$NODE" ] && [ -f "$ENTRY" ]; then', '  "$NODE" "$ENTRY" ui --background >>"$LOG" 2>&1 && exit 0', 'else', '  # The recorded Node or sideby moved (an upgrade, a version manager): ask the login shell for `sideby`.', `  "\${SHELL:-/bin/sh}" -ilc 'sideby ui --background' >>"$LOG" 2>&1 </dev/null && exit 0`, 'fi', alert, 'exit 1', '');
+    return lines.join('\n');
+}
+export function infoPlist(version) {
+    const entries = [
+        ['CFBundleName', APP_NAME],
+        ['CFBundleDisplayName', APP_NAME],
+        ['CFBundleIdentifier', BUNDLE_ID],
+        ['CFBundleExecutable', APP_NAME],
+        ['CFBundleIconFile', 'AppIcon'],
+        ['CFBundlePackageType', 'APPL'],
+        ['CFBundleShortVersionString', version],
+        ['CFBundleVersion', version],
+        ['LSMinimumSystemVersion', '10.13'],
+        ['SidebyInstalledBy', APP_MARKER],
+    ];
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        ...entries.flatMap(([k, v]) => [`  <key>${k}</key>`, `  <string>${xml(v)}</string>`]),
+        '</dict>',
+        '</plist>',
+        '',
+    ].join('\n');
+}
+/** Desktop Entry `Exec` value; refuses characters that would need the spec's double escaping. */
+function execArg(p) {
+    if (/["`$\\%\n\r]/.test(p))
+        throw new UserError(`cannot write a desktop entry for a path with ", \`, $, \\ or %: ${p}`);
+    return `"${p}"`;
+}
+export function desktopEntry(launcher) {
+    return [
+        '[Desktop Entry]',
+        'Type=Application',
+        `Name=${APP_NAME}`,
+        'Comment=Every AI coding account side by side',
+        `Exec=${execArg(launcher)}`,
+        `Icon=${APP_NAME}`,
+        'Terminal=false',
+        'Categories=Development;Utility;',
+        `X-Sideby-Installed-By=${APP_MARKER}`,
+        '',
+    ].join('\n');
+}
+function layout(ctx, platform) {
+    if (platform === 'darwin') {
+        const app = join(ctx.home, 'Applications', `${APP_NAME}.app`);
+        return { entries: [app], primary: app };
+    }
+    const dataHome = ctx.env.XDG_DATA_HOME && isAbsolute(ctx.env.XDG_DATA_HOME)
+        ? ctx.env.XDG_DATA_HOME
+        : join(ctx.home, '.local', 'share');
+    const linux = {
+        desktop: join(dataHome, 'applications', `${APP_NAME}.desktop`),
+        launcher: join(dataHome, APP_NAME, 'sideby-launcher'),
+        svg: join(dataHome, 'icons', 'hicolor', 'scalable', 'apps', `${APP_NAME}.svg`),
+        png: join(dataHome, 'icons', 'hicolor', '256x256', 'apps', `${APP_NAME}.png`),
+    };
+    return { entries: Object.values(linux), primary: linux.desktop, linux };
+}
+/** How each kind of install target carries APP_MARKER; anything that merely mentions it elsewhere is foreign. */
+function markerTest(entry) {
+    if (entry.endsWith('.app'))
+        return (d) => new RegExp(`<key>SidebyInstalledBy</key>\\s*<string>${APP_MARKER}</string>`).test(d.toString('utf8'));
+    if (entry.endsWith('.desktop'))
+        return (d) => new RegExp(`^X-Sideby-Installed-By=${APP_MARKER}$`, 'm').test(d.toString('utf8'));
+    if (entry.endsWith('.svg'))
+        return (d) => d.includes(`<!-- ${APP_MARKER} -->`);
+    if (entry.endsWith('.png'))
+        return (d) => d.includes(`tEXtSoftware\0${APP_MARKER}`, 0, 'latin1');
+    // The launcher script: the marker comment is its second line.
+    return (d) => d.toString('utf8').split('\n', 2)[1]?.startsWith(`# ${APP_MARKER}: `) === true;
+}
+/** Reads a regular file without following a symlink, however the path changed since it was checked. */
+async function readNoFollow(path) {
+    const fh = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return await fh.readFile();
+    }
+    finally {
+        await fh.close();
+    }
+}
+const LINK = 'is a symbolic link';
+const NOT_OURS = 'exists and was not created by `sideby app install`';
+/**
+ * Whether `entry` is something `sideby app install` wrote. Never follows a symlink: a link at the target, or
+ * (for the macOS bundle) anywhere among the bundle's own paths, is foreign even when it leads to a marked file,
+ * so install never writes through it and uninstall never removes it.
+ */
+async function ownership(entry) {
+    const top = await lstatOrNull(entry);
+    if (!top)
+        return { state: 'absent' };
+    const foreign = (path, reason) => ({ state: 'foreign', path, reason });
+    if (top.isSymbolicLink())
+        return foreign(entry, LINK);
+    let markerPath = entry;
+    if (entry.endsWith('.app')) {
+        if (!top.isDirectory())
+            return foreign(entry, 'is not a directory');
+        const parts = [
+            ['Contents', 'dir', true],
+            ['Contents/Info.plist', 'file', true],
+            ['Contents/MacOS', 'dir', false],
+            [`Contents/MacOS/${APP_NAME}`, 'file', false],
+            ['Contents/Resources', 'dir', false],
+            ['Contents/Resources/AppIcon.icns', 'file', false],
+        ];
+        for (const [rel, kind, required] of parts) {
+            const p = join(entry, rel);
+            const st = await lstatOrNull(p);
+            if (!st) {
+                if (required)
+                    return foreign(entry, NOT_OURS);
+                continue;
+            }
+            if (st.isSymbolicLink())
+                return foreign(p, LINK);
+            if (kind === 'dir' ? !st.isDirectory() : !st.isFile())
+                return foreign(p, kind === 'dir' ? 'is not a directory' : 'is not a regular file');
+        }
+        markerPath = join(entry, 'Contents', 'Info.plist');
+    }
+    else if (!top.isFile())
+        return foreign(entry, 'is not a regular file');
+    let data;
+    try {
+        data = await readNoFollow(markerPath);
+    }
+    catch {
+        return foreign(entry, NOT_OURS);
+    }
+    return markerTest(entry)(data) ? { state: 'ours' } : foreign(entry, NOT_OURS);
+}
+/** Refuses to replace anything at `entry` that `sideby app install` did not write; true when it is ours. */
+async function assertOwned(entry, verb) {
+    const o = await ownership(entry);
+    if (o.state === 'absent')
+        return false;
+    if (o.state === 'ours')
+        return true;
+    throw new UserError(`${o.path} ${o.reason}; move it away first, then ${verb} again`);
+}
+export async function installApp(ctx, opts) {
+    const platform = platformOf(ctx);
+    const run = ctx.run ?? defaultRunner;
+    if (!isAbsolute(opts.node) || !isAbsolute(opts.entry))
+        throw new UserError('node and the sideby entry must be absolute paths');
+    const url = opts.url === undefined ? undefined : checkAppUrl(opts.url);
+    const l = layout(ctx, platform);
+    let updated = false;
+    for (const e of l.entries)
+        if (await assertOwned(e, 'install'))
+            updated = true;
+    const xdg = {};
+    for (const k of ['XDG_CONFIG_HOME', 'XDG_STATE_HOME']) {
+        const v = ctx.env[k];
+        if (v && isAbsolute(v))
+            xdg[k] = v;
+    }
+    const script = launcherScript({
+        node: opts.node,
+        entry: opts.entry,
+        platform,
+        xdg,
+        ...(url ? { url } : {}),
+    });
+    const files = [];
+    const hints = [];
+    if (platform === 'darwin') {
+        const app = l.primary;
+        await mkdir(dirname(app), { recursive: true });
+        // Build next to the target, then swap it in, so a failed install never leaves half a bundle.
+        const tmp = await mkdtemp(join(dirname(app), '.sideby.app.tmp-'));
+        try {
+            await chmod(tmp, 0o755);
+            const contents = join(tmp, 'Contents');
+            await mkdir(join(contents, 'MacOS'), { recursive: true });
+            await mkdir(join(contents, 'Resources'), { recursive: true });
+            await writeFile(join(contents, 'Info.plist'), infoPlist(opts.version));
+            await writeFile(join(contents, 'MacOS', APP_NAME), script, { mode: 0o755 });
+            await chmod(join(contents, 'MacOS', APP_NAME), 0o755);
+            const iconset = join(tmp, 'AppIcon.iconset');
+            await mkdir(iconset);
+            const pngs = new Map();
+            for (const { name, size } of ICONSET) {
+                const png = iconPng(size);
+                pngs.set(name, png);
+                await writeFile(join(iconset, name), png);
+            }
+            const icns = join(contents, 'Resources', 'AppIcon.icns');
+            if (!(await run('iconutil', ['-c', 'icns', iconset, '-o', icns])))
+                await writeFile(icns, encodeIcns(pngs));
+            await rm(iconset, { recursive: true, force: true });
+            await rm(app, { recursive: true, force: true });
+            await rename(tmp, app);
+        }
+        catch (err) {
+            await rm(tmp, { recursive: true, force: true });
+            throw err;
+        }
+        // Ask Launch Services to pick up the new icon and bundle; harmless when it is not there.
+        await run('/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister', ['-f', app]);
+        files.push(app, join(app, 'Contents', 'Info.plist'), join(app, 'Contents', 'MacOS', APP_NAME), join(app, 'Contents', 'Resources', 'AppIcon.icns'));
+        hints.push('Open it from ~/Applications or Spotlight ("sideby"), or drag it to the Dock.');
+    }
+    else {
+        const p = l.linux;
+        // Temp file in the same directory, then rename: never writes through a link, never leaves half a file.
+        const write = async (path, data, mode = 0o644) => {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFileAtomic(path, data, mode);
+            files.push(path);
+        };
+        await write(p.launcher, script, 0o755);
+        await write(p.svg, iconSvg());
+        await write(p.png, iconPng(256));
+        await write(p.desktop, desktopEntry(p.launcher));
+        await run('update-desktop-database', [dirname(p.desktop)]);
+        hints.push('Find "sideby" in your application menu.');
+    }
+    if (url)
+        hints.push(`The app opens ${url}.`);
+    else
+        hints.push('The app starts the panel in the background and opens it; stop the panel with `sideby ui --stop`.', 'Run `sideby app install` again after upgrading sideby or Node, so the app starts the new version.');
+    if (/[/\\]_npx[/\\]/.test(opts.entry))
+        hints.push('sideby runs from the npx cache, which npm may clear; install it with `npm i -g sideby` and run this again.');
+    return {
+        platform,
+        path: l.primary,
+        files,
+        mode: url ? 'url' : 'panel',
+        ...(url ? { url } : {}),
+        node: opts.node,
+        entry: opts.entry,
+        updated,
+        hints,
+    };
+}
+export async function uninstallApp(ctx) {
+    const platform = platformOf(ctx);
+    const l = layout(ctx, platform);
+    const removed = [];
+    const skipped = [];
+    for (const e of l.entries) {
+        const o = await ownership(e);
+        if (o.state === 'absent')
+            continue;
+        if (o.state === 'foreign') {
+            const reason = o.reason === NOT_OURS ? 'not created by `sideby app install`' : `${o.path} ${o.reason}`;
+            skipped.push({ path: e, reason: `${reason}; left in place` });
+            continue;
+        }
+        await rm(e, { recursive: e.endsWith('.app'), force: true });
+        removed.push(e);
+    }
+    if (platform === 'linux' && removed.length) {
+        // The launcher's own directory, only when nothing else is left in it.
+        await rmdir(dirname(l.linux.launcher)).catch(() => { });
+        await (ctx.run ?? defaultRunner)('update-desktop-database', [dirname(l.primary)]);
+    }
+    return { platform, removed, skipped };
+}

package/dist/src/desktop/icon.d.ts

@@ -0,0 +1,16 @@
+/** Text stored in every generated file, so `sideby app uninstall` deletes only what it wrote. */
+export declare const APP_MARKER = "sideby-app-install";
+/** RGBA pixels (straight alpha) of the icon at `size`×`size`. */
+export declare function renderIcon(size: number): Uint8Array;
+/** Encodes straight-alpha RGBA pixels as a PNG with a `Software` text chunk holding APP_MARKER. */
+export declare function encodePng(width: number, height: number, rgba: Uint8Array): Buffer;
+export declare const iconPng: (size: number) => Buffer;
+/** The macOS `.iconset` file names and their pixel sizes, 16 to 1024. */
+export declare const ICONSET: readonly {
+    name: string;
+    size: number;
+}[];
+/** Builds an `.icns` file directly from PNGs; used when `iconutil` is not available. */
+export declare function encodeIcns(pngs: ReadonlyMap<string, Buffer>): Buffer;
+/** The same mark as an SVG (1024-unit canvas), for Linux icon themes. */
+export declare function iconSvg(): string;