sideby 0.0.0-stage → 0.2.1

package/dist/src/core/secret-file.js

@@ -0,0 +1,116 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { UserError } from './errors.js';
+export class SecretFileError extends UserError {
+}
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
+/** Non-secret locations a Secret File may reference from the environment, such as `$HOME/bin/notify`. */
+export const SECRET_FILE_ENV_REFS = [
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'TMPDIR',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'XDG_STATE_HOME',
+    'XDG_CACHE_HOME',
+];
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)|\$\{/g;
+/**
+ * Parses the dotenv subset sideby supports: KEY=VALUE, optional `export `, quotes and comments.
+ * `$NAME` and `${NAME}` in unquoted or double-quoted values expand to a key defined earlier in the
+ * same file, else to one of SECRET_FILE_ENV_REFS from `env`; no other variable is read and nothing is
+ * executed. Errors name the line, never its content.
+ */
+export function parseSecretFile(text, file, env = {}) {
+    const out = {};
+    const lines = text.split(/\r?\n/);
+    const expand = (s, line) => s.replace(REF, (whole, braced, bare) => {
+        const name = braced ?? bare;
+        if (!name)
+            throw new SecretFileError(`${file}:${line}: unterminated \${`);
+        if (Object.hasOwn(out, name))
+            return out[name];
+        const fromEnv = SECRET_FILE_ENV_REFS.includes(name) ? env[name] : undefined;
+        if (fromEnv !== undefined)
+            return fromEnv;
+        throw new SecretFileError(`${file}:${line}: ${whole} is not defined earlier in this file; from the environment only ${SECRET_FILE_ENV_REFS.join(', ')} are read`);
+    });
+    lines.forEach((raw, i) => {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            return;
+        const m = LINE.exec(raw);
+        if (!m)
+            throw new SecretFileError(`${file}:${i + 1}: expected KEY=VALUE`);
+        const key = m[1];
+        let value = m[2];
+        const q = value[0];
+        if (q === '"' || q === "'") {
+            let end = -1;
+            for (let j = 1; j < value.length; j++) {
+                if (q === '"' && value[j] === '\\')
+                    j++;
+                else if (value[j] === q) {
+                    end = j;
+                    break;
+                }
+            }
+            if (end === -1)
+                throw new SecretFileError(`${file}:${i + 1}: unterminated quote`);
+            const rest = value.slice(end + 1).trim();
+            if (rest && !rest.startsWith('#'))
+                throw new SecretFileError(`${file}:${i + 1}: text after closing quote`);
+            value = value.slice(1, end);
+            if (q === '"')
+                // Escapes and references in one pass, so an escaped `\$` stays a literal dollar sign.
+                value = value.replace(/\\(n|"|\\|\$)|\$[^$\\]*/g, (part, c) => c === undefined ? expand(part, i + 1) : c === 'n' ? '\n' : c);
+        }
+        else {
+            const hash = value.search(/\s#/);
+            if (hash !== -1)
+                value = value.slice(0, hash).trimEnd();
+            if (/\$\(|`/.test(value))
+                throw new SecretFileError(`${file}:${i + 1}: command substitution is not supported; write the value itself`);
+            value = expand(value, i + 1);
+        }
+        out[key] = value;
+    });
+    return out;
+}
+/**
+ * The one Secret File rule, used by Launch and by Doctor: the Account's own regular file (never a link)
+ * with mode 600. Only the file's type and mode are inspected, never its contents.
+ */
+export async function inspectSecretFile(file) {
+    let st;
+    try {
+        st = await lstat(file);
+    }
+    catch {
+        return { kind: 'missing' };
+    }
+    if (!st.isFile())
+        return { kind: 'not-file' };
+    const mode = st.mode & 0o777;
+    return mode === 0o600 ? { kind: 'ok' } : { kind: 'mode', mode };
+}
+/** Reads a Secret File after inspectSecretFile accepts it. */
+export async function readSecretFile(file, env = {}) {
+    const state = await inspectSecretFile(file);
+    if (state.kind === 'missing')
+        throw new SecretFileError(`${file} is missing`);
+    if (state.kind === 'not-file')
+        throw new SecretFileError(`${file} must be a regular file, not a link or directory`);
+    if (state.kind === 'mode')
+        throw new SecretFileError(`${file} has mode ${state.mode.toString(8)}; run \`chmod 600 ${file}\` so only you can read it`);
+    return parseSecretFile(await readFile(file, 'utf8'), file, env);
+}
+export function secretFileTemplate(vars, familyTitle) {
+    const lines = [
+        `# ${familyTitle} API account. sideby loads these variables only into this account's process.`,
+        '# Uncomment and fill in. Keep this file private (mode 600).',
+        ...vars.map((v) => `# ${v}=`),
+        '',
+    ];
+    return lines.join('\n');
+}

package/dist/src/core/share-meaning.d.ts

@@ -0,0 +1,6 @@
+import type { SharedItemDef } from '../types.ts';
+/**
+ * What one Shared Item looks like in an Account, in one fixed English sentence for `sideby families` (spec §3.16).
+ * Agents quote it to users, so it follows the Share Mode rules of spec §3.3 and never promises more.
+ */
+export declare function shareMeaning(item: SharedItemDef): string;

package/dist/src/core/share-meaning.js

@@ -0,0 +1,32 @@
+/**
+ * What one Shared Item looks like in an Account, in one fixed English sentence for `sideby families` (spec §3.16).
+ * Agents quote it to users, so it follows the Share Mode rules of spec §3.3 and never promises more.
+ */
+export function shareMeaning(item) {
+    const main = item.mainPath ? `~/${item.mainPath}` : "the Main Account's";
+    const base = (() => {
+        switch (item.mode) {
+            case 'link':
+                return "A link to the Main Account's: one copy for every Account.";
+            case 'copy':
+                return "A copy of the Main Account's, kept equal by `doctor --fix`; the Host does not accept a link here.";
+            case 'link-or-copy':
+                return "A link to the Main Account's, or a copy kept equal by `doctor --fix`.";
+            case 'link-or-local':
+                return "A link to the Main Account's, unless the Account keeps its own file.";
+            case 'local':
+                return "The Account's own file, first copied from the Main Account and never synced.";
+            case 'local-if-api':
+                return item.noSymlink
+                    ? "Subscription Accounts: a copy of the Main Account's, kept equal by `doctor --fix`. API Accounts: their own file."
+                    : "Subscription Accounts: a link to the Main Account's, or a copy kept equal. API Accounts: their own file.";
+            case 'info':
+                return item.credential
+                    ? "The Account's own sign-in: never shared and never read; sideby checks only that it is mode 600."
+                    : "The Account's own; sideby only reports it.";
+            case 'json-key':
+                return `The Account's own file; only its \`${item.key}\` entry is kept equal to ${main}${item.credential ? ', and sideby reads no other part of it' : ''}.`;
+        }
+    })();
+    return item.noSymlink && item.mode !== 'copy' ? `${base} Never a link: the Host refuses one.` : base;
+}

package/dist/src/core/share-mode-names.d.ts

@@ -0,0 +1 @@
+export declare const SHARE_MODES: readonly ["link", "copy", "link-or-copy", "link-or-local", "local", "local-if-api", "info", "json-key"];

package/dist/src/core/share-mode-names.js

@@ -0,0 +1,10 @@
+export const SHARE_MODES = [
+    'link',
+    'copy',
+    'link-or-copy',
+    'link-or-local',
+    'local',
+    'local-if-api',
+    'info',
+    'json-key',
+];

package/dist/src/core/share-modes.d.ts

@@ -0,0 +1,24 @@
+import type { Account, CheckResult, SharedItemDef } from '../types.ts';
+export interface ItemContext {
+    account: Account;
+    item: SharedItemDef;
+    /** Resolved main-side path. */
+    mainPath: string;
+    /** Path inside the Account directory. */
+    accountPath: string;
+    /** The Account directory; every repair must stay inside it. */
+    accountDir: string;
+    /** Allows `json-key` to remove entries the Account has but the main file does not. */
+    force: boolean;
+}
+/** `counted` is false for `info` items, which never count toward the shared total. */
+export interface ItemCheck {
+    counted: boolean;
+    results: CheckResult[];
+}
+export declare function credentialModeFinding(item: string, path: string, mode: number): CheckResult;
+export declare function checkItem(ctx: ItemContext): Promise<ItemCheck>;
+export declare function itemPaths(home: string, mainDir: string, accountDir: string, item: SharedItemDef): {
+    mainPath: string;
+    accountPath: string;
+};

package/dist/src/core/share-modes.js

@@ -0,0 +1,405 @@
+import { chmod, mkdir, readFile, symlink, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { assertInside, fileHash, isEmptyDir, linksTo, lstatOrNull, permBits, realpathOrNull, replaceWithCopy, sameContent, statOrNull, writeIfUnchanged, } from './fs-safe.js';
+function kindOf(st) {
+    if (!st)
+        return 'missing';
+    if (st.isSymbolicLink())
+        return 'link';
+    if (st.isFile())
+        return 'file';
+    if (st.isDirectory())
+        return 'dir';
+    return 'other';
+}
+async function classify(ctx) {
+    const st = await lstatOrNull(ctx.accountPath);
+    const k = kindOf(st);
+    if (k !== 'link')
+        return { kind: k, st };
+    return { kind: (await linksTo(ctx.accountPath, ctx.mainPath)) ? 'link-ok' : 'link-other', st };
+}
+const ok = (item) => ({ level: 'ok', item, code: 'ok', message: 'ok' });
+function hostNote(item) {
+    return item.hostMessage ? ` (host says: "${item.hostMessage}")` : '';
+}
+async function makeLink(ctx) {
+    await mkdir(dirname(ctx.accountPath), { recursive: true });
+    await symlink(ctx.mainPath, ctx.accountPath);
+    return { ok: true, message: `linked ${ctx.item.path}` };
+}
+async function makeCopy(ctx) {
+    await mkdir(dirname(ctx.accountPath), { recursive: true });
+    await replaceWithCopy(ctx.mainPath, ctx.accountPath);
+    return { ok: true, message: `copied ${ctx.item.path} from the main account` };
+}
+/** Replaces a symlink that points at the main item with a real copy; refuses any other link. */
+async function linkToCopy(ctx) {
+    if (!(await linksTo(ctx.accountPath, ctx.mainPath)))
+        return { ok: false, message: `${ctx.item.path} no longer points at the main account; left unchanged` };
+    await unlink(ctx.accountPath);
+    return makeCopy(ctx);
+}
+function realConflict(ctx, what) {
+    const p = ctx.accountPath;
+    return {
+        level: 'fail',
+        item: ctx.item.path,
+        code: 'link.real-file',
+        message: `${ctx.item.path} is a real ${what}; expected a link to the main account`,
+        hint: `sideby never replaces it. Keep it with: mv "${p}" "${p}.local" && ln -s "${ctx.mainPath}" "${p}"`,
+    };
+}
+/** Whether this item may legitimately be a link in this Account. */
+function acceptsLink(ctx) {
+    const { item } = ctx;
+    if (item.noSymlink)
+        return false;
+    if (item.mode === 'local-if-api')
+        return ctx.account.kind !== 'api';
+    return item.mode === 'link' || item.mode === 'link-or-copy' || item.mode === 'link-or-local';
+}
+/** A link that does not resolve to the main item: dangling is a failure, a deliberate other target a warning. */
+async function wrongLink(ctx) {
+    const target = await realpathOrNull(ctx.accountPath);
+    if (target && !acceptsLink(ctx))
+        return {
+            level: 'fail',
+            item: ctx.item.path,
+            code: 'symlink-forbidden',
+            message: `${ctx.item.path} must not be a link (it points to ${target})${hostNote(ctx.item)}`,
+            hint: `sideby never re-points or replaces links it did not create. Replace it yourself: rm "${ctx.accountPath}" && cp -R "${ctx.mainPath}" "${ctx.accountPath}"`,
+        };
+    if (target)
+        return {
+            level: 'warn',
+            item: ctx.item.path,
+            code: 'link.other-target',
+            message: `${ctx.item.path} links to ${target} instead of the main account's ${ctx.item.path}`,
+            hint: 'fine if intended; sideby never re-points links',
+        };
+    return {
+        level: 'fail',
+        item: ctx.item.path,
+        code: 'link.dangling',
+        message: `${ctx.item.path} is a dangling link`,
+        hint: `sideby never re-points links. Inspect it with: ls -l "${ctx.accountPath}"`,
+    };
+}
+function missingFix(ctx, useCopy) {
+    return {
+        level: 'fail',
+        item: ctx.item.path,
+        code: 'missing',
+        message: `${ctx.item.path} is missing`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: () => (useCopy ? makeCopy(ctx) : makeLink(ctx)),
+    };
+}
+async function compareCopy(ctx, mainSt, kind) {
+    const item = ctx.item.path;
+    const mainKind = mainSt.isDirectory() ? 'dir' : 'file';
+    if (kind !== mainKind)
+        return {
+            level: 'fail',
+            item,
+            code: 'copy.type-mismatch',
+            message: `${item} is a ${kind} but the main account has a ${mainKind}`,
+            hint: 'sideby does not change the type of an existing item; move it aside and run `sideby doctor --fix`',
+        };
+    if (await sameContent(ctx.accountPath, ctx.mainPath))
+        return ok(item);
+    if (mainKind === 'dir' && (await isEmptyDir(ctx.mainPath)))
+        return {
+            level: 'warn',
+            item,
+            code: 'copy.main-empty',
+            message: `${item} differs, but the main account's copy is empty; not mirroring an empty directory`,
+        };
+    return {
+        level: 'fail',
+        item,
+        code: 'copy.stale',
+        message: `${item} is an outdated copy of the main account`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: () => makeCopy(ctx),
+    };
+}
+async function checkCopyLike(ctx, mainSt, allowLink) {
+    const { kind } = await classify(ctx);
+    const item = ctx.item.path;
+    switch (kind) {
+        case 'link-ok':
+            if (allowLink)
+                return ok(item);
+            return {
+                level: 'fail',
+                item,
+                code: 'symlink-forbidden',
+                message: `${item} must be a real copy, not a link${hostNote(ctx.item)}`,
+                hint: 'run `sideby doctor --fix` to replace the link with a copy',
+                fixable: true,
+                fix: () => linkToCopy(ctx),
+            };
+        case 'link-other':
+            return await wrongLink(ctx);
+        case 'missing':
+            return missingFix(ctx, !allowLink);
+        case 'file':
+        case 'dir':
+            return compareCopy(ctx, mainSt, kind);
+        default:
+            return {
+                level: 'fail',
+                item,
+                code: 'unsupported-type',
+                message: `${item} is not a file, directory or link`,
+            };
+    }
+}
+async function checkJsonKey(ctx) {
+    const item = `${ctx.item.path}#${ctx.item.key}`;
+    const key = ctx.item.key;
+    const accSt = await lstatOrNull(ctx.accountPath);
+    if (accSt?.isSymbolicLink())
+        return {
+            level: 'fail',
+            item,
+            code: 'json-key.symlink',
+            message: `${ctx.item.path} is a symlink; sharing it would mix logins between accounts`,
+            hint: `replace it with the account's own file; sideby will not write through it even with --force`,
+        };
+    let mainVal;
+    let mainText;
+    try {
+        mainText = await readFile(ctx.mainPath, 'utf8');
+    }
+    catch {
+        return { level: 'ok', item, code: 'ok', message: 'main file absent; nothing to share' };
+    }
+    try {
+        mainVal = JSON.parse(mainText)[key];
+    }
+    catch {
+        return {
+            level: 'warn',
+            item,
+            code: 'json-key.main-unreadable',
+            message: `cannot read ${key} from the main file`,
+        };
+    }
+    if (mainVal === undefined)
+        return { level: 'ok', item, code: 'ok', message: `main file has no ${key}` };
+    if (!isPlainObject(mainVal))
+        return { level: 'fail', item, code: 'json-key.main-not-object', message: `main ${key} is not an object` };
+    const beforeHash = await fileHash(ctx.accountPath);
+    let acc = {};
+    if (beforeHash !== null) {
+        try {
+            const parsed = JSON.parse(await readFile(ctx.accountPath, 'utf8'));
+            if (!isPlainObject(parsed))
+                throw new Error('not an object');
+            acc = parsed;
+        }
+        catch {
+            return {
+                level: 'fail',
+                item,
+                code: 'json-key.not-object',
+                message: `${ctx.item.path} is not a JSON object; sideby will not rewrite it`,
+            };
+        }
+    }
+    const accVal = key in acc ? acc[key] : {};
+    if (!isPlainObject(accVal))
+        return {
+            level: 'fail',
+            item,
+            code: 'json-key.not-object',
+            message: `${key} in ${ctx.item.path} is not an object`,
+        };
+    if (canonical(accVal) === canonical(mainVal))
+        return ok(item);
+    const removed = Object.keys(accVal).filter((k) => !(k in mainVal));
+    const added = Object.keys(mainVal).filter((k) => !(k in accVal));
+    const detail = [
+        added.length ? `adds ${added.join(', ')}` : '',
+        removed.length ? `removes ${removed.join(', ')}` : '',
+    ]
+        .filter(Boolean)
+        .join('; ');
+    const write = async () => {
+        const next = `${JSON.stringify({ ...acc, [key]: mainVal }, null, 2)}\n`;
+        const done = await writeIfUnchanged(ctx.accountPath, beforeHash, next, 0o600);
+        return done
+            ? { ok: true, message: `synced ${key} (${detail || 'values changed'})` }
+            : { ok: false, message: `${ctx.item.path} changed while syncing; run doctor again` };
+    };
+    if (removed.length && !ctx.force)
+        return {
+            level: 'fail',
+            item,
+            code: 'json-key.would-remove',
+            message: `${key} differs from the main account and syncing would remove: ${removed.join(', ')}`,
+            hint: 'add them to the main account first, or run `sideby doctor --fix --force` to remove them',
+        };
+    return {
+        level: 'fail',
+        item,
+        code: 'json-key.drift',
+        message: `${key} differs from the main account (${detail || 'values changed'})`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: write,
+    };
+}
+async function checkCredentialMode(ctx) {
+    const st = await lstatOrNull(ctx.accountPath);
+    if (!st?.isFile() || permBits(st) === 0o600)
+        return null;
+    return credentialModeFinding(ctx.item.path, ctx.accountPath, permBits(st));
+}
+export function credentialModeFinding(item, path, mode) {
+    return {
+        level: 'fail',
+        item,
+        code: 'credential.mode',
+        message: `${item} has mode ${mode.toString(8)}; credentials must be 600`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: async () => {
+            await chmod(path, 0o600);
+            return { ok: true, message: `set ${item} to 600` };
+        },
+    };
+}
+export async function checkItem(ctx) {
+    const { item } = ctx;
+    const out = [];
+    if (isAbsolute(item.path) || item.path.split(/[\\/]/).includes('..'))
+        return {
+            counted: false,
+            results: [
+                {
+                    level: 'fail',
+                    item: item.path,
+                    code: 'path.invalid',
+                    message: `shared item path ${item.path} must be relative and stay inside the account directory`,
+                    hint: 'fix the path in the sideby config or the plugin that defines it',
+                },
+            ],
+        };
+    // Every repair re-checks, at the moment it runs, that it writes inside this Account only.
+    const guard = (r) => {
+        const fix = r.fix;
+        if (!fix)
+            return r;
+        return {
+            ...r,
+            fix: async () => {
+                await assertInside(ctx.accountDir, ctx.accountPath);
+                return fix();
+            },
+        };
+    };
+    const done = async (r, counted = true) => {
+        out.push(guard(r));
+        if (item.credential) {
+            const c = await checkCredentialMode(ctx);
+            if (c)
+                out.push(guard(c));
+        }
+        return { counted, results: out };
+    };
+    if (item.mode === 'info') {
+        const st = await lstatOrNull(ctx.accountPath);
+        if (item.noSymlink && st?.isSymbolicLink())
+            return done({
+                level: 'fail',
+                item: item.path,
+                code: 'symlink-forbidden',
+                message: `${item.path} must not be a link${hostNote(item)}`,
+                hint: `sideby does not copy credentials. Replace the link with the account's own file, e.g. log in again with \`sideby login ${ctx.account.ref}\``,
+            }, false);
+        return done(ok(item.path), false);
+    }
+    if (item.mode === 'json-key')
+        return done(await checkJsonKey(ctx));
+    // The main account has nothing to share here yet: not counted, but the Account's own entry must still
+    // respect Host rules (a dangling link, or a link where the Host refuses links, is still a problem).
+    const mainSt = await statOrNull(ctx.mainPath);
+    if (!mainSt) {
+        const st = await lstatOrNull(ctx.accountPath);
+        if (st?.isSymbolicLink() && (!(await realpathOrNull(ctx.accountPath)) || !acceptsLink(ctx)))
+            return done(await wrongLink(ctx), false);
+        return done(ok(item.path), false);
+    }
+    const isApi = ctx.account.kind === 'api';
+    const { kind } = await classify(ctx);
+    switch (item.mode) {
+        case 'link':
+            if (kind === 'link-ok')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done(missingFix(ctx, false));
+            if (kind === 'link-other')
+                return done(await wrongLink(ctx));
+            return done(realConflict(ctx, kind === 'dir' ? 'directory' : 'file'));
+        case 'copy':
+            return done(await checkCopyLike(ctx, mainSt, false));
+        case 'link-or-copy':
+            return done(await checkCopyLike(ctx, mainSt, !item.noSymlink));
+        case 'link-or-local':
+            if (kind === 'link-ok' || kind === 'file' || kind === 'dir')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done(missingFix(ctx, false));
+            return done(await wrongLink(ctx));
+        case 'local':
+            if (kind === 'file' || kind === 'dir')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done(missingFix(ctx, true));
+            return done({
+                level: 'fail',
+                item: item.path,
+                code: 'local.is-link',
+                message: `${item.path} must be the account's own file, not a link${hostNote(item)}`,
+                hint: `sideby never replaces links here. Replace it yourself: rm "${ctx.accountPath}" && cp -R "${ctx.mainPath}" "${ctx.accountPath}"`,
+            });
+        case 'local-if-api':
+            if (!isApi)
+                return done(await checkCopyLike(ctx, mainSt, !item.noSymlink));
+            if (kind === 'file')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done({
+                    level: 'fail',
+                    item: item.path,
+                    code: 'api.needs-own',
+                    message: `${item.path} is missing; an API account needs its own copy`,
+                    hint: `cp "${ctx.mainPath}" "${ctx.accountPath}" and edit it for this account's endpoint`,
+                });
+            return done({
+                level: 'fail',
+                item: item.path,
+                code: 'api.needs-own',
+                message: `${item.path} must be this API account's own file (found ${kind === 'link-ok' || kind === 'link-other' ? 'a link' : `a ${kind}`})`,
+                hint: 'an API account changes its endpoint here, so sharing it would change the main account too',
+            });
+    }
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function canonical(v) {
+    return JSON.stringify(v, (_k, val) => isPlainObject(val) ? Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b))) : val);
+}
+export function itemPaths(home, mainDir, accountDir, item) {
+    return {
+        mainPath: item.mainPath ? join(home, item.mainPath) : join(mainDir, item.path),
+        accountPath: join(accountDir, item.path),
+    };
+}

package/dist/src/core/shell-init.d.ts

@@ -0,0 +1,31 @@
+import type { Account } from '../types.ts';
+export declare const SHELLS: readonly ['zsh', 'bash'];
+export type Shell = (typeof SHELLS)[number];
+/** First line of every generated script; an existing file without it is never overwritten. */
+export declare const SHELL_INIT_HEADER = "# sideby shell-init: one function per account, plus aliases from the sideby config";
+/** A Family whose bare Host command `shell-init` routes through `sideby resume` (config `resumeRouting`). */
+export interface ResumeRouteFunction {
+    family: string;
+    bin: string;
+    selectVar: string;
+}
+/**
+ * The script for one shell, ending in a newline: exactly what `sideby shell-init <shell>` prints. zsh and bash
+ * read the same function syntax, so the shell only names the file it goes to.
+ */
+export declare function shellInitScript(accounts: readonly Account[], aliases: Readonly<Record<string, unknown>> | undefined, routes?: readonly ResumeRouteFunction[]): string;
+export interface ShellInitWrite {
+    shell: Shell;
+    /** The configured path, as written in the config (`~/…` kept). */
+    path: string;
+    ok: boolean;
+    /** `written`, or `unchanged` when the file already had this content. */
+    action?: 'written' | 'unchanged';
+    message?: string;
+}
+/**
+ * Writes `content` to the configured file atomically (temp file in the same directory, then rename), keeping its
+ * mode (0644 for a new file). Refuses a relative path and an existing file that sideby did not generate, so a
+ * mistyped `shellInitFile` can never replace a shell rc file.
+ */
+export declare function writeShellInitFile(shell: Shell, configured: string, home: string, content: string): Promise<ShellInitWrite>;