sideby 0.0.0-stage → 0.1.0

package/dist/src/cli/json-schemas.js

@@ -0,0 +1,224 @@
+// JSON Schemas for every `--json` output. Additive changes keep schemaVersion 1; removals, renames or
+// meaning changes bump it (spec §3.9). `pnpm schemas` writes these to schemas/*.json.
+import { Type } from 'typebox';
+import { ConfigSchema } from '../core/config.js';
+const Str = Type.String();
+const Level = Type.Union([Type.Literal('ok'), Type.Literal('warn'), Type.Literal('fail')]);
+const Kind = Type.Union([Type.Literal('subscription'), Type.Literal('api')]);
+const Version = Type.Literal(1);
+const AppPlatform = Type.Union([Type.Literal('darwin'), Type.Literal('linux')]);
+const Account = Type.Object({
+    family: Str,
+    name: Str,
+    ref: Str,
+    dir: Str,
+    isMain: Type.Boolean(),
+    kind: Kind,
+    secretFile: Type.Optional(Str),
+});
+const AccountStatus = Type.Intersect([
+    Account,
+    Type.Object({
+        familyTitle: Str,
+        hostInstalled: Type.Boolean(),
+        login: Type.Union([
+            Type.Literal('logged-in'),
+            Type.Literal('logged-out'),
+            Type.Literal('unknown'),
+            Type.Literal('not-needed'),
+        ]),
+        model: Type.Optional(Str),
+        identity: Type.Optional(Type.Object({ email: Type.Optional(Str), org: Type.Optional(Str) }, {
+            description: "Who the account is signed in as, from the host's login file: identity fields only, never a token (ADR-0003).",
+        })),
+        problems: Type.Optional(Type.Array(Str)),
+    }),
+]);
+const FamilyInfo = Type.Object({
+    id: Str,
+    title: Str,
+    bin: Str,
+    installUrl: Str,
+    installed: Type.Boolean(),
+    plugin: Str,
+});
+const PluginError = Type.Object({ where: Str, message: Str });
+const Finding = Type.Object({
+    level: Level,
+    account: Str,
+    item: Str,
+    code: Str,
+    message: Str,
+    hint: Type.Optional(Str),
+    source: Str,
+    fixable: Type.Boolean(),
+});
+const QuotaWindow = Type.Object({
+    label: Str,
+    windowMinutes: Type.Number(),
+    usedPercent: Type.Number(),
+    resetsAt: Str,
+});
+const Quota = Type.Union([
+    Type.Object({
+        status: Type.Literal('ok'),
+        windows: Type.Array(QuotaWindow),
+        observedAt: Str,
+        source: Str,
+        plan: Type.Optional(Str),
+    }),
+    Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
+]);
+const Usage = Type.Union([
+    Type.Object({
+        status: Type.Literal('ok'),
+        days: Type.Number(),
+        sessions: Type.Number(),
+        inputTokens: Type.Number(),
+        outputTokens: Type.Number(),
+        cacheReadTokens: Type.Number(),
+        cacheWriteTokens: Type.Number(),
+        totalTokens: Type.Number(),
+        daily: Type.Optional(Type.Array(Type.Object({ date: Str, totalTokens: Type.Number() }), {
+            description: 'Tokens per local day (YYYY-MM-DD), oldest first, days without records as 0.',
+        })),
+        lastActivityAt: Type.Optional(Str),
+    }),
+    Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
+]);
+const QuotaSetupPlan = Type.Object({
+    status: Type.Union([Type.Literal('enabled'), Type.Literal('ready'), Type.Literal('blocked')]),
+    file: Str,
+    diff: Str,
+    message: Str,
+});
+const ShellInitFiles = Type.Array(Type.Object({
+    shell: Type.Union([Type.Literal('zsh'), Type.Literal('bash')]),
+    path: Str,
+    ok: Type.Boolean(),
+    action: Type.Optional(Type.Union([Type.Literal('written'), Type.Literal('unchanged')])),
+    message: Type.Optional(Str),
+}), { description: 'One entry per config `shellInitFile`, rewritten after the change.' });
+export const OUTPUT_SCHEMAS = {
+    list: Type.Object({
+        schemaVersion: Version,
+        families: Type.Array(FamilyInfo),
+        accounts: Type.Array(AccountStatus),
+        pluginErrors: Type.Array(PluginError),
+    }, { title: 'sideby list --json' }),
+    doctor: Type.Object({
+        schemaVersion: Version,
+        status: Type.Union([Type.Literal('ok'), Type.Literal('issues')]),
+        accounts: Type.Array(Type.Object({
+            ref: Str,
+            family: Str,
+            name: Str,
+            kind: Kind,
+            dir: Str,
+            shared: Type.Object({ ok: Type.Number(), total: Type.Number() }),
+            backups: Type.Number(),
+            findings: Type.Array(Finding),
+        })),
+        general: Type.Array(Finding),
+        fixes: Type.Array(Type.Object({ account: Str, item: Str, code: Str, ok: Type.Boolean(), message: Str })),
+    }, { title: 'sideby doctor --json' }),
+    quota: Type.Object({
+        schemaVersion: Version,
+        accounts: Type.Array(Type.Object({ ref: Str, kind: Kind, quota: Quota, usage: Usage })),
+    }, { title: 'sideby quota --json' }),
+    next: Type.Object({
+        schemaVersion: Version,
+        family: Str,
+        pick: Type.Union([Str, Type.Null()], {
+            description: 'The recommended account; null when none can be used now (exit code 1).',
+        }),
+        accounts: Type.Array(Type.Object({
+            ref: Str,
+            kind: Kind,
+            state: Type.Union([
+                Type.Literal('ready'),
+                Type.Literal('unknown'),
+                Type.Literal('api'),
+                Type.Literal('full'),
+                Type.Literal('logged-out'),
+            ], {
+                description: 'ready and unknown can be picked; api only with --include-api; full and logged-out never.',
+            }),
+            pressure: Type.Union([Type.Number(), Type.Null()], {
+                description: 'Used percent of the fullest window not reset yet; null without quota.',
+            }),
+            resetsAt: Type.Optional(Type.String({ description: 'For full: when its last full window resets.' })),
+            observedAt: Type.Optional(Type.String({ description: "When the account's quota was recorded (its last session)." })),
+        }), { description: 'Every account of the family, best first.' }),
+        hasQuota: Type.Boolean({
+            description: 'False when no account has quota data: the pick is then a guess, and `sideby next` does not start it (exit 1).',
+        }),
+        earliestReset: Type.Optional(Type.Object({ ref: Str, at: Str }, {
+            description: 'Set when nothing can be picked and some accounts are full: the first to come back.',
+        })),
+    }, { title: 'sideby next --json' }),
+    'quota-setup': Type.Object({ schemaVersion: Version, family: Str, applied: Type.Boolean(), plan: QuotaSetupPlan }, { title: 'sideby quota setup --json' }),
+    'quota-teardown': Type.Object({ schemaVersion: Version, family: Str, ok: Type.Boolean(), message: Str, diff: Type.Optional(Str) }, { title: 'sideby quota teardown --json' }),
+    new: Type.Object({
+        schemaVersion: Version,
+        ok: Type.Boolean(),
+        account: Account,
+        steps: Type.Array(Type.Object({ item: Str, action: Str, ok: Type.Boolean(), message: Type.Optional(Str) })),
+        hookErrors: Type.Array(Type.Object({ plugin: Str, message: Str })),
+        nextSteps: Type.Array(Str),
+        alias: Type.Optional(Type.Object({ name: Str, added: Type.Boolean(), message: Type.Optional(Str) }, { description: 'The `--alias` short command; `added: false` means the Account exists without it.' })),
+        shellInitFiles: Type.Optional(ShellInitFiles),
+    }, { title: 'sideby new --json' }),
+    alias: Type.Object({
+        schemaVersion: Version,
+        ok: Type.Boolean({ description: 'False when a config `shellInitFile` was not rewritten.' }),
+        alias: Str,
+        status: Type.Union([
+            Type.Literal('added'),
+            Type.Literal('exists'),
+            Type.Literal('removed'),
+            Type.Literal('absent'),
+        ]),
+        account: Type.Optional(Str),
+        args: Type.Optional(Type.Array(Str, { description: 'Host arguments `sideby run <alias>` adds.' })),
+        shellInitFiles: Type.Optional(ShellInitFiles),
+    }, { title: 'sideby alias add|rm --json' }),
+    plugins: Type.Object({
+        schemaVersion: Version,
+        plugins: Type.Array(Type.Object({
+            name: Str,
+            version: Str,
+            source: Str,
+            description: Type.Optional(Str),
+            families: Type.Array(Str),
+            configKeys: Type.Array(Str),
+        })),
+        errors: Type.Array(PluginError),
+    }, { title: 'sideby plugins --json' }),
+    'app-install': Type.Object({
+        schemaVersion: Version,
+        platform: AppPlatform,
+        path: Str,
+        files: Type.Array(Str),
+        mode: Type.Union([Type.Literal('panel'), Type.Literal('url')]),
+        url: Type.Optional(Str),
+        node: Str,
+        entry: Str,
+        updated: Type.Boolean(),
+        hints: Type.Array(Str),
+    }, { title: 'sideby app install --json' }),
+    'app-uninstall': Type.Object({
+        schemaVersion: Version,
+        platform: AppPlatform,
+        removed: Type.Array(Str),
+        skipped: Type.Array(Type.Object({ path: Str, reason: Str })),
+    }, { title: 'sideby app uninstall --json' }),
+    error: Type.Object({
+        schemaVersion: Version,
+        error: Type.String({ description: 'What went wrong and what to do next.' }),
+        code: Type.String({
+            description: '`usage` for a malformed command line (exit 2), a reason such as `no-quota-source` or `alias-invalid`, or `error`.',
+        }),
+    }, { title: 'sideby error --json' }),
+    config: ConfigSchema,
+};

package/dist/src/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;

package/dist/src/cli/main.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// Entry point. Keeps imports lazy so `statusline-tap`, which Claude Code runs on every refresh, starts fast.
+import { realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const MIN_NODE = [22, 18];
+const HELP = `sideby — run every AI coding account side by side
+
+Usage:
+  sideby                              list accounts (same as \`sideby list\`)
+  sideby run <account> [-- args]      start the host CLI for one account
+  sideby new <family> <name> [--api] [--alias <short>]
+                                      create an account (families: claude, codex, grok, pi);
+                                      --alias also adds a short command such as cc008
+  sideby alias add <short> <account> [-- args]
+                                      add a short command, optionally with host arguments
+                                      (sideby alias add pi-kimi pi:main -- --model kimi-coding/k3)
+  sideby alias rm <short>             remove a short command
+  sideby login <account>              sign in to an account
+  sideby next <family> [--dry-run] [--include-api] [-- args]
+                                      recommend the account with the most quota left (claude, codex)
+                                      and start it; --dry-run only recommends
+  sideby doctor [target] [--fix] [--force]
+                                      check shared items and permissions; --fix repairs safe issues
+  sideby quota [account]              quota and 7-day token usage
+  sideby quota setup claude [--yes]   turn on Claude quota (shows the change first)
+  sideby quota teardown claude        undo it, restoring the original file
+  sideby ui [--port n] [--no-open]    open the local panel
+  sideby ui --background              same, without a terminal: keeps running after this command exits
+  sideby ui --stop                    stop the background panel
+  sideby app install [--url <url>]    add a sideby app that opens the panel (macOS, Linux)
+  sideby app uninstall                remove that app
+  sideby shell-init zsh|bash          print shell functions, e.g. eval "$(sideby shell-init zsh)"
+  sideby shell-init [zsh|bash] --write
+                                      rewrite the config's shellInitFile with them
+  sideby plugins                      list loaded plugins and load errors
+
+Options:
+  --json        machine-readable output (list, new, next, alias, doctor, quota, plugins, app)
+  -h, --help    show this help
+  -v, --version show the version
+
+An <account> is <family>:<name> (claude:work) or just <name> when it is unique.`;
+function nodeTooOld() {
+    const [maj = 0, min = 0] = process.versions.node.split('.').map(Number);
+    return maj < MIN_NODE[0] || (maj === MIN_NODE[0] && min < MIN_NODE[1]);
+}
+const COMMANDS = {
+    list: { flags: ['json'] },
+    run: { flags: [] },
+    login: { flags: [] },
+    next: { flags: ['dry-run', 'include-api', 'json'] },
+    new: { flags: ['api', 'json'], valued: ['alias'] },
+    alias: { flags: ['json'] },
+    doctor: { flags: ['fix', 'force', 'json'] },
+    quota: { flags: ['json', 'yes'] },
+    ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
+    app: { flags: ['json'], valued: ['url'] },
+    'shell-init': { flags: ['write'] },
+    plugins: { flags: ['json'] },
+};
+export async function main(argv) {
+    const [first, ...rest] = argv;
+    if (first === 'statusline-tap') {
+        const { runStatuslineTap } = await import('../quota/statusline-tap.js');
+        return runStatuslineTap(rest, process.env, process.stdin, process.stdout);
+    }
+    if (first === '-v' || first === '--version' || first === 'version') {
+        const { packageVersion } = await import('../core/version.js');
+        console.log(packageVersion());
+        return 0;
+    }
+    if (first === '-h' || first === '--help' || first === 'help') {
+        console.log(HELP);
+        return 0;
+    }
+    if (nodeTooOld()) {
+        console.error(`sideby needs Node ${MIN_NODE.join('.')} or newer (you have ${process.versions.node}). Upgrade: https://nodejs.org`);
+        return 1;
+    }
+    const cmd = first === undefined || first.startsWith('--') ? 'list' : first;
+    const args = first === undefined || first.startsWith('--') ? argv : rest;
+    const spec = COMMANDS[cmd];
+    const io = { out: (s) => console.log(s), err: (s) => console.error(s) };
+    const { parseArgs, UsageError } = await import('./args.js');
+    // Only sideby's own options count: arguments after `--` belong to the host.
+    const own = args.includes('--') ? args.slice(0, args.indexOf('--')) : args;
+    const wantsJson = Boolean(spec?.flags.includes('json')) && own.includes('--json');
+    try {
+        if (!spec)
+            throw new UsageError(`unknown command "${cmd}"; run \`sideby --help\``);
+        // `run` passes everything after the account through to the host, with or without `--`.
+        let parsed;
+        if (cmd === 'run') {
+            const sep = args.indexOf('--');
+            const head = sep === -1 ? args : args.slice(0, sep);
+            const [ref, ...more] = head;
+            parsed = {
+                positionals: ref ? [ref] : [],
+                flags: new Map(),
+                rest: [...more, ...(sep === -1 ? [] : args.slice(sep + 1))],
+            };
+            if (ref === '-h' || ref === '--help')
+                parsed.flags.set('help', true);
+        }
+        else {
+            try {
+                parsed = parseArgs(args, [...spec.flags, 'help'], spec.valued ?? []);
+            }
+            catch (err) {
+                // `alias add` takes Host arguments too; the usual mistake is leaving out the `--` before them.
+                if (cmd === 'alias' && err instanceof UsageError && err.message.startsWith('unknown option'))
+                    throw new UsageError(`${err.message}; put Host arguments after \`--\`, for example: sideby alias add pi-kimi pi:main -- --model kimi-coding/k3`);
+                if (cmd === 'next' && err instanceof UsageError && err.message.startsWith('unknown option'))
+                    throw new UsageError(`${err.message}; put Host arguments after \`--\`, for example: sideby next claude -- --model opus`);
+                throw err;
+            }
+        }
+        if (parsed.flags.has('help')) {
+            console.log(HELP);
+            return 0;
+        }
+        const cmds = await import('./commands.js');
+        switch (cmd) {
+            case 'list':
+                return await cmds.cmdList(parsed, io);
+            case 'run':
+                return await cmds.cmdRun(parsed, io, 'run');
+            case 'login':
+                return await cmds.cmdRun(parsed, io, 'login');
+            case 'next':
+                return await cmds.cmdNext(parsed, io);
+            case 'new':
+                return await cmds.cmdNew(parsed, io);
+            case 'alias':
+                return await cmds.cmdAlias(parsed, io);
+            case 'doctor':
+                return await cmds.cmdDoctor(parsed, io);
+            case 'quota':
+                return await cmds.cmdQuota(parsed, io);
+            case 'ui':
+                return await cmds.cmdUi(parsed, io);
+            case 'app':
+                return await cmds.cmdApp(parsed, io);
+            case 'shell-init':
+                return await cmds.cmdShellInit(parsed, io);
+            case 'plugins':
+                return await cmds.cmdPlugins(parsed, io);
+        }
+        return 2;
+    }
+    catch (err) {
+        const usage = err instanceof UsageError;
+        const message = err instanceof Error ? err.message : String(err);
+        if (wantsJson) {
+            const { UserError } = await import('../core/errors.js');
+            const code = usage ? 'usage' : err instanceof UserError && err.code ? err.code : 'error';
+            console.log(JSON.stringify({ schemaVersion: 1, error: message, code }, null, 2));
+        }
+        else
+            console.error(`sideby: ${message}`);
+        if (!usage && process.env.SIDEBY_DEBUG && err instanceof Error)
+            console.error(err.stack);
+        return usage ? 2 : 1;
+    }
+}
+// Run when executed directly, also through symlinks (npm's bin shim, a user alias like `sb`).
+function isEntry() {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    try {
+        return (pathToFileURL(realpathSync(arg)).href ===
+            pathToFileURL(realpathSync(fileURLToPath(import.meta.url))).href);
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntry()) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (err) => {
+        console.error(`sideby: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    });
+}

package/dist/src/cli/schemas.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/cli/schemas.js

@@ -0,0 +1,16 @@
+// Writes schemas/*.json from OUTPUT_SCHEMAS. CI regenerates and fails if the result differs from git.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { OUTPUT_SCHEMAS } from './json-schemas.js';
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'schemas');
+await mkdir(root, { recursive: true });
+for (const [name, schema] of Object.entries(OUTPUT_SCHEMAS)) {
+    const doc = {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        $id: `sideby/${name}.json`,
+        ...schema,
+    };
+    await writeFile(join(root, `${name}.json`), `${JSON.stringify(doc, null, 2)}\n`);
+}
+console.log(`wrote ${Object.keys(OUTPUT_SCHEMAS).length} schemas to schemas/`);

package/dist/src/core/account-name.d.ts

@@ -0,0 +1,2 @@
+/** Valid Account names. A leaf module with no I/O so the status line tap can import it cheaply. */
+export declare const ACCOUNT_NAME: RegExp;

package/dist/src/core/account-name.js

@@ -0,0 +1,2 @@
+/** Valid Account names. A leaf module with no I/O so the status line tap can import it cheaply. */
+export const ACCOUNT_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;

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

@@ -0,0 +1,18 @@
+import type { Account, FamilyDef } from '../types.ts';
+import { ACCOUNT_NAME } from './account-name.ts';
+import { UserError } from './errors.ts';
+export { ACCOUNT_NAME };
+export declare function looksLikeBackup(name: string): boolean;
+export declare function mainDirOf(family: FamilyDef, home: string): string;
+export declare function accountDirOf(family: FamilyDef, home: string, name: string): string;
+/**
+ * The Account for this Family and name, read from its directory: the one place an Account is built.
+ * Whether it is an API Account follows the Secret File on disk (and the Family's secretFileMeansApi).
+ */
+export declare function accountAt(family: FamilyDef, home: string, name: string): Promise<Account>;
+/** Discovers the Main Account (if its directory exists) and every `<prefix><name><suffix>` directory in HOME. */
+export declare function discoverAccounts(family: FamilyDef, home: string, ignore?: ReadonlySet<string>): Promise<Account[]>;
+export declare class AccountRefError extends UserError {
+}
+/** Resolves `<family>:<name>`, an alias from the config, or a name unique across Families. */
+export declare function resolveRef(ref: string, accounts: readonly Account[], aliases?: Readonly<Record<string, string>>): Account;

package/dist/src/core/accounts.js

@@ -0,0 +1,116 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ACCOUNT_NAME } from './account-name.js';
+import { UserError } from './errors.js';
+import { lstatOrNull, statOrNull } from './fs-safe.js';
+export { ACCOUNT_NAME };
+const BACKUP_LIKE = /(bak|backup|old|tmp)/;
+export function looksLikeBackup(name) {
+    return BACKUP_LIKE.test(name);
+}
+export function mainDirOf(family, home) {
+    return join(home, family.layout.main);
+}
+export function accountDirOf(family, home, name) {
+    return name === 'main' ? mainDirOf(family, home) : join(home, family.layout.account.replace('<name>', name));
+}
+function splitLayout(family) {
+    const [first, ...rest] = family.layout.account.split('/');
+    const at = first.indexOf('<name>');
+    if (at === -1)
+        throw new Error(`family ${family.id}: layout.account must contain <name> in its first segment`);
+    return { prefix: first.slice(0, at), suffix: first.slice(at + '<name>'.length), rest: rest.join('/') };
+}
+/**
+ * The Account for this Family and name, read from its directory: the one place an Account is built.
+ * Whether it is an API Account follows the Secret File on disk (and the Family's secretFileMeansApi).
+ */
+export async function accountAt(family, home, name) {
+    const dir = accountDirOf(family, home, name);
+    const secretFile = join(dir, 'proxy.env');
+    const hasSecret = (await lstatOrNull(secretFile)) !== null;
+    return {
+        family: family.id,
+        name,
+        ref: `${family.id}:${name}`,
+        dir,
+        isMain: name === 'main',
+        kind: hasSecret && family.secretFileMeansApi !== false ? 'api' : 'subscription',
+        ...(hasSecret ? { secretFile } : {}),
+    };
+}
+/**
+ * A directory that merely matches the name pattern (for example `~/.claude-code-router`, another tool's
+ * config) is not an Account: it must hold a Secret File or one of the Family's Shared Items, or be empty.
+ */
+async function looksLikeAccount(family, dir) {
+    for (const p of ['proxy.env', ...(family.markers ?? family.sharedItems.map((i) => i.path))])
+        if (await lstatOrNull(join(dir, p)))
+            return true;
+    // A freshly created Account may have nothing to share yet; another tool's directory is never empty.
+    try {
+        return (await readdir(dir)).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Discovers the Main Account (if its directory exists) and every `<prefix><name><suffix>` directory in HOME. */
+export async function discoverAccounts(family, home, ignore = new Set()) {
+    const out = [];
+    const main = mainDirOf(family, home);
+    if ((await statOrNull(main))?.isDirectory())
+        out.push(await accountAt(family, home, 'main'));
+    const { prefix, suffix, rest } = splitLayout(family);
+    let entries = [];
+    try {
+        entries = await readdir(home);
+    }
+    catch {
+        return out;
+    }
+    const names = [];
+    for (const e of entries) {
+        if (!e.startsWith(prefix) || !e.endsWith(suffix))
+            continue;
+        const name = e.slice(prefix.length, e.length - suffix.length);
+        if (!ACCOUNT_NAME.test(name) || name === 'main')
+            continue;
+        if (ignore.has(`${family.id}:${name}`))
+            continue;
+        // A non-main Account must be a real directory at every level: a symlinked `~/.claude-work` pointing at
+        // `~/.claude` would make every repair write into the Main Account. Only the Main Account may be a link.
+        const top = join(home, e);
+        const dir = rest ? join(top, rest) : top;
+        if (!(await lstatOrNull(top))?.isDirectory())
+            continue;
+        if (rest && !(await lstatOrNull(dir))?.isDirectory())
+            continue;
+        if (!(await looksLikeAccount(family, dir)))
+            continue;
+        names.push(name);
+    }
+    names.sort();
+    for (const name of names)
+        out.push(await accountAt(family, home, name));
+    return out;
+}
+export class AccountRefError extends UserError {
+}
+/** Resolves `<family>:<name>`, an alias from the config, or a name unique across Families. */
+export function resolveRef(ref, accounts, aliases = {}) {
+    if (!ref.includes(':') && Object.hasOwn(aliases, ref))
+        return resolveRef(aliases[ref], accounts);
+    if (ref.includes(':')) {
+        const hit = accounts.find((a) => a.ref === ref);
+        if (hit)
+            return hit;
+        throw new AccountRefError(`no account ${ref}; run \`sideby list\` to see accounts or \`sideby new\` to create one`);
+    }
+    const hits = accounts.filter((a) => a.name === ref);
+    if (hits.length === 1)
+        return hits[0];
+    if (hits.length === 0)
+        throw new AccountRefError(`no account named ${ref}; run \`sideby list\` to see accounts`);
+    throw new AccountRefError(`${ref} is ambiguous; use one of: ${hits.map((a) => a.ref).join(', ')}`);
+}

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

@@ -0,0 +1,60 @@
+import { type Static, Type } from 'typebox';
+import { UserError } from './errors.ts';
+export declare const ALIAS_NAME: RegExp;
+/** Shell keywords and builtins an alias must not shadow (`command() { command sideby … }` would recurse). */
+export declare const RESERVED_ALIASES: Set<string>;
+export declare function aliasProblem(alias: string): string | null;
+/** One `aliases` value: an Account ref, or a ref plus Host arguments that only `sideby run` adds (ADR-0005). */
+declare const AliasSchema: Type.TUnion<[Type.TString, Type.TObject<{
+    account: Type.TString;
+    args: Type.TOptional<Type.TArray<Type.TString>>;
+}>]>;
+export type AliasValue = Static<typeof AliasSchema>;
+/** The Account ref an Alias starts. */
+export declare const aliasAccount: (value: AliasValue) => string;
+/** The Host arguments an Alias adds to `sideby run`; none for a plain ref. */
+export declare const aliasArgs: (value: AliasValue | undefined) => string[];
+/** `aliases` as alias → Account ref, for lookups that ignore the arguments. */
+export declare function aliasRefs(aliases: Readonly<Record<string, AliasValue>> | undefined): Record<string, string>;
+export declare const ConfigSchema: Type.TObject<{
+    $schema: Type.TOptional<Type.TString>;
+    accounts: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+        args: Type.TOptional<Type.TArray<Type.TString>>;
+    }>>>;
+    aliases: Type.TOptional<Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TObject<{
+        account: Type.TString;
+        args: Type.TOptional<Type.TArray<Type.TString>>;
+    }>]>>>;
+    ignore: Type.TOptional<Type.TArray<Type.TString>>;
+    pluginDirs: Type.TOptional<Type.TArray<Type.TString>>;
+    plugins: Type.TOptional<Type.TRecord<"^.*$", Type.TRecord<"^.*$", Type.TUnknown>>>;
+    extraSharedItems: Type.TOptional<Type.TRecord<"^.*$", Type.TArray<Type.TObject<{
+        path: Type.TString;
+        mode: Type.TUnion<Type.TLiteral<"copy" | "info" | "link" | "link-or-copy" | "link-or-local" | "local" | "local-if-api">[]>;
+        noSymlink: Type.TOptional<Type.TBoolean>;
+        credential: Type.TOptional<Type.TBoolean>;
+    }>>>>;
+    shellInitFile: Type.TOptional<Type.TObject<{
+        zsh: Type.TOptional<Type.TString>;
+        bash: Type.TOptional<Type.TString>;
+    }>>;
+}>;
+export type Config = Static<typeof ConfigSchema>;
+export declare class ConfigError extends UserError {
+}
+export declare function loadConfig(file: string): Promise<Config>;
+/**
+ * Adds `alias → ref` to the config file's `aliases`, as `{ account, args }` when `args` is not empty (see
+ * `editConfigAliases` for how the file is written). Refuses an invalid alias, or one that already starts another
+ * Account or the same Account with other arguments. Returns the aliases now in the file.
+ */
+export declare function addConfigAlias(file: string, alias: string, ref: string, args?: readonly string[]): Promise<{
+    status: 'added' | 'exists';
+    aliases: Record<string, AliasValue>;
+}>;
+/** Removes `alias` from the config file's `aliases`; `absent` when it was not there (nothing is written then). */
+export declare function removeConfigAlias(file: string, alias: string): Promise<{
+    status: 'removed' | 'absent';
+    aliases: Record<string, AliasValue>;
+}>;
+export {};