sideby 0.0.0-stage → 0.2.1

package/dist/src/core/accounts.js

@@ -0,0 +1,131 @@
+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(', ')}`);
+}
+/** Alias names per Account ref, sorted. An alias whose target matches no Account is left out. */
+export function aliasesByAccount(aliases, accounts) {
+    const out = new Map();
+    for (const [alias, target] of Object.entries(aliases ?? {})) {
+        let ref;
+        try {
+            ref = resolveRef(target, accounts).ref;
+        }
+        catch {
+            continue;
+        }
+        out.set(ref, [...(out.get(ref) ?? []), alias].sort());
+    }
+    return out;
+}

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

@@ -0,0 +1,61 @@
+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>;
+    }>>>>;
+    resumeRouting: 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 {};

package/dist/src/core/config.js

@@ -0,0 +1,184 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { Type } from 'typebox';
+import { Value } from 'typebox/value';
+import { UserError } from './errors.js';
+import { lstatOrNull, parseJsonSafely, realpathOrNull, sha256, writeIfUnchanged } from './fs-safe.js';
+import { SHARE_MODES } from './share-mode-names.js';
+const SharedItemSchema = Type.Object({
+    path: Type.String({ minLength: 1, pattern: '^(?!/)(?!.*(^|/)\\.\\.(/|$)).+$' }),
+    // json-key needs a key and a main-side path, which the config does not offer.
+    mode: Type.Union(SHARE_MODES.filter((m) => m !== 'json-key').map((m) => Type.Literal(m))),
+    noSymlink: Type.Optional(Type.Boolean()),
+    credential: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+export const ALIAS_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/** Shell keywords and builtins an alias must not shadow (`command() { command sideby … }` would recurse). */
+export const RESERVED_ALIASES = new Set('alias bg bind break builtin case cd command compgen complete continue declare dirs disown do done echo elif else enable esac eval exec exit export false fc fg fi for function getopts hash help history if in jobs kill let local logout popd printf pushd pwd read readonly return select set shift shopt source suspend test then time times trap true type typeset ulimit umask unalias unset until wait while sideby'.split(' '));
+export function aliasProblem(alias) {
+    if (!ALIAS_NAME.test(alias))
+        return `must match ${ALIAS_NAME.source}`;
+    if (RESERVED_ALIASES.has(alias))
+        return 'is a shell keyword, builtin or sideby itself';
+    return null;
+}
+/** One `aliases` value: an Account ref, or a ref plus Host arguments that only `sideby run` adds (ADR-0005). */
+const AliasSchema = Type.Union([
+    Type.String(),
+    Type.Object({
+        account: Type.String({ pattern: '^[^:]+:.+$', description: 'The Account ref, `<family>:<name>`.' }),
+        args: Type.Optional(Type.Array(Type.String(), {
+            description: 'Host arguments `sideby run <alias>` adds after the Account `args`, before the user’s.',
+        })),
+    }, { additionalProperties: false }),
+]);
+/** The Account ref an Alias starts. */
+export const aliasAccount = (value) => (typeof value === 'string' ? value : value.account);
+/** The Host arguments an Alias adds to `sideby run`; none for a plain ref. */
+export const aliasArgs = (value) => typeof value === 'object' ? [...(value.args ?? [])] : [];
+/** `aliases` as alias → Account ref, for lookups that ignore the arguments. */
+export function aliasRefs(aliases) {
+    return Object.fromEntries(Object.entries(aliases ?? {}).map(([name, v]) => [name, aliasAccount(v)]));
+}
+const sameAlias = (a, b) => aliasAccount(a) === aliasAccount(b) && JSON.stringify(aliasArgs(a)) === JSON.stringify(aliasArgs(b));
+const describeAlias = (v) => {
+    const args = aliasArgs(v);
+    return args.length ? `${aliasAccount(v)} with ${args.join(' ')}` : aliasAccount(v);
+};
+export const ConfigSchema = Type.Object({
+    $schema: Type.Optional(Type.String()),
+    accounts: Type.Optional(Type.Record(Type.String(), Type.Object({ args: Type.Optional(Type.Array(Type.String())) }, { additionalProperties: false }), { description: 'Per-Account settings keyed by `<family>:<name>`.' })),
+    aliases: Type.Optional(Type.Record(Type.String({ pattern: '^[A-Za-z_][A-Za-z0-9_-]*$' }), AliasSchema, {
+        description: 'Short shell function names created by `sideby shell-init`, mapped to an Account ref or to `{ account, args }`.',
+    })),
+    ignore: Type.Optional(Type.Array(Type.String(), { description: 'Account refs that are not Accounts.' })),
+    pluginDirs: Type.Optional(Type.Array(Type.String(), { description: 'Absolute or `~/` paths of Plugin directories.' })),
+    plugins: Type.Optional(Type.Record(Type.String(), Type.Record(Type.String(), Type.Unknown()), {
+        description: 'Per-Plugin settings; `enabled: false` turns a Plugin off.',
+    })),
+    extraSharedItems: Type.Optional(Type.Record(Type.String(), Type.Array(SharedItemSchema))),
+    resumeRouting: Type.Optional(Type.Boolean({
+        description: 'Make `sideby shell-init` also define Host-named functions (`claude`, `codex`, `grok`) that resume a session by id in the Account that holds it. Off by default.',
+    })),
+    shellInitFile: Type.Optional(Type.Object({
+        zsh: Type.Optional(Type.String({ minLength: 1 })),
+        bash: Type.Optional(Type.String({ minLength: 1 })),
+    }, {
+        additionalProperties: false,
+        description: 'Absolute or `~/` paths of files sideby rewrites with the `sideby shell-init <shell>` output whenever it adds an Account or an alias; source the file from your shell rc.',
+    })),
+}, { additionalProperties: false, title: 'sideby config' });
+export class ConfigError extends UserError {
+}
+export async function loadConfig(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return {};
+        throw new ConfigError(`cannot read ${file}: ${err.message}`);
+    }
+    let data;
+    try {
+        data = parseJsonSafely(raw, file);
+    }
+    catch {
+        throw new ConfigError(`${file} is not valid JSON; fix the syntax or delete the file`);
+    }
+    if (!Value.Check(ConfigSchema, data)) {
+        const first = [...Value.Errors(ConfigSchema, data)][0];
+        const where = first?.instancePath || '/';
+        throw new ConfigError(`${file}: ${where} ${first?.message ?? 'is invalid'}; see schemas/config.json`);
+    }
+    // TypeBox does not enforce key patterns on records; alias names become shell function names.
+    for (const alias of Object.keys(data.aliases ?? {})) {
+        const problem = aliasProblem(alias);
+        if (problem)
+            throw new ConfigError(`${file}: alias "${alias}" ${problem} (it becomes a shell function name)`);
+    }
+    return data;
+}
+/** Where the config file is read and written: the target of a link (a dotfiles manager may link it). */
+async function configTarget(file) {
+    return (await lstatOrNull(file))?.isSymbolicLink() ? ((await realpathOrNull(file)) ?? file) : file;
+}
+/**
+ * Re-reads the config file, lets `edit` change its `aliases`, and writes the result: every other key and their
+ * order kept (with `$schema`), 2-space JSON with a trailing newline, atomically, keeping the file's mode (0600 for
+ * a new file). Refuses, without writing, a file that is not valid JSON or not a valid config, or one that changed
+ * while sideby wrote it. `edit` returns null to leave the file alone. `retry` names what to do again after a fix.
+ */
+async function editConfigAliases(file, retry, edit) {
+    const target = await configTarget(file);
+    let raw = null;
+    try {
+        raw = await readFile(target, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw new ConfigError(`cannot read ${file}: ${err.message}`);
+    }
+    let data = {};
+    if (raw !== null) {
+        let parsed;
+        try {
+            parsed = parseJsonSafely(raw, file);
+        }
+        catch {
+            throw new ConfigError(`${file} is not valid JSON; nothing was changed. Fix the syntax and ${retry} again`);
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            throw new ConfigError(`${file} is not a JSON object; nothing was changed. Fix it and ${retry} again`);
+        if (!Value.Check(ConfigSchema, parsed))
+            throw new ConfigError(`${file} does not match schemas/config.json; nothing was changed. Run \`sideby list\` to see why`);
+        data = parsed;
+    }
+    const current = (data.aliases ?? {});
+    const aliases = edit(current);
+    if (!aliases)
+        return current;
+    // A new file gets the schema link editors use for completion; an existing file keeps its keys in order.
+    const next = raw === null ? { $schema: 'https://unpkg.com/sideby/schemas/config.json', aliases } : { ...data, aliases };
+    const st = raw === null ? null : await lstatOrNull(target);
+    if (raw === null)
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const written = await writeIfUnchanged(target, raw === null ? null : sha256(raw), `${JSON.stringify(next, null, 2)}\n`, st ? st.mode & 0o777 : 0o600);
+    if (!written)
+        throw new ConfigError(`${file} changed while sideby was writing it; nothing was changed. Try again`);
+    return aliases;
+}
+/**
+ * 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 async function addConfigAlias(file, alias, ref, args = []) {
+    const problem = aliasProblem(alias);
+    if (problem)
+        throw new ConfigError(`alias "${alias}" ${problem} (it becomes a shell function name)`);
+    const value = args.length ? { account: ref, args: [...args] } : ref;
+    let status = 'added';
+    const aliases = await editConfigAliases(file, 'add the alias', (current) => {
+        if (!Object.hasOwn(current, alias))
+            return { ...current, [alias]: value };
+        if (!sameAlias(current[alias], value))
+            throw new ConfigError(`alias "${alias}" already starts ${describeAlias(current[alias])}; pick another name, or remove it first with \`sideby alias rm ${alias}\``);
+        status = 'exists';
+        return null;
+    });
+    return { status, aliases };
+}
+/** Removes `alias` from the config file's `aliases`; `absent` when it was not there (nothing is written then). */
+export async function removeConfigAlias(file, alias) {
+    let status = 'absent';
+    const aliases = await editConfigAliases(file, 'remove the alias', (current) => {
+        if (!Object.hasOwn(current, alias))
+            return null;
+        status = 'removed';
+        const { [alias]: _gone, ...rest } = current;
+        return rest;
+    });
+    return { status, aliases };
+}

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

@@ -0,0 +1,30 @@
+import { type HookBus } from '../plugins/bus.ts';
+import type { Account, FamilyDef } from '../types.ts';
+import { UserError } from './errors.ts';
+export interface CreateStep {
+    item: string;
+    action: 'linked' | 'copied' | 'written' | 'skipped';
+    ok: boolean;
+    message?: string;
+}
+export interface CreateResult {
+    account: Account;
+    steps: CreateStep[];
+    hookErrors: {
+        plugin: string;
+        message: string;
+    }[];
+    nextSteps: string[];
+    ok: boolean;
+}
+export declare class CreateError extends UserError {
+}
+export declare function createAccount(opts: {
+    family: FamilyDef;
+    name: string;
+    api: boolean;
+    home: string;
+    bus: HookBus;
+    /** The Family's existing Accounts, for `account.create.before`. */
+    accounts?: Account[];
+}): Promise<CreateResult>;

package/dist/src/core/create.js

@@ -0,0 +1,126 @@
+import { mkdir, readFile, symlink } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { HookError } from '../plugins/bus.js';
+import { ACCOUNT_NAME, accountAt, accountDirOf, mainDirOf } from './accounts.js';
+import { UserError } from './errors.js';
+import { assertInside, lstatOrNull, parseJsonSafely, replaceWithCopy, statOrNull, writeFileAtomic, } from './fs-safe.js';
+import { secretFileTemplate } from './secret-file.js';
+import { itemPaths } from './share-modes.js';
+export class CreateError extends UserError {
+}
+function actionFor(item, api) {
+    switch (item.mode) {
+        case 'info':
+            return 'skip';
+        case 'json-key':
+            return 'json';
+        case 'link':
+        case 'link-or-local':
+            return 'link';
+        case 'copy':
+        case 'local':
+            return 'copy';
+        case 'link-or-copy':
+            return item.noSymlink ? 'copy' : 'link';
+        case 'local-if-api':
+            // An API Account gets its own copy to edit; a subscription Account shares the main one.
+            return api || item.noSymlink ? 'copy' : 'link';
+    }
+}
+export async function createAccount(opts) {
+    const { family, name, api, home } = opts;
+    if (!ACCOUNT_NAME.test(name) || name === 'main')
+        throw new CreateError(`"${name}" is not a valid account name: use 1–32 lowercase letters, digits or "-", not "main"`);
+    const mainDir = mainDirOf(family, home);
+    if (!(await statOrNull(mainDir))?.isDirectory())
+        throw new CreateError(`${family.title} has no main account at ${mainDir}; install ${family.bin} (${family.installUrl}) and run it once first`);
+    const dir = accountDirOf(family, home, name);
+    if (await lstatOrNull(dir))
+        throw new CreateError(`${dir} already exists; pick another name or run \`sideby doctor\``);
+    // Every level of the layout that already exists must be a real directory (as discovery requires), so a
+    // symlinked `~/.pi-<name>` can never make creation write into its target.
+    const segments = relative(home, dir).split(sep);
+    for (let i = 1; i < segments.length; i++) {
+        const prefix = join(home, ...segments.slice(0, i));
+        const st = await lstatOrNull(prefix);
+        if (st && !st.isDirectory())
+            throw new CreateError(`${prefix} exists and is not a real directory (a link or file); move it aside first`);
+    }
+    // Plugins may refuse before anything is written (Cursor keeps one subscription login besides main).
+    try {
+        await opts.bus.run('account.create.before', family.id, {
+            family,
+            name,
+            api,
+            accounts: opts.accounts ?? [],
+            config: {},
+        });
+    }
+    catch (err) {
+        if (!(err instanceof HookError))
+            throw err;
+        if (err.aborted)
+            throw new CreateError(err.message, { code: 'create-refused' });
+        throw new CreateError(`${err.message}; nothing was created. Fix or disable plugin ${err.plugin} (see \`sideby plugins\`)`);
+    }
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const steps = [];
+    for (const item of family.sharedItems) {
+        const { mainPath, accountPath } = itemPaths(home, mainDir, dir, item);
+        const action = actionFor(item, api);
+        if (action === 'skip')
+            continue;
+        if (!(await statOrNull(mainPath))) {
+            steps.push({ item: item.path, action: 'skipped', ok: true, message: 'not in the main account' });
+            continue;
+        }
+        try {
+            await assertInside(dir, accountPath);
+            await mkdir(dirname(accountPath), { recursive: true });
+            if (action === 'link') {
+                await symlink(mainPath, accountPath);
+                steps.push({ item: item.path, action: 'linked', ok: true });
+            }
+            else if (action === 'copy') {
+                await replaceWithCopy(mainPath, accountPath);
+                steps.push({ item: item.path, action: 'copied', ok: true });
+            }
+            else {
+                // Never echo parse errors: this file holds credentials.
+                const parsed = parseJsonSafely(await readFile(mainPath, 'utf8'), item.mainPath ?? item.path);
+                const value = parsed?.[item.key];
+                await writeFileAtomic(accountPath, `${JSON.stringify(value === undefined ? {} : { [item.key]: value }, null, 2)}\n`);
+                steps.push({ item: `${item.path}#${item.key}`, action: 'written', ok: true });
+            }
+        }
+        catch (err) {
+            steps.push({ item: item.path, action: 'skipped', ok: false, message: err.message });
+        }
+    }
+    let secretFile;
+    if (api) {
+        secretFile = join(dir, 'proxy.env');
+        await writeFileAtomic(secretFile, secretFileTemplate(family.apiVars, family.title), 0o600);
+        steps.push({ item: 'proxy.env', action: 'written', ok: true });
+    }
+    const account = await accountAt(family, home, name);
+    const logs = [];
+    const hookErrors = (await opts.bus.runIsolated('account.created', family.id, {
+        account,
+        family,
+        config: {},
+        log: (m) => logs.push(m),
+    }))
+        .filter((r) => r.error)
+        .map((r) => ({ plugin: r.plugin, message: r.error.message }));
+    const nextSteps = api
+        ? [`fill in ${secretFile}`, `sideby run ${account.ref}`]
+        : [`sideby login ${account.ref}`, `sideby run ${account.ref}`];
+    return {
+        account,
+        steps,
+        hookErrors,
+        nextSteps: [...nextSteps, ...logs],
+        ok: steps.every((s) => s.ok) && hookErrors.length === 0,
+    };
+}

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

@@ -0,0 +1,41 @@
+import type { HookBus } from '../plugins/bus.ts';
+import type { Account, FamilyDef, Finding } from '../types.ts';
+export interface AccountReport {
+    ref: string;
+    family: string;
+    name: string;
+    kind: Account['kind'];
+    dir: string;
+    shared: {
+        ok: number;
+        total: number;
+    };
+    backups: number;
+    findings: Finding[];
+}
+export interface FixOutcome {
+    account: string;
+    item: string;
+    code: string;
+    ok: boolean;
+    message: string;
+}
+export interface DoctorReport {
+    status: 'ok' | 'issues';
+    accounts: AccountReport[];
+    /** Findings that are not about one Account (for example a missing Main Account). */
+    general: Finding[];
+    fixes: FixOutcome[];
+}
+export interface DoctorInput {
+    home: string;
+    families: ReadonlyMap<string, FamilyDef>;
+    accounts: readonly Account[];
+    bus: HookBus;
+    force?: boolean;
+    /** This sideby's version: when set, installed sideby skills of the checked Families are compared with it. */
+    skillVersion?: string;
+}
+export declare function runDoctor(input: DoctorInput): Promise<DoctorReport>;
+/** Applies every fixable Finding once, in order; one failing fix never stops the others. */
+export declare function applyFixes(report: DoctorReport): Promise<FixOutcome[]>;