allaboard 0.0.0-stage → 0.4.0

package/dist/core/flows/update.js

@@ -0,0 +1,370 @@
+import { isNewer, isVersion } from "../../semver.js";
+import { errorName } from "../../values.js";
+import { parseBang } from "../commands.js";
+import * as texts from "../texts.js";
+import { fill, named } from "../texts.js";
+import { whyUnknown } from "../updates.js";
+import { isCancelled, logger } from "./talk.js";
+/** Wall-clock seconds as `HH:MM` on the daemon's clock, for "checked 14:05". */
+export function clockTime(seconds) {
+    const at = new Date(seconds * 1000);
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${pad(at.getHours())}:${pad(at.getMinutes())}`;
+}
+export function updating(deps, updates, talk) {
+    const { chat, sessions, state, names } = deps;
+    const { host } = updates;
+    /** Why the copy updates outside the chat, as a sentence, for a markup. */
+    const outside = (refusal, markup) => {
+        const reason = refusal.kind === "not-global"
+            ? fill(texts.UPDATE_REASON_NOT_GLOBAL, { path: chat.escape(refusal.folder, markup) })
+            : refusal.kind === "link"
+                ? texts.UPDATE_REASON_LINK
+                : fill(texts.UPDATE_REASON_UNPUBLISHED, { version: refusal.version });
+        return fill(named(texts.UPDATE_OUTSIDE, names), { reason });
+    };
+    const notAService = () => named(texts.UPDATE_NOT_A_SERVICE, names);
+    /** The sentence of an install that left the version it was asked for, or did not end well. */
+    const notInstalled = (outcome, version) => {
+        const installed = updates.installed;
+        if (outcome.kind === "mismatch") {
+            return outcome.found === null
+                ? fill(texts.UPDATE_UNREADABLE, { installed })
+                : fill(texts.UPDATE_MISMATCH, { found: outcome.found, latest: version, installed });
+        }
+        const { failure } = outcome;
+        if (failure.kind === "network")
+            return fill(texts.UPDATE_FAILED_NETWORK, { installed });
+        const log = chat.escape(host.logFile, "notice");
+        if (failure.kind === "permission") {
+            const folder = failure.path === null ? "the folder it installs into" : failure.path;
+            return fill(texts.UPDATE_FAILED_PERMISSION, {
+                folder: chat.escape(folder, "notice"),
+                installed,
+                log,
+            });
+        }
+        return fill(texts.UPDATE_FAILED_OTHER, { status: failure.status ?? "unknown", installed, log });
+    };
+    /** The sentences of the instances an install's restart did not reach, one a line; null when none. */
+    const notRestarted = (failures) => {
+        if (failures.length === 0)
+            return null;
+        return failures
+            .map(({ instance, status }) => {
+            const reason = status === null
+                ? texts.UPDATE_OTHER_NO_MANAGER
+                : fill(texts.UPDATE_OTHER_STATUS, { status });
+            return instance === null
+                ? fill(texts.UPDATE_OTHER_FAILED_DEFAULT, { reason })
+                : fill(texts.UPDATE_OTHER_FAILED, { name: instance, reason });
+        })
+            .join("\n");
+    };
+    /** What `NotUpdatable` says to the owner when a click could not prove the copy. */
+    const unproven = (refusal) => refusal.kind === "npm"
+        ? { text: fill(texts.UPDATE_UNKNOWN, { reason: whyUnknown(refusal.failure) }), failed: true }
+        : { text: outside(refusal, "notice"), failed: false };
+    /** The offer rewritten into `text`; a chat that refuses is logged, the update goes on. */
+    const rewrite = async (channel, list, text) => {
+        if (talk.stopped)
+            return;
+        try {
+            await chat.channel(channel).rewrite(list, text);
+        }
+        catch (error) {
+            if (isCancelled(error))
+                throw error;
+            logger.warning(`could not rewrite the update offer in ${channel}: ${errorName(error)}`);
+        }
+    };
+    /**
+     * Records the message the next start rewrites, before the stop that ends this process is asked
+     * (a missing note is no reason to keep the daemon from restarting).
+     */
+    const remember = (notice) => {
+        try {
+            state.setRestartNotice(notice);
+        }
+        catch (error) {
+            logger.warning(`could not record the restart notice: ${errorName(error)}`);
+        }
+    };
+    /** A `!allaboard restart` is being answered or has asked the stop. */
+    let restartAsked = false;
+    /** `install` that never throws: a host that fails to run npm at all is an install that failed. */
+    const install = async (copy, version) => {
+        try {
+            return await host.install(copy, version, updates.installing);
+        }
+        catch (error) {
+            logger.error(`the install could not run: ${errorName(error)}`);
+            return { kind: "failed", failure: { kind: "other", status: null } };
+        }
+    };
+    async function click(pick) {
+        const { channel, list, version } = pick;
+        // The value of a control the chat drew from a version; anything else is not ours to install.
+        if (!isVersion(version)) {
+            logger.warning("ignored an update click that carries no version");
+            return;
+        }
+        const offer = channel !== null && list !== null ? { channel, list } : null;
+        // For the owner alone, leaving the offer as it is: another click is already at work on it. A
+        // click on the chat's own page has no message to answer on; that page shows the state.
+        const aside = async (text) => {
+            if (offer !== null && !talk.stopped)
+                await chat.channel(offer.channel).tell(text);
+        };
+        const running = updates.phase;
+        if (running.kind === "installing" || running.kind === "restarting") {
+            await aside(fill(texts.UPDATE_UNDER_WAY, { version: running.version }));
+            return;
+        }
+        if (sessions.draining) {
+            await aside(texts.UPDATE_DRAINING);
+            return;
+        }
+        // (sync) Claimed with the checks above, before the first await: a second click finds it. A
+        // stop that already cancelled the install refuses the claim.
+        if (!updates.begin(version)) {
+            await aside(texts.UPDATE_DRAINING);
+            return;
+        }
+        let settled = false;
+        let lock = null;
+        let unblock = null;
+        let restarting = false;
+        /** The click ended with `text`: on the offer, and on the page when it `failed`. */
+        const settle = async (text, failed) => {
+            settled = true;
+            if (failed)
+                updates.fail(version, text);
+            else
+                updates.abandon();
+            if (offer !== null)
+                await rewrite(offer.channel, offer.list, text);
+        };
+        try {
+            lock = await host.lock();
+            if (lock === null) {
+                settled = true;
+                updates.abandon();
+                await aside(texts.UPDATE_ELSEWHERE);
+                return;
+            }
+            if (sessions.draining) {
+                settled = true;
+                updates.abandon();
+                await aside(texts.UPDATE_DRAINING);
+                return;
+            }
+            const installed = updates.installed;
+            if (!isNewer(version, installed)) {
+                await settle(fill(texts.UPDATE_ALREADY_RUNS, { latest: installed }), false);
+                return;
+            }
+            const found = await updates.validate();
+            // A stop came while npm was asked (a drain, or one with none that cancelled the install):
+            // nothing is installed, and no sentence about npm is made of its answer to the stop.
+            if (found === null || updates.installing.aborted) {
+                settled = true;
+                updates.abandon();
+                await aside(texts.UPDATE_DRAINING);
+                return;
+            }
+            if ("swapping" in found) {
+                // Another process (a terminal's `npm install -g`) is replacing the copy this very moment.
+                settled = true;
+                updates.abandon();
+                await aside(texts.UPDATE_ELSEWHERE);
+                return;
+            }
+            if ("refusal" in found) {
+                const { text, failed } = unproven(found.refusal);
+                await settle(text, failed);
+                return;
+            }
+            if (!host.supervised()) {
+                await settle(notAService(), true);
+                return;
+            }
+            if (host.copyVersion(found.copy) === version) {
+                await settle(fill(texts.UPDATE_COPY_HOLDS, { latest: version, installed }), true);
+                return;
+            }
+            unblock = sessions.blockStarts();
+            const newer = updates.newer;
+            const underWay = newer !== null && isNewer(newer, version)
+                ? fill(texts.UPDATE_NEWER_SINCE, { latest: version, newer })
+                : fill(texts.UPDATE_INSTALLING, { latest: version });
+            if (offer !== null)
+                await rewrite(offer.channel, offer.list, underWay);
+            const outcome = await install(found.copy, version);
+            if (outcome.kind !== "installed") {
+                await settle(notInstalled(outcome, version), true);
+                return;
+            }
+            let failures = [];
+            try {
+                failures = await host.restartOthers(found.copy);
+            }
+            catch (error) {
+                logger.error(`could not restart the other instances: ${errorName(error)}`);
+            }
+            // The block stays up until the process ends: no agent starts between the swap and the exit.
+            restarting = true;
+            settled = true;
+            const note = notRestarted(failures);
+            updates.restarting(version, note);
+            if (offer !== null) {
+                const installedText = fill(texts.UPDATE_INSTALLED, { latest: version });
+                await rewrite(offer.channel, offer.list, note === null ? installedText : `${installedText}\n${note}`);
+                // An offer that names an instance still to restart by hand keeps that line: the next
+                // start's rewrite would replace it with `Updated to…`.
+                if (note === null)
+                    remember({ channel: offer.channel, message: offer.list, version });
+            }
+            host.restart();
+        }
+        finally {
+            if (!settled)
+                updates.abandon();
+            if (!restarting)
+                unblock?.();
+            await lock?.release();
+        }
+    }
+    return {
+        async show() {
+            await updates.current();
+            const installed = updates.installed;
+            const time = clockTime(updates.checkedAt ?? deps.now());
+            const failure = updates.checkFailure;
+            const newer = updates.newer;
+            const lines = [
+                failure !== null
+                    ? fill(texts.UPDATE_STATUS_UNKNOWN, { installed, reason: whyUnknown(failure), time })
+                    : newer !== null
+                        ? fill(texts.UPDATE_STATUS_NEWER, { installed, latest: newer, time })
+                        : fill(texts.UPDATE_STATUS_CURRENT, { installed, time }),
+            ];
+            const refusal = updates.refusal;
+            if (refusal !== null)
+                lines.push(outside(refusal, "reference"));
+            else if (updates.canUpdate && !host.supervised())
+                lines.push(notAService());
+            return lines.join("\n");
+        },
+        async update(channel) {
+            const running = updates.phase;
+            if (running.kind === "installing" || running.kind === "restarting") {
+                await talk.inChannel(channel, fill(texts.UPDATE_UNDER_WAY, { version: running.version }));
+                return;
+            }
+            if (sessions.draining) {
+                await talk.inChannel(channel, texts.UPDATE_DRAINING);
+                return;
+            }
+            await updates.check();
+            const refusal = updates.refusal;
+            const failure = updates.checkFailure;
+            const copy = updates.copy;
+            const newer = updates.newer;
+            if (refusal !== null) {
+                await talk.inChannel(channel, outside(refusal, "notice"));
+            }
+            else if (failure !== null) {
+                await talk.inChannel(channel, fill(texts.UPDATE_UNKNOWN, { reason: whyUnknown(failure) }));
+            }
+            else if (newer !== null && copy === null) {
+                // A newer version, and no answer yet about the copy: it is being replaced right now.
+                await talk.inChannel(channel, texts.UPDATE_ELSEWHERE);
+            }
+            else if (newer === null || copy === null) {
+                await talk.inChannel(channel, fill(texts.UPDATE_LATEST, { installed: updates.installed }));
+            }
+            else if (!host.supervised()) {
+                await talk.inChannel(channel, notAService());
+            }
+            else {
+                await chat.channel(channel).offer({
+                    type: "update",
+                    from: updates.installed,
+                    to: newer,
+                    changelog: host.changelog(newer),
+                    sharing: host.sharing(copy),
+                }, fill(texts.UPDATE_OFFER, { installed: updates.installed, latest: newer }));
+            }
+        },
+        async restart(channel) {
+            const running = updates.phase;
+            if (running.kind === "installing" || running.kind === "restarting") {
+                await talk.inChannel(channel, fill(texts.UPDATE_UNDER_WAY, { version: running.version }));
+                return;
+            }
+            if (sessions.draining || restartAsked) {
+                await talk.inChannel(channel, texts.RESTARTING);
+                return;
+            }
+            // (sync) Claimed before the first await: a second `!allaboard restart` (a double send, an
+            // event delivered twice) finds it, so the stop is asked and recorded once.
+            restartAsked = true;
+            let asked = false;
+            try {
+                if (await host.updateHeld()) {
+                    // Another process is replacing the copy: a restart now would start from half of it.
+                    await talk.inChannel(channel, texts.UPDATE_ELSEWHERE);
+                }
+                else if (!host.supervised()) {
+                    await talk.inChannel(channel, notAService());
+                }
+                else {
+                    const message = await talk.postInChannel(channel, texts.UPDATE_RESTART);
+                    if (message !== null)
+                        remember({ channel, message, version: null });
+                    host.restart();
+                    asked = true;
+                }
+            }
+            finally {
+                // A restart that was refused leaves the next one free; one that asked the stop is the last.
+                if (!asked)
+                    restartAsked = false;
+            }
+        },
+        // The drain waits for a click, and a stop with no drain ends its install (`Updates.track`).
+        picked: (pick) => updates.track(() => click(pick)),
+        async notice(message) {
+            // (sync) Decided and recorded before anything is awaited: the caller starts the message's
+            // own handling right after, and it must take its place in line first (`messages.ts`).
+            const version = updates.noticeDue(state.updateNotice);
+            if (version === null)
+                return;
+            try {
+                state.setUpdateNotice(version);
+            }
+            catch (error) {
+                logger.warning(`could not record the update told of: ${errorName(error)}`);
+                return;
+            }
+            // Asking about allaboard is being told; the line would repeat the answer.
+            const typed = message.literal ? null : (parseBang(message.text) ?? parseBang(message.plain));
+            if (typed?.kind === "allaboard")
+                return;
+            const text = fill(texts.UPDATE_NOTICE, { latest: version, installed: updates.installed });
+            // A message of the channel opens a thread that has no reply yet, and a chat may show a
+            // line for the owner alone in a thread only once it is active: the line goes to the
+            // channel. A chat that refuses the line does not hold the message back.
+            try {
+                if (message.topLevel)
+                    await chat.channel(message.ref.channel).tell(text);
+                else
+                    await talk.tell(message.ref, text);
+            }
+            catch (error) {
+                logger.warning(`could not tell the owner of ${version}: ${errorName(error)}`);
+            }
+        },
+    };
+}

package/dist/core/flows/words.js

@@ -0,0 +1,171 @@
+import { helpText, WORD } from "../commands.js";
+import { guideText } from "../guide.js";
+import { BypassUnavailable } from "../sessions/errors.js";
+import * as texts from "../texts.js";
+import { fill, named } from "../texts.js";
+import { channelStatus } from "./status.js";
+export function wordFlow(deps, talk, others) {
+    const { chat, agent, sessions, names } = deps;
+    const status = channelStatus(deps, talk);
+    // The words this agent and this chat cannot serve: each is refused when typed, and `!help`
+    // does not list it.
+    const unserved = new Set();
+    if (agent.capabilities.permissionModes.bypass === null)
+        unserved.add(WORD.bypass);
+    if (!agent.capabilities.sessionListing)
+        unserved.add(WORD.resume);
+    if (!chat.capabilities.fileUpload)
+        unserved.add(WORD.open);
+    // A daemon built without a way to update itself offers no `!allaboard`.
+    const allaboard = others.allaboard;
+    if (allaboard === undefined)
+        unserved.add(WORD.allaboard);
+    return async (ref, message, command, { session, outside }) => {
+        const { channel, thread } = ref;
+        const where = session === null ? null : thread;
+        const quiet = session !== null;
+        const showHelp = async (query) => {
+            if (session !== null)
+                await session.ensureConnected();
+            const commands = session === null ? null : session.commands;
+            await talk.say(channel, where, helpText(commands, query, (text) => chat.escape(text, "reference"), names, agent.capabilities.commands, unserved, agent.capabilities.folderTrust), { ownerOnly: quiet });
+        };
+        switch (command.kind) {
+            case "help":
+                await showHelp(command.query);
+                return;
+            case "invalid":
+                // A mistyped word gets the full list, which shows how each word is written.
+                await showHelp("");
+                return;
+            case "guide": {
+                const have = agent.capabilities;
+                const offered = {
+                    folderTrust: have.folderTrust,
+                    models: have.models,
+                    efforts: have.effortLevels.length > 0,
+                    bypass: have.permissionModes.bypass !== null,
+                    commands: have.commands,
+                    questions: have.questions,
+                    backgroundTasks: have.backgroundTasks,
+                    sessionListing: have.sessionListing,
+                    fileUpload: chat.capabilities.fileUpload,
+                    updates: allaboard !== undefined,
+                };
+                await talk.say(channel, where, guideText(names, offered), { ownerOnly: quiet });
+                return;
+            }
+            case "bind":
+                if (session !== null || (outside && command.path)) {
+                    await talk.tell(ref, fill(texts.WORD_IN_THREAD, { word: WORD.bind }));
+                }
+                else if (command.path) {
+                    await others.bind.to(channel, command.path);
+                }
+                else {
+                    await others.bind.list(channel);
+                }
+                return;
+            case "bypass": {
+                if (session === null) {
+                    await talk.inChannel(channel, texts.BYPASS_TOP_LEVEL);
+                    return;
+                }
+                let switched;
+                try {
+                    switched = await session.switchBypass(command.on);
+                }
+                catch (error) {
+                    if (!(error instanceof BypassUnavailable))
+                        throw error;
+                    await talk.tell(ref, named(texts.BYPASS_UNAVAILABLE, names));
+                    return;
+                }
+                if (!switched) {
+                    // Start writes the setup's box over the switch (`applySetup`): one flipped before
+                    // it would not hold, so the word changed nothing.
+                    await talk.tell(ref, texts.BYPASS_BEFORE_START);
+                }
+                else {
+                    // Both: the line says what changed and is gone on reload, the mark stays.
+                    await talk.acknowledge(ref, message);
+                    await talk.tell(ref, command.on ? texts.BYPASS_ON_THREAD : named(texts.BYPASS_OFF_THREAD, names));
+                }
+                return;
+            }
+            case "status":
+                if (session === null)
+                    await status(channel);
+                else
+                    await talk.say(channel, thread, await session.status(), { ownerOnly: true });
+                return;
+            case "stop":
+                if (outside) {
+                    await talk.tell(ref, texts.STOP_OUTSIDE_SESSION);
+                }
+                else if (session === null) {
+                    const stopped = await sessions.stopChannel(channel);
+                    // null: only a hold was cancelled somewhere in the channel (`Not sent.`, from its
+                    // own waiter); no second notice, since nothing the agent was doing stopped.
+                    if (stopped !== null) {
+                        await talk.inChannel(channel, stopped ? texts.STOPPED_CHANNEL : texts.NOTHING_TO_STOP);
+                    }
+                }
+                else {
+                    // Either answer is a post that stays in the thread: a line for the owner alone is
+                    // gone on reload, and the root's mark alone does not say a stop was received. null:
+                    // only a hold was cancelled, which already said `Not sent.` from its own waiter.
+                    const stopped = await session.stop();
+                    if (stopped) {
+                        // The answer goes under the ending and the footer of the reply the stop cut
+                        // short, which may be a message of its own.
+                        await session.stopLanded();
+                    }
+                    if (stopped !== null) {
+                        await talk.tell(ref, stopped ? texts.STOPPED_THREAD : texts.NOTHING_TO_STOP_THREAD, {
+                            stays: true,
+                        });
+                    }
+                }
+                return;
+            case "open":
+                if (session === null) {
+                    await talk.inChannel(channel, texts.OPEN_TOP_LEVEL);
+                }
+                else if (!chat.capabilities.fileUpload || chat.openFile === undefined) {
+                    await talk.tell(ref, named(texts.OPEN_UNAVAILABLE, names));
+                }
+                else {
+                    await chat.openFile(ref, session.directory, command.target);
+                }
+                return;
+            case "allaboard":
+                if (allaboard === undefined) {
+                    await showHelp("");
+                }
+                else if (command.action === "show") {
+                    await talk.say(channel, where, await allaboard.show(), { ownerOnly: quiet });
+                }
+                else if (session !== null || outside) {
+                    // The offer lives in the channel, so a word that makes one is refused in a thread.
+                    const word = `${WORD.allaboard} ${command.action}`;
+                    await talk.tell(ref, fill(texts.WORD_IN_THREAD, { word }));
+                }
+                else if (command.action === "update") {
+                    await allaboard.update(channel);
+                }
+                else {
+                    await allaboard.restart(channel);
+                }
+                return;
+            case "resume":
+                if (session !== null || outside) {
+                    await talk.tell(ref, fill(texts.WORD_IN_THREAD, { word: WORD.resume }));
+                }
+                else {
+                    await others.resume.word(ref, command.target);
+                }
+                return;
+        }
+    };
+}

package/dist/core/folders.js

@@ -0,0 +1,93 @@
+/**
+ * `!bind` alone: the folders under the allowed root where a session can start.
+ *
+ * Claude Code has no folder picker: the terminal starts in the folder it is launched from. The list
+ * holds the allowed root and the folders two levels below it that Claude Code trusts, since a
+ * session starts nowhere else. It never descends into a git repository: its subfolders belong to
+ * that one project. The Bind button rows are the chat provider's.
+ */
+import { lstat, opendir, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { getLogger } from "../log.js";
+import { compareCodePoints } from "../text.js";
+import { ABSENT } from "./paths.js";
+export const logger = getLogger("allaboard.core.folders");
+export const FOLDER_ROWS = 20;
+export const FOLDER_DEPTH = 2;
+// Each trust check reads the filesystem: a batch at a time, so a root with many untrusted folders
+// lists in a few rounds, and the check stops soon after the rows are filled.
+export const TRUST_BATCH = 8;
+function code(error) {
+    return error?.code;
+}
+async function isFolder(directory, name) {
+    // A symlink could lead outside the root; hidden folders are tooling (.git, .venv, .claude).
+    if (name.startsWith("."))
+        return false;
+    try {
+        // `lstat` does not follow a link: a real directory is the only thing that passes.
+        return (await lstat(join(directory, name))).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function descends(folder) {
+    // `.git` is a directory in a repository and a file in a worktree. A folder that cannot be
+    // searched fails here with more than "not there": it has nothing to list.
+    try {
+        await stat(join(folder, ".git"));
+        return false;
+    }
+    catch (error) {
+        return ABSENT.has(code(error));
+    }
+}
+async function children(folder) {
+    let names;
+    try {
+        names = (await readdir(folder)).toSorted(compareCodePoints);
+    }
+    catch (error) {
+        // A subfolder the daemon may not open (macOS privacy, permissions) lists nothing.
+        logger.debug(`skipped an unreadable folder: ${code(error)}`);
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        if (await isFolder(folder, name))
+            found.push(join(folder, name));
+    }
+    return found;
+}
+/** The root, then its folders, then theirs: the higher levels come first. */
+export async function foldersWithin(root) {
+    // An unreadable root raises: an empty list would send the owner to trust folders instead.
+    await (await opendir(root)).close();
+    const levels = [[root]];
+    for (let depth = 0; depth < FOLDER_DEPTH; depth += 1) {
+        const next = [];
+        for (const folder of levels[levels.length - 1]) {
+            if (await descends(folder))
+                next.push(...(await children(folder)));
+        }
+        levels.push(next);
+    }
+    return levels.flat();
+}
+/**
+ * Trusted folders under `root`, the higher levels first, at most `FOLDER_ROWS + 1`: one past the
+ * rows shown is enough to say that more exist, and stops the trust checks there.
+ */
+export async function bindableFolders(root, trusted) {
+    const candidates = await foldersWithin(root);
+    const found = [];
+    for (let start = 0; start < candidates.length; start += TRUST_BATCH) {
+        const batch = candidates.slice(start, start + TRUST_BATCH);
+        const verdicts = await Promise.all(batch.map((folder) => trusted(folder)));
+        found.push(...batch.filter((_folder, index) => verdicts[index]));
+        if (found.length > FOLDER_ROWS)
+            return found.slice(0, FOLDER_ROWS + 1);
+    }
+    return found;
+}