sideby 0.0.0-stage → 0.2.1

package/dist/src/plugins/bus.js

@@ -0,0 +1,84 @@
+export const HOOK_TIMEOUT_MS = {
+    'launch.before': 30_000,
+    'account.create.before': 10_000,
+    'account.created': 30_000,
+    'doctor.check': 10_000,
+};
+/** Error thrown by a hook, labelled with the Plugin that raised it. */
+export class HookError extends Error {
+    plugin;
+    aborted;
+    constructor(plugin, message, aborted) {
+        super(`[${plugin}] ${message}`);
+        this.plugin = plugin;
+        this.aborted = aborted;
+    }
+}
+/** Thrown by `api.abort()` to stop a Launch or a new Account on purpose. */
+export class HookAbort extends Error {
+}
+export class HookBus {
+    entries = new Map();
+    timeouts;
+    constructor(timeouts = {}) {
+        this.timeouts = { ...HOOK_TIMEOUT_MS, ...timeouts };
+    }
+    add(plugin, event, filter, handler) {
+        const list = this.entries.get(event) ?? [];
+        list.push({ plugin, filter, handler: handler });
+        this.entries.set(event, list);
+    }
+    count(event) {
+        return this.entries.get(event)?.length ?? 0;
+    }
+    /**
+     * Runs matching handlers in registration order. Each gets the event's timeout.
+     * Returns per-plugin results; the first failure stops the chain and is thrown as HookError.
+     */
+    async run(event, family, ctx) {
+        const out = [];
+        for (const e of this.entries.get(event) ?? []) {
+            if (e.filter.family && e.filter.family !== family)
+                continue;
+            const result = await this.invoke(e, event, ctx);
+            out.push({ plugin: e.plugin, result });
+        }
+        return out;
+    }
+    /** Like `run`, but a failing handler is reported and the others still run (used by Doctor). */
+    async runIsolated(event, family, ctx) {
+        const out = [];
+        for (const e of this.entries.get(event) ?? []) {
+            if (e.filter.family && e.filter.family !== family)
+                continue;
+            try {
+                out.push({ plugin: e.plugin, result: await this.invoke(e, event, ctx) });
+            }
+            catch (err) {
+                out.push({ plugin: e.plugin, error: err });
+            }
+        }
+        return out;
+    }
+    async invoke(e, event, ctx) {
+        const ms = this.timeouts[event];
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new HookError(e.plugin, `${event} timed out after ${ms / 1000}s`, false)), ms);
+            // Kept referenced: a hook stuck on a bare Promise holds no handle, and an unref'd timer would let
+            // the process exit silently mid-operation. `finally` clears it, so it never delays a normal exit.
+        });
+        try {
+            return await Promise.race([Promise.resolve().then(() => e.handler(ctx)), timeout]);
+        }
+        catch (err) {
+            if (err instanceof HookError)
+                throw err;
+            const aborted = err instanceof HookAbort;
+            throw new HookError(e.plugin, err?.message ?? String(err), aborted);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/src/plugins/loader.d.ts

@@ -0,0 +1,58 @@
+import type { Config } from '../core/config.ts';
+import type { FamilyDef, Plugin } from '../types.ts';
+import { type HookBus } from './bus.ts';
+export interface PluginManifest {
+    name: string;
+    version: string;
+    description?: string;
+    main?: string;
+    userConfig?: Record<string, {
+        type?: string;
+        default?: unknown;
+        title?: string;
+        description?: string;
+    }>;
+}
+export interface LoadedPlugin {
+    name: string;
+    version: string;
+    source: 'builtin' | string;
+    description?: string;
+    families: string[];
+    config: Record<string, unknown>;
+}
+export interface PluginLoadError {
+    /** Plugin directory, or the plugin name when known. */
+    where: string;
+    message: string;
+}
+export interface BuiltinPlugin {
+    plugin: Plugin;
+    version: string;
+    description: string;
+    /** Built-in Plugins that stay off unless the config enables them. */
+    defaultEnabled: boolean;
+}
+export interface LoadResult {
+    plugins: LoadedPlugin[];
+    errors: PluginLoadError[];
+    families: Map<string, FamilyDef>;
+    familyOwner: Map<string, string>;
+}
+/** Rejects plugin files other users could have written: plugins run with the user's full permissions. */
+export declare function checkTrusted(path: string): Promise<string | null>;
+/**
+ * checkTrusted for a directory and everything under it, at any depth; symlinks are judged by their
+ * targets and each real directory is visited once, so a link cycle cannot loop forever.
+ */
+export declare function checkTrustedTree(root: string, seen?: Set<string>): Promise<string | null>;
+export declare const MAX_LOGO_PATH = 20000;
+/** Why a Family logo is unusable, or null when it is fine. The Panel draws it with DOM APIs, never as markup. */
+export declare function logoProblem(logo: unknown): string | null;
+export declare function loadPlugins(opts: {
+    builtins: BuiltinPlugin[];
+    config: Config;
+    bus: HookBus;
+    userPluginsDir: string;
+    home: string;
+}): Promise<LoadResult>;

package/dist/src/plugins/loader.js

@@ -0,0 +1,250 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { writeFileAtomic } from '../core/fs-safe.js';
+import { expandUserPath } from '../core/paths.js';
+import { HOOK_TIMEOUT_MS, HookAbort } from './bus.js';
+/** Rejects plugin files other users could have written: plugins run with the user's full permissions. */
+export async function checkTrusted(path) {
+    const st = await stat(path);
+    const uid = process.getuid?.();
+    if (uid !== undefined && st.uid !== uid)
+        return `${path} is owned by another user`;
+    if ((st.mode & 0o022) !== 0)
+        return `${path} is writable by group or others; run \`chmod go-w "${path}"\``;
+    return null;
+}
+/**
+ * checkTrusted for a directory and everything under it, at any depth; symlinks are judged by their
+ * targets and each real directory is visited once, so a link cycle cannot loop forever.
+ */
+export async function checkTrustedTree(root, seen = new Set()) {
+    let st;
+    try {
+        st = await stat(root);
+    }
+    catch {
+        return `${root} is missing or a dangling link`;
+    }
+    const own = await checkTrusted(root);
+    if (own)
+        return own;
+    if (!st.isDirectory())
+        return null;
+    const real = await realpath(root);
+    if (seen.has(real))
+        return null;
+    seen.add(real);
+    for (const e of await readdir(root)) {
+        const problem = await checkTrustedTree(join(root, e), seen);
+        if (problem)
+            return problem;
+    }
+    return null;
+}
+/** SVG path data only: commands, numbers and separators, so a logo cannot carry markup or script. */
+const LOGO_PATH_RE = /^[MmLlHhVvCcSsQqTtAaZz0-9eE.,+\-\s]+$/;
+const LOGO_COLOR_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+export const MAX_LOGO_PATH = 20_000;
+/** Why a Family logo is unusable, or null when it is fine. The Panel draws it with DOM APIs, never as markup. */
+export function logoProblem(logo) {
+    if (typeof logo !== 'object' || logo === null || Array.isArray(logo))
+        return 'logo must be an object';
+    const { path, color, title, fillRule } = logo;
+    if (typeof path !== 'string' || !path.trim())
+        return 'logo.path must be a non-empty string';
+    if (path.length > MAX_LOGO_PATH)
+        return `logo.path is over ${MAX_LOGO_PATH} characters`;
+    if (!LOGO_PATH_RE.test(path))
+        return 'logo.path may hold only SVG path commands, numbers, spaces, commas, dots, "+" and "-"';
+    if (color !== undefined && (typeof color !== 'string' || !LOGO_COLOR_RE.test(color)))
+        return 'logo.color must be a hex color such as #D97757';
+    if (title !== undefined && (typeof title !== 'string' || title.length > 80))
+        return 'logo.title must be a string of at most 80 characters';
+    if (fillRule !== undefined && fillRule !== 'nonzero' && fillRule !== 'evenodd')
+        return 'logo.fillRule must be "nonzero" or "evenodd"';
+    return null;
+}
+/** Only the known logo fields, so nothing else a Plugin put on the object reaches the Panel. */
+function cleanLogo(logo) {
+    return {
+        path: logo.path,
+        ...(logo.color ? { color: logo.color } : {}),
+        ...(logo.title ? { title: logo.title } : {}),
+        ...(logo.fillRule ? { fillRule: logo.fillRule } : {}),
+    };
+}
+function settingsFor(config, name, manifest) {
+    const defaults = {};
+    for (const [k, v] of Object.entries(manifest?.userConfig ?? {}))
+        if ('default' in v)
+            defaults[k] = v.default;
+    return { ...defaults, ...(config.plugins?.[name] ?? {}) };
+}
+async function register(plugin, bus, result, source, settings) {
+    if (!plugin || typeof plugin.name !== 'string' || typeof plugin.register !== 'function')
+        throw new Error(`${source}: default export must be { name, register(api) }`);
+    // Stage everything the Plugin registers; commit only after register() succeeds, so a Plugin that fails
+    // halfway leaves no Family and no hook behind.
+    const stagedFamilies = [];
+    const stagedHooks = [];
+    const stagedErrors = [];
+    const api = {
+        family(def) {
+            // The id becomes part of account refs and shell function names.
+            if (!/^[a-z][a-z0-9-]{0,31}$/.test(def.id))
+                throw new Error(`family id "${def.id}" must be lowercase letters, digits or "-", starting with a letter`);
+            const owner = result.familyOwner.get(def.id);
+            if (owner)
+                throw new Error(`family ${def.id} is already provided by ${owner}`);
+            if (stagedFamilies.some((f) => f.id === def.id))
+                throw new Error(`family ${def.id} is registered twice`);
+            // A bad logo costs only the logo: the Family still loads and the Panel shows its initials.
+            if (def.logo !== undefined) {
+                const problem = logoProblem(def.logo);
+                if (problem) {
+                    stagedErrors.push(`family ${def.id}: ${problem}; showing its initials instead`);
+                    const { logo: _dropped, ...rest } = def;
+                    stagedFamilies.push(rest);
+                    return;
+                }
+                stagedFamilies.push({ ...def, logo: cleanLogo(def.logo) });
+                return;
+            }
+            stagedFamilies.push(def);
+        },
+        on(event, a, b) {
+            const [filter, handler] = typeof a === 'function' ? [{}, a] : [a, b];
+            if (!Object.hasOwn(HOOK_TIMEOUT_MS, event))
+                throw new Error(`unknown hook event ${event}`);
+            // Each hook sees its own Plugin's settings; env and args stay shared so mutations reach the Launch.
+            const withConfig = ((ctx) => handler({ ...ctx, config: settings }));
+            stagedHooks.push(() => bus.add(plugin.name, event, filter, withConfig));
+        },
+        abort: (message) => new HookAbort(message),
+        fs: {
+            async writeFileAtomic(path, data, mode) {
+                await writeFileAtomic(path, data, mode);
+            },
+        },
+    };
+    await plugin.register(api);
+    for (const def of stagedFamilies) {
+        result.families.set(def.id, def);
+        result.familyOwner.set(def.id, plugin.name);
+    }
+    for (const add of stagedHooks)
+        add();
+    for (const message of stagedErrors)
+        result.errors.push({ where: plugin.name, message });
+    return stagedFamilies.map((f) => f.id);
+}
+async function candidateDirs(config, userPluginsDir, home, errors) {
+    const dirs = [];
+    let entries = [];
+    try {
+        entries = (await readdir(userPluginsDir)).sort();
+    }
+    catch {
+        // no user plugins directory
+    }
+    for (const e of entries) {
+        if (e.startsWith('.'))
+            continue;
+        const p = join(userPluginsDir, e);
+        try {
+            if ((await stat(p)).isDirectory())
+                dirs.push(p);
+        }
+        catch (err) {
+            errors.push({
+                where: p,
+                message: `cannot read plugin directory: ${err.code ?? 'error'}`,
+            });
+        }
+    }
+    for (const raw of config.pluginDirs ?? []) {
+        const p = expandUserPath(raw, home);
+        if (!p)
+            errors.push({ where: raw, message: 'pluginDirs entries must be absolute or start with ~/' });
+        else
+            dirs.push(p);
+    }
+    return dirs;
+}
+export async function loadPlugins(opts) {
+    const result = { plugins: [], errors: [], families: new Map(), familyOwner: new Map() };
+    const seen = new Set();
+    for (const b of opts.builtins) {
+        const settings = settingsFor(opts.config, b.plugin.name);
+        const enabled = settings.enabled === undefined ? b.defaultEnabled : settings.enabled === true;
+        if (!enabled)
+            continue;
+        try {
+            const families = await register(b.plugin, opts.bus, result, 'builtin', settings);
+            seen.add(b.plugin.name);
+            result.plugins.push({
+                name: b.plugin.name,
+                version: b.version,
+                source: 'builtin',
+                description: b.description,
+                families,
+                config: settings,
+            });
+        }
+        catch (err) {
+            result.errors.push({ where: b.plugin.name, message: err.message });
+        }
+    }
+    for (const dir of await candidateDirs(opts.config, opts.userPluginsDir, opts.home, result.errors)) {
+        try {
+            const manifestPath = join(dir, 'plugin.json');
+            const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+            if (typeof manifest.name !== 'string' || !manifest.name)
+                throw new Error('plugin.json needs a "name"');
+            const settings = settingsFor(opts.config, manifest.name, manifest);
+            if (settings.enabled === false)
+                continue;
+            if (seen.has(manifest.name))
+                throw new Error(`a plugin named ${manifest.name} is already loaded`);
+            const entry = join(dir, manifest.main ?? 'index.ts');
+            // The entry can import any file next to it, so every file in the plugin directory must be trusted,
+            // and the entry itself must be one of those files (`main: "../x.ts"` must not escape the check).
+            const problem = await checkTrustedTree(dir);
+            if (problem)
+                throw new Error(`not loaded: ${problem}`);
+            const [dirReal, entryReal] = await Promise.all([realpath(dir), realpath(entry).catch(() => null)]);
+            if (!entryReal)
+                throw new Error(`not loaded: entry ${entry} is missing`);
+            if (!entryReal.startsWith(`${dirReal}${sep}`))
+                throw new Error(`not loaded: entry ${entry} is outside the plugin directory`);
+            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href)));
+            if (!mod.default)
+                throw new Error(`${entry} has no default export`);
+            if (mod.default.name !== manifest.name)
+                throw new Error(`plugin.json name ${manifest.name} does not match the exported name ${mod.default.name}`);
+            const families = await register(mod.default, opts.bus, result, dir, settings);
+            seen.add(manifest.name);
+            result.plugins.push({
+                name: manifest.name,
+                version: manifest.version ?? '0.0.0',
+                source: dir,
+                ...(manifest.description ? { description: manifest.description } : {}),
+                families,
+                config: settings,
+            });
+        }
+        catch (err) {
+            result.errors.push({ where: dir, message: err.message });
+        }
+    }
+    return result;
+}

package/dist/src/quota/claude-statusline.d.ts

@@ -0,0 +1,28 @@
+import type { QuotaSetup } from '../types.ts';
+export interface StatuslineBackup {
+    /** Real path that was changed (the symlink target when settings.json is a link). */
+    file: string;
+    originalBase64: string;
+    originalHash: string;
+    wrappedHash: string;
+    appliedAt: string;
+}
+export declare function backupFile(stateDir: string): string;
+export declare function mainSettingsFile(home: string): string;
+export declare function isWrapped(command: unknown): boolean;
+export declare function wrapCommand(original: string | undefined): string;
+export declare const claudeStatusline: QuotaSetup;
+/**
+ * Hides values of secret-looking JSON keys in a diff line. settings.json often keeps API keys in `env`,
+ * right next to `statusLine`, so context lines could otherwise print them.
+ */
+export declare function redactLine(line: string): string;
+/**
+ * Diff of the statusLine object only. The rest of settings.json never enters a diff: it often holds API keys
+ * (for example in `env`), in shapes no line-based redaction can reliably catch.
+ */
+export declare function statusLineDiff(before: unknown, after: unknown, file: string): string;
+/** Shows the statusLine fields sideby touches as they are; any other value becomes "<redacted>". */
+export declare function redactStatusLine(v: unknown): unknown;
+/** Minimal unified diff with 3 lines of context; empty when the texts are equal. Secret-looking values are redacted. */
+export declare function unifiedDiff(oldText: string, newText: string, file: string, context?: number): string;