sideby 0.0.0-stage → 0.2.1

package/dist/src/runtime.js

@@ -0,0 +1,424 @@
+// The one service layer the CLI and the Panel share. Frozen contract for v0.1 (plan: 审核修订).
+import { discoverAccounts, resolveRef } from './core/accounts.js';
+import { addConfigAlias, aliasAccount, aliasArgs, aliasProblem, aliasRefs, loadConfig, removeConfigAlias, } from './core/config.js';
+import { createAccount } from './core/create.js';
+import { applyFixes, runDoctor } from './core/doctor.js';
+import { UserError } from './core/errors.js';
+import { planHandoff } from './core/handoff.js';
+import { identityOf } from './core/identity.js';
+import { mergeDoctorHistory, readDoctorHistory, writeDoctorHistory, } from './core/last-doctor.js';
+import { prepareLaunch, which } from './core/launch.js';
+import { resolvePaths } from './core/paths.js';
+import { findResumeRoute } from './core/resume.js';
+import { shareMeaning } from './core/share-meaning.js';
+import { SHELLS, shellInitScript, writeShellInitFile, } from './core/shell-init.js';
+import { packageVersion } from './core/version.js';
+import { BUILTIN_PLUGINS } from './families/index.js';
+import { HookBus } from './plugins/bus.js';
+import { loadPlugins } from './plugins/loader.js';
+export class UnknownFamilyError extends UserError {
+}
+/**
+ * A Family's identity reader, kept to the identity fields with the expected types. A reader that throws, or returns
+ * anything else, gives undefined: identity is a display nicety and never a problem of the Account.
+ */
+async function readIdentity(f, account) {
+    if (!f.identity || account.kind === 'api')
+        return undefined;
+    try {
+        const r = await f.identity(account);
+        return identityOf(r?.email, r?.org);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function createRuntime(opts = {}) {
+    const env = opts.env ?? process.env;
+    const paths = resolvePaths(env);
+    const config = await loadConfig(paths.configFile);
+    const bus = new HookBus();
+    const loaded = await loadPlugins({
+        builtins: opts.builtins ?? BUILTIN_PLUGINS,
+        config,
+        bus,
+        userPluginsDir: paths.userPluginsDir,
+        home: paths.home,
+    });
+    const families = loaded.families;
+    const ignore = new Set(config.ignore ?? []);
+    const now = opts.now ?? (() => new Date());
+    const familyOf = (id) => {
+        const f = families.get(id);
+        if (!f)
+            throw new UnknownFamilyError(`unknown family "${id}"; available: ${[...families.keys()].join(', ') || 'none (check `sideby plugins`)'}`);
+        return f;
+    };
+    // Merge `extraSharedItems` from the config into each Family's list.
+    for (const [id, extra] of Object.entries(config.extraSharedItems ?? {})) {
+        const f = families.get(id);
+        if (f)
+            families.set(id, { ...f, sharedItems: [...f.sharedItems, ...extra] });
+    }
+    const accounts = async () => {
+        const out = [];
+        for (const f of families.values())
+            out.push(...(await discoverAccounts(f, paths.home, ignore)));
+        return out;
+    };
+    const readContext = () => ({
+        home: paths.home,
+        now: now(),
+        stateDir: paths.stateDir,
+        env,
+    });
+    /** The config value of the alias `name`, from own keys only (`constructor` is not an alias unless configured). */
+    const ownAlias = (name) => config.aliases && Object.hasOwn(config.aliases, name) ? config.aliases[name] : undefined;
+    /** The config value of `ref` when it names an alias (no colon), as `resolveRef` reads it. */
+    const aliasValue = (ref) => (ref.includes(':') ? undefined : ownAlias(ref));
+    const aliasEdit = async (alias, status, value) => {
+        const args = aliasArgs(value);
+        const files = await rt.writeShellInitFiles();
+        return {
+            ok: files.every((f) => f.ok),
+            alias,
+            status,
+            ...(value === undefined ? {} : { account: aliasAccount(value) }),
+            ...(args.length ? { args } : {}),
+            ...(files.length ? { shellInitFiles: files } : {}),
+        };
+    };
+    const rt = {
+        paths,
+        config,
+        env,
+        families,
+        plugins: loaded.plugins,
+        pluginErrors: loaded.errors,
+        async familyInfo() {
+            return Promise.all([...families.values()].map(async (f) => ({
+                id: f.id,
+                title: f.title,
+                bin: f.bin,
+                installUrl: f.installUrl,
+                installed: (await which(f.bin, env)) !== null,
+                plugin: loaded.familyOwner.get(f.id) ?? 'unknown',
+            })));
+        },
+        async familyDetails() {
+            const info = new Map((await rt.familyInfo()).map((f) => [f.id, f]));
+            return [...families.values()].map((f) => {
+                // The merged list holds the config's own objects, so identity tells which ones came from `extraSharedItems`.
+                const fromConfig = new Set(config.extraSharedItems?.[f.id] ?? []);
+                return {
+                    ...info.get(f.id),
+                    layout: { main: f.layout.main, account: f.layout.account },
+                    selectVar: f.selectVar,
+                    login: { args: f.login.args ? [...f.login.args] : null, hint: f.login.hint },
+                    quota: Boolean(f.readQuota),
+                    usage: Boolean(f.readUsage),
+                    quotaSetup: Boolean(f.quotaSetup),
+                    shared: f.sharedItems.map((item) => ({
+                        path: item.path,
+                        mode: item.mode,
+                        ...(item.key ? { key: item.key } : {}),
+                        ...(item.mainPath ? { mainPath: item.mainPath } : {}),
+                        ...(item.credential ? { credential: true } : {}),
+                        ...(item.noSymlink ? { noSymlink: true } : {}),
+                        source: fromConfig.has(item) ? 'config' : 'family',
+                        meaning: shareMeaning(item),
+                    })),
+                };
+            });
+        },
+        accounts,
+        async resolve(ref) {
+            return resolveRef(ref, await accounts(), aliasRefs(config.aliases));
+        },
+        async status(account) {
+            const f = familyOf(account.family);
+            const problems = [];
+            // Plugin readers may throw synchronously or reject; either way the Account still gets a status.
+            const safe = async (what, fn) => {
+                if (!fn)
+                    return undefined;
+                try {
+                    return await fn();
+                }
+                catch (err) {
+                    problems.push(`${what}: ${err?.message ?? String(err)}`);
+                    return undefined;
+                }
+            };
+            const [installed, login, model, identity] = await Promise.all([
+                which(f.bin, env),
+                account.kind === 'api'
+                    ? undefined
+                    : safe('login state', f.loginState && (() => f.loginState(account))),
+                safe('model', f.model && (() => f.model(account))),
+                readIdentity(f, account),
+            ]);
+            return {
+                ...account,
+                familyTitle: f.title,
+                hostInstalled: installed !== null,
+                login: account.kind === 'api' ? 'not-needed' : (login ?? 'unknown'),
+                ...(model ? { model } : {}),
+                ...(identity ? { identity } : {}),
+                ...(problems.length ? { problems } : {}),
+            };
+        },
+        async doctor(o = {}) {
+            return (await rt.doctorWithHistory(o)).report;
+        },
+        async doctorWithHistory(o = {}) {
+            let list = await accounts();
+            let fams = families;
+            let scope = { kind: 'all' };
+            if (o.target) {
+                if (families.has(o.target)) {
+                    list = list.filter((a) => a.family === o.target);
+                    fams = new Map([[o.target, families.get(o.target)]]);
+                    scope = { kind: 'family', family: o.target };
+                }
+                else {
+                    const one = resolveRef(o.target, list, aliasRefs(config.aliases));
+                    list = [one];
+                    fams = new Map([[one.family, familyOf(one.family)]]);
+                    scope = { kind: 'account', ref: one.ref };
+                }
+            }
+            const input = {
+                home: paths.home,
+                families: fams,
+                accounts: list,
+                bus,
+                force: Boolean(o.force),
+                // Checked for every Family in the run, also when Doctor is aimed at one Account, so the saved result
+                // of that Family keeps its skill warning.
+                skillVersion: packageVersion(),
+            };
+            let report = await runDoctor(input);
+            if (o.fix) {
+                const fixes = await applyFixes(report);
+                report = { ...(await runDoctor(input)), fixes };
+            }
+            const history = mergeDoctorHistory(await readDoctorHistory(paths.stateDir), report, scope, now());
+            if (o.persist !== false)
+                await writeDoctorHistory(paths.stateDir, history);
+            return { report, history };
+        },
+        doctorHistory: () => readDoctorHistory(paths.stateDir),
+        async quotaSetups() {
+            const out = [];
+            for (const f of families.values()) {
+                if (!f.quotaSetup)
+                    continue;
+                const setup = rt.quotaSetup(f.id);
+                out.push({ family: f.id, summary: setup.summary, plan: await setup.plan() });
+            }
+            return out;
+        },
+        quotaSetup(familyId) {
+            const f = familyOf(familyId);
+            const setup = f.quotaSetup;
+            if (!setup)
+                throw new UserError(`${f.title} needs no quota setup`);
+            // One rule for every adapter: a setup that throws is reported, never crashes the caller. The message
+            // is the error's own text; setup implementations must not put file contents into it.
+            const blocked = (err) => ({
+                status: 'blocked',
+                file: '',
+                diff: '',
+                message: err?.message ?? String(err),
+            });
+            return {
+                family: f.id,
+                summary: setup.summary,
+                // Promise.resolve().then also catches a setup that throws synchronously.
+                plan: () => Promise.resolve()
+                    .then(() => setup.plan(readContext()))
+                    .catch(blocked),
+                apply: () => Promise.resolve()
+                    .then(() => setup.apply(readContext()))
+                    .catch(blocked),
+                teardown: () => Promise.resolve()
+                    .then(() => setup.teardown(readContext()))
+                    .catch((err) => ({
+                    ok: false,
+                    message: err?.message ?? String(err),
+                })),
+            };
+        },
+        async createAccount(familyId, name, o = {}) {
+            const family = familyOf(familyId);
+            const alias = o.alias?.trim() || undefined;
+            const ref = `${family.id}:${name}`;
+            if (alias) {
+                const problem = rt.aliasProblem(alias, ref);
+                if (problem)
+                    throw new UserError(`${problem}; nothing was created`, { code: 'alias-invalid' });
+            }
+            const created = await createAccount({
+                family,
+                name,
+                api: Boolean(o.api),
+                home: paths.home,
+                bus,
+                accounts: await discoverAccounts(family, paths.home, ignore),
+            });
+            if (alias) {
+                try {
+                    // An alias that already starts this Account keeps its arguments; creating the Account does not change them.
+                    const r = await addConfigAlias(paths.configFile, alias, created.account.ref, aliasArgs(ownAlias(alias)));
+                    config.aliases = r.aliases;
+                    created.alias = {
+                        name: alias,
+                        added: true,
+                        ...(r.status === 'exists' ? { message: 'already in the config' } : {}),
+                    };
+                }
+                catch (err) {
+                    created.alias = {
+                        name: alias,
+                        added: false,
+                        message: `${created.account.ref} was created, but the alias was not added: ${err.message}`,
+                    };
+                }
+            }
+            const files = await rt.writeShellInitFiles();
+            if (files.length)
+                created.shellInitFiles = files;
+            created.ok = created.ok && created.alias?.added !== false && files.every((f) => f.ok);
+            return created;
+        },
+        async addAlias(alias, target, args = []) {
+            const bad = aliasProblem(alias);
+            if (bad)
+                throw new UserError(`alias "${alias}" ${bad} (it becomes a shell function name)`);
+            // Resolve first so the config only ever names an Account that exists, by its ref.
+            const account = resolveRef(target, await accounts(), aliasRefs(config.aliases));
+            const r = await addConfigAlias(paths.configFile, alias, account.ref, args);
+            config.aliases = r.aliases;
+            return aliasEdit(alias, r.status, r.aliases[alias]);
+        },
+        async removeAlias(alias) {
+            const before = ownAlias(alias);
+            const r = await removeConfigAlias(paths.configFile, alias);
+            config.aliases = r.aliases;
+            return aliasEdit(alias, r.status, r.status === 'removed' ? before : undefined);
+        },
+        aliasProblem(alias, ref) {
+            const bad = aliasProblem(alias);
+            if (bad)
+                return `alias "${alias}" ${bad} (it becomes a shell function name)`;
+            const value = ownAlias(alias);
+            const taken = value === undefined ? undefined : aliasAccount(value);
+            if (taken !== undefined && taken !== ref)
+                return `alias "${alias}" already starts ${taken}; pick another name`;
+            return null;
+        },
+        async shellInitScript() {
+            const list = await accounts();
+            // Routing helps only a Family that can route and has somewhere else to route to (spec §3.15).
+            const routes = config.resumeRouting
+                ? [...families.values()]
+                    .filter((f) => f.resumedSession && f.sessionWrittenAt && list.some((a) => a.family === f.id && !a.isMain))
+                    .map((f) => ({ family: f.id, bin: f.bin, selectVar: f.selectVar }))
+                : [];
+            return shellInitScript(list, config.aliases, routes);
+        },
+        async writeShellInitFiles(shells = SHELLS) {
+            const out = [];
+            for (const shell of shells) {
+                const file = config.shellInitFile?.[shell];
+                if (file)
+                    out.push(await writeShellInitFile(shell, file, paths.home, await rt.shellInitScript(shell)));
+            }
+            return out;
+        },
+        async prepareLaunch(ref, userArgs, command) {
+            const account = resolveRef(ref, await accounts(), aliasRefs(config.aliases));
+            return prepareLaunch({
+                account,
+                family: familyOf(account.family),
+                baseEnv: env,
+                accountArgs: config.accounts?.[account.ref]?.args ?? [],
+                // An alias's arguments come before the user's; the Family sees both as the user's choice (ADR-0005).
+                userArgs: command === 'run' ? [...aliasArgs(aliasValue(ref)), ...userArgs] : userArgs,
+                command,
+                bus,
+            });
+        },
+        async resumeLaunch(familyId, userArgs) {
+            const family = familyOf(familyId);
+            if (!family.resumedSession || !family.sessionWrittenAt)
+                throw new UserError(`${family.title} sessions cannot be routed; start an account yourself with \`sideby run <account> -- …\``);
+            const host = { family, bin: family.bin, args: [...userArgs], env };
+            // A select variable already set means an Account was chosen on purpose: run the Host as it is.
+            if (env[family.selectVar])
+                return { launch: host };
+            const route = await findResumeRoute(family, await accounts(), userArgs);
+            const id = route.sessionId ? { sessionId: route.sessionId } : {};
+            if (!route.account || route.account.isMain)
+                return { launch: host, ...id };
+            return {
+                launch: await rt.prepareLaunch(route.account.ref, userArgs, 'run'),
+                ...id,
+                account: route.account,
+            };
+        },
+        async quota(account) {
+            if (account.kind === 'api')
+                return { status: 'unavailable', reason: 'api-account' };
+            const f = familyOf(account.family);
+            if (!f.readQuota)
+                return { status: 'unavailable', reason: 'no-source' };
+            try {
+                return await f.readQuota(account, readContext());
+            }
+            catch (err) {
+                return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
+            }
+        },
+        async usage(account) {
+            const f = familyOf(account.family);
+            if (!f.readUsage)
+                return { status: 'unavailable', reason: 'no-source' };
+            try {
+                return await f.readUsage(account, readContext());
+            }
+            catch (err) {
+                return { status: 'unavailable', reason: 'unrecognized', detail: err.message };
+            }
+        },
+        async handoff(familyId, o = {}) {
+            const f = familyOf(familyId);
+            const list = (await accounts()).filter((a) => a.family === f.id);
+            if (!f.readQuota)
+                throw new UserError(`${f.title} has no public quota source, so sideby cannot tell which account has room; pick one yourself: ${list.map((a) => `sideby run ${a.ref}`).join(', ') || `sideby new ${f.id} <name>`}`, { code: 'no-quota-source' });
+            if (list.length === 0)
+                throw new UserError(`no ${f.title} accounts yet; create one with \`sideby new ${f.id} <name>\``, {
+                    code: 'no-accounts',
+                });
+            // Only the login state and Quota: no identity, model or Host lookups are needed to rank.
+            const loginOf = async (a) => {
+                if (a.kind === 'api')
+                    return 'not-needed';
+                try {
+                    return (await f.loginState?.(a)) ?? 'unknown';
+                }
+                catch {
+                    return 'unknown';
+                }
+            };
+            const candidates = await Promise.all(list.map(async (a) => {
+                const [login, quota] = await Promise.all([loginOf(a), rt.quota(a)]);
+                return { ref: a.ref, name: a.name, isMain: a.isMain, kind: a.kind, login, quota };
+            }));
+            return planHandoff(f.id, candidates, readContext().now, o);
+        },
+        readContext,
+    };
+    return rt;
+}