sideby 0.0.0-stage → 0.1.0

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;

package/dist/src/desktop/icon.js

@@ -0,0 +1,174 @@
+// The sideby mark drawn without dependencies: the Panel header's logo (a dark rounded tile with a light disc
+// split into two halves, offset along the diagonal, the second at 55% opacity) rasterised with analytic
+// antialiasing and encoded as PNG, SVG or ICNS.
+import { deflateSync } from 'node:zlib';
+/** Text stored in every generated file, so `sideby app uninstall` deletes only what it wrote. */
+export const APP_MARKER = 'sideby-app-install';
+// Geometry in the Panel's 40-unit logo box (page.ts: .logo 40×40, radius 10; halves of radius 10.5 centred at
+// 18.5,18.5 facing left and 21.5,21.5 facing right, so they sit 3 apart and mirror through the centre).
+const TILE = { size: 40, radius: 10, color: [0x15, 0x17, 0x1c] };
+const MARK = { color: [0xf5, 0xf6, 0xf8], opacities: [1, 0.55] };
+const HALVES = [
+    { cx: 18.5, cy: 18.5, r: 10.5, side: -1 },
+    { cx: 21.5, cy: 21.5, r: 10.5, side: 1 },
+];
+// The tile sits on the macOS icon grid: 824 of 1024 units, centred.
+const GRID = { canvas: 1024, tile: 824 };
+function shapes(size) {
+    const tilePx = (size * GRID.tile) / GRID.canvas;
+    const off = (size - tilePx) / 2;
+    const u = tilePx / TILE.size;
+    return {
+        tile: { x: off, y: off, w: tilePx, h: tilePx, r: TILE.radius * u },
+        halves: HALVES.map((h) => ({ cx: off + h.cx * u, cy: off + h.cy * u, r: h.r * u, side: h.side })),
+    };
+}
+/** Signed distance from (px, py) to a rounded rectangle; negative inside. */
+function roundedRectDistance(px, py, s) {
+    const hx = s.w / 2;
+    const hy = s.h / 2;
+    const qx = Math.abs(px - (s.x + hx)) - (hx - s.r);
+    const qy = Math.abs(py - (s.y + hy)) - (hy - s.r);
+    const outside = Math.hypot(Math.max(qx, 0), Math.max(qy, 0));
+    return outside + Math.min(Math.max(qx, qy), 0) - s.r;
+}
+/** Signed distance from (px, py) to a half disc: the disc intersected with the half-plane on its side. */
+function halfDistance(px, py, h) {
+    return Math.max(Math.hypot(px - h.cx, py - h.cy) - h.r, (px - h.cx) * -h.side);
+}
+/** RGBA pixels (straight alpha) of the icon at `size`×`size`. */
+export function renderIcon(size) {
+    const { tile, halves } = shapes(size);
+    const layers = [
+        { dist: (x, y) => roundedRectDistance(x, y, tile), color: TILE.color, opacity: 1 },
+        ...halves.map((h, i) => ({
+            dist: (x, y) => halfDistance(x, y, h),
+            color: MARK.color,
+            opacity: MARK.opacities[i],
+        })),
+    ];
+    const px = new Uint8Array(size * size * 4);
+    for (let y = 0; y < size; y++)
+        for (let x = 0; x < size; x++) {
+            // Premultiplied "over" compositing; coverage from the distance at the pixel centre.
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            for (const l of layers) {
+                const cover = Math.min(1, Math.max(0, 0.5 - l.dist(x + 0.5, y + 0.5)));
+                const la = cover * l.opacity;
+                if (la === 0)
+                    continue;
+                r = (l.color[0] / 255) * la + r * (1 - la);
+                g = (l.color[1] / 255) * la + g * (1 - la);
+                b = (l.color[2] / 255) * la + b * (1 - la);
+                a = la + a * (1 - la);
+            }
+            const i = (y * size + x) * 4;
+            if (a > 0) {
+                px[i] = Math.round((r / a) * 255);
+                px[i + 1] = Math.round((g / a) * 255);
+                px[i + 2] = Math.round((b / a) * 255);
+                px[i + 3] = Math.round(a * 255);
+            }
+        }
+    return px;
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (const byte of buf)
+        c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(data.length, 0);
+    head.write(type, 4, 'latin1');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])), 0);
+    return Buffer.concat([head, data, crc]);
+}
+/** Encodes straight-alpha RGBA pixels as a PNG with a `Software` text chunk holding APP_MARKER. */
+export function encodePng(width, height, rgba) {
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr.set([8, 6, 0, 0, 0], 8); // 8-bit RGBA, no interlace
+    const raw = Buffer.alloc((width * 4 + 1) * height);
+    for (let y = 0; y < height; y++) {
+        raw[y * (width * 4 + 1)] = 0; // filter: none
+        raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1);
+    }
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk('IHDR', ihdr),
+        chunk('tEXt', Buffer.from(`Software\0${APP_MARKER}`, 'latin1')),
+        chunk('IDAT', deflateSync(raw, { level: 9 })),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+}
+export const iconPng = (size) => encodePng(size, size, renderIcon(size));
+/** The macOS `.iconset` file names and their pixel sizes, 16 to 1024. */
+export const ICONSET = [16, 32, 128, 256, 512].flatMap((s) => [
+    { name: `icon_${s}x${s}.png`, size: s },
+    { name: `icon_${s}x${s}@2x.png`, size: s * 2 },
+]);
+// ICNS element types for PNG data, by pixel size (`@2x` variants have their own types).
+const ICNS_TYPES = {
+    'icon_16x16.png': 'icp4',
+    'icon_16x16@2x.png': 'ic11',
+    'icon_32x32.png': 'icp5',
+    'icon_32x32@2x.png': 'ic12',
+    'icon_128x128.png': 'ic07',
+    'icon_128x128@2x.png': 'ic13',
+    'icon_256x256.png': 'ic08',
+    'icon_256x256@2x.png': 'ic14',
+    'icon_512x512.png': 'ic09',
+    'icon_512x512@2x.png': 'ic10',
+};
+/** Builds an `.icns` file directly from PNGs; used when `iconutil` is not available. */
+export function encodeIcns(pngs) {
+    const parts = [];
+    for (const { name } of ICONSET) {
+        const data = pngs.get(name);
+        if (!data)
+            continue;
+        const head = Buffer.alloc(8);
+        head.write(ICNS_TYPES[name], 0, 'latin1');
+        head.writeUInt32BE(data.length + 8, 4);
+        parts.push(head, data);
+    }
+    const body = Buffer.concat(parts);
+    const head = Buffer.alloc(8);
+    head.write('icns', 0, 'latin1');
+    head.writeUInt32BE(body.length + 8, 4);
+    return Buffer.concat([head, body]);
+}
+/** The same mark as an SVG (1024-unit canvas), for Linux icon themes. */
+export function iconSvg() {
+    const { tile, halves } = shapes(GRID.canvas);
+    const hex = (c) => `#${c.map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+    const opacityAttr = (opacity) => (opacity === 1 ? '' : ` fill-opacity="${opacity}"`);
+    const rect = (s, fill) => `  <rect x="${s.x}" y="${s.y}" width="${s.w}" height="${s.h}" rx="${s.r}" fill="${fill}"/>`;
+    // From the top of the cut to its bottom, bulging to the half's side.
+    const half = (h, fill, opacity) => `  <path d="M${h.cx} ${h.cy - h.r}A${h.r} ${h.r} 0 0 ${h.side > 0 ? 1 : 0} ${h.cx} ${h.cy + h.r}Z" fill="${fill}"${opacityAttr(opacity)}/>`;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${GRID.canvas} ${GRID.canvas}" width="${GRID.canvas}" height="${GRID.canvas}">`,
+        `  <!-- ${APP_MARKER} -->`,
+        rect(tile, hex(TILE.color)),
+        ...halves.map((h, i) => half(h, hex(MARK.color), MARK.opacities[i])),
+        '</svg>',
+        '',
+    ].join('\n');
+}

package/dist/src/families/claude/index.d.ts

@@ -0,0 +1,10 @@
+import type { Account, FamilyDef, Plugin } from '../../types.ts';
+/** The Main Account keeps `.claude.json` in HOME; other Accounts keep it inside their directory. */
+export declare function claudeJsonOf(account: Account): string;
+/**
+ * `oauthAccount.emailAddress` and `organizationName` from `.claude.json`; nothing else is kept. The organization a
+ * personal sign-in gets by default ("<name>'s Organization") says nothing new, so it is left out.
+ */
+export declare function claudeIdentity(account: Account): Promise<import("../../types.ts").AccountIdentity | undefined>;
+export declare const claudeFamily: FamilyDef;
+export declare const claudePlugin: Plugin;