sideby 0.0.0-stage → 0.1.0

package/dist/src/core/config.js

@@ -0,0 +1,181 @@
+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))),
+    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[]>;

package/dist/src/core/doctor.js

@@ -0,0 +1,171 @@
+import { readdir } from 'node:fs/promises';
+import { looksLikeBackup, mainDirOf } from './accounts.js';
+import { lstatOrNull, permBits, statOrNull } from './fs-safe.js';
+import { inspectSecretFile } from './secret-file.js';
+import { checkItem, credentialModeFinding, itemPaths } from './share-modes.js';
+import { checkInstalledSkills } from './skill-check.js';
+const BACKUP_ENTRY = /(\.bak|backup|\.tmp)/i;
+const BACKUP_DIRS = new Set(['backups', 'tmp', '.tmp']);
+async function countBackups(dir) {
+    try {
+        return (await readdir(dir)).filter((e) => BACKUP_ENTRY.test(e) && !BACKUP_DIRS.has(e)).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function toFinding(r, account, source) {
+    return { ...r, account, source, fixable: Boolean(r.fixable && r.fix) };
+}
+async function checkAccount(input, family, account) {
+    const findings = [];
+    let okCount = 0;
+    let total = 0;
+    const mainDir = mainDirOf(family, input.home);
+    const items = [...family.sharedItems];
+    if (!account.isMain) {
+        for (const item of items) {
+            const { mainPath, accountPath } = itemPaths(input.home, mainDir, account.dir, item);
+            const res = await checkItem({
+                account,
+                item,
+                mainPath,
+                accountPath,
+                accountDir: account.dir,
+                force: Boolean(input.force),
+            });
+            if (res.counted) {
+                total++;
+                if (res.results[0]?.level === 'ok')
+                    okCount++;
+            }
+            for (const r of res.results)
+                if (r.level !== 'ok')
+                    findings.push(toFinding(r, account.ref, 'core'));
+        }
+        if (looksLikeBackup(account.name))
+            findings.push({
+                level: 'warn',
+                account: account.ref,
+                item: 'name',
+                code: 'name.backup-like',
+                message: `${account.ref} looks like a backup, not an account`,
+                hint: `if it is a backup, add "${account.ref}" to "ignore" in the sideby config`,
+                source: 'core',
+                fixable: false,
+            });
+    }
+    else {
+        // The Main Account is the source of sharing; only its credential files are checked.
+        for (const item of items.filter((i) => i.credential)) {
+            const { mainPath } = itemPaths(input.home, mainDir, account.dir, item);
+            const st = await lstatOrNull(mainPath);
+            if (st?.isFile() && permBits(st) !== 0o600)
+                findings.push(toFinding(credentialModeFinding(item.mainPath ?? item.path, mainPath, permBits(st)), account.ref, 'core'));
+        }
+    }
+    if (account.secretFile) {
+        const state = await inspectSecretFile(account.secretFile);
+        if (state.kind === 'not-file')
+            findings.push({
+                level: 'fail',
+                account: account.ref,
+                item: 'proxy.env',
+                code: 'secret.not-file',
+                message: 'proxy.env must be a regular file, not a link or directory',
+                source: 'core',
+                fixable: false,
+            });
+        else if (state.kind === 'mode')
+            findings.push(toFinding(credentialModeFinding('proxy.env', account.secretFile, state.mode), account.ref, 'core'));
+    }
+    for (const r of await input.bus.runIsolated('doctor.check', family.id, {
+        account,
+        family,
+        config: {},
+    })) {
+        if (r.error) {
+            findings.push({
+                level: 'fail',
+                account: account.ref,
+                item: 'plugin',
+                code: 'plugin.error',
+                message: r.error.message,
+                source: r.plugin,
+                fixable: false,
+            });
+            continue;
+        }
+        const results = r.result ?? [];
+        if (!Array.isArray(results)) {
+            findings.push({
+                level: 'fail',
+                account: account.ref,
+                item: 'plugin',
+                code: 'plugin.error',
+                message: `[${r.plugin}] doctor.check must return an array of findings`,
+                source: r.plugin,
+                fixable: false,
+            });
+            continue;
+        }
+        for (const c of results)
+            if (c?.level !== 'ok')
+                findings.push(toFinding(c, account.ref, r.plugin));
+    }
+    return {
+        ref: account.ref,
+        family: account.family,
+        name: account.name,
+        kind: account.kind,
+        dir: account.dir,
+        shared: { ok: okCount, total },
+        backups: await countBackups(account.dir),
+        findings,
+    };
+}
+export async function runDoctor(input) {
+    const accounts = [];
+    const general = [];
+    for (const family of input.families.values()) {
+        const list = input.accounts.filter((a) => a.family === family.id);
+        if (list.length === 0)
+            continue;
+        if (!list.some((a) => a.isMain) && !(await statOrNull(mainDirOf(family, input.home)))?.isDirectory())
+            general.push({
+                level: 'fail',
+                account: `${family.id}:main`,
+                item: 'main',
+                code: 'main.missing',
+                message: `${family.title} has accounts but no main account directory to share from`,
+                hint: `run ${family.bin} once so it creates its default directory`,
+                source: 'core',
+                fixable: false,
+            });
+        for (const account of list)
+            accounts.push(await checkAccount(input, family, account));
+    }
+    if (input.skillVersion) {
+        const checked = [...input.families.values()].filter((f) => input.accounts.some((a) => a.family === f.id));
+        general.push(...(await checkInstalledSkills(input.home, checked, input.skillVersion)));
+    }
+    const failed = [...general, ...accounts.flatMap((a) => a.findings)].some((f) => f.level === 'fail');
+    return { status: failed ? 'issues' : 'ok', accounts, general, fixes: [] };
+}
+/** Applies every fixable Finding once, in order; one failing fix never stops the others. */
+export async function applyFixes(report) {
+    const out = [];
+    for (const f of report.accounts.flatMap((a) => a.findings)) {
+        if (!f.fixable || !f.fix)
+            continue;
+        let res;
+        try {
+            res = await f.fix();
+        }
+        catch (err) {
+            res = { ok: false, message: err.message };
+        }
+        out.push({ account: f.account, item: f.item, code: f.code, ...res });
+    }
+    return out;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * An error caused by what the user asked for or has on disk (unknown account, broken config, invalid name),
+ * as opposed to a bug. Adapters map it without a stack: the CLI exits 1, the Panel answers 400.
+ * Command-line shape errors (`UsageError`, exit 2) are deliberately not UserErrors.
+ */
+export declare class UserError extends Error {
+    /** Machine-readable reason, such as `create-refused`; the Panel passes it to the page. */
+    readonly code?: string;
+    constructor(message: string, opts?: {
+        code?: string;
+    });
+}

package/dist/src/core/errors.js

@@ -0,0 +1,14 @@
+/**
+ * An error caused by what the user asked for or has on disk (unknown account, broken config, invalid name),
+ * as opposed to a bug. Adapters map it without a stack: the CLI exits 1, the Panel answers 400.
+ * Command-line shape errors (`UsageError`, exit 2) are deliberately not UserErrors.
+ */
+export class UserError extends Error {
+    /** Machine-readable reason, such as `create-refused`; the Panel passes it to the page. */
+    code;
+    constructor(message, opts = {}) {
+        super(message);
+        if (opts.code)
+            this.code = opts.code;
+    }
+}

package/dist/src/core/file-memo.d.ts

@@ -0,0 +1,24 @@
+import type { Stats } from 'node:fs';
+/** The parts of `fs.Stats` that tell whether a file changed. */
+export type FileStats = Pick<Stats, 'size' | 'mtimeMs' | 'ctimeMs' | 'ino'>;
+export declare function fileSignature(st: FileStats): string;
+/** One pass over a scope's files. Files the pass does not ask for are forgotten when it ends. */
+export interface MemoPass<T> {
+    /** The remembered value for this file version, or `parse()` (remembered unless `keep` says no). */
+    get(path: string, st: FileStats, parse: () => Promise<T>, keep?: (value: T) => boolean): Promise<T>;
+    /** Ends the pass: the scope now holds only the files this pass asked for. */
+    done(): void;
+}
+export declare class FileMemo<T> {
+    #private;
+    /** Counters for tests and timing. */
+    readonly stats: {
+        hits: number;
+        misses: number;
+    };
+    /** Starts a pass over `scope`, such as one Account's directory. */
+    pass(scope: string): MemoPass<T>;
+    /** Files remembered for a scope (for tests). */
+    size(scope: string): number;
+    clear(): void;
+}

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

@@ -0,0 +1,41 @@
+export function fileSignature(st) {
+    return `${st.size}:${st.mtimeMs}:${st.ctimeMs}:${st.ino}`;
+}
+export class FileMemo {
+    #scopes = new Map();
+    /** Counters for tests and timing. */
+    stats = { hits: 0, misses: 0 };
+    /** Starts a pass over `scope`, such as one Account's directory. */
+    pass(scope) {
+        const before = this.#scopes.get(scope);
+        const seen = new Map();
+        return {
+            get: async (path, st, parse, keep) => {
+                const sig = fileSignature(st);
+                const hit = seen.get(path) ?? before?.get(path);
+                if (hit && hit.sig === sig) {
+                    this.stats.hits++;
+                    seen.set(path, hit);
+                    return hit.value;
+                }
+                this.stats.misses++;
+                const value = await parse();
+                if (!keep || keep(value))
+                    seen.set(path, { sig, value });
+                return value;
+            },
+            done: () => {
+                this.#scopes.set(scope, seen);
+            },
+        };
+    }
+    /** Files remembered for a scope (for tests). */
+    size(scope) {
+        return this.#scopes.get(scope)?.size ?? 0;
+    }
+    clear() {
+        this.#scopes.clear();
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+    }
+}