@jungjaehoon/mama-os 0.78.0 → 0.79.0

package/dist/cli/runtime/telegram-pairing.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.botName = botName;
+exports.pairOwner = pairOwner;
+exports.bindCommonGroup = bindCommonGroup;
+exports.confirmUpdates = confirmUpdates;
+const node_crypto_1 = require("node:crypto");
+const prompt_js_1 = require("../prompt.js");
+/** At most this many people get a code in one window; anyone after that is ignored. */
+const MAX_CODES = 10;
+/** How long init waits for /bind before it stops and says how to continue. */
+const BIND_WAIT_MS = 15 * 60_000;
+/** A call whose network failure ends init with a sentence, not an unnamed error. */
+async function request(options, method, params) {
+    try {
+        return await options.call(options.token, method, params);
+    }
+    catch (error) {
+        const cause = error.cause?.code;
+        const name = error instanceof Error ? error.name : 'Error';
+        throw new prompt_js_1.CliInputError(`Could not reach Telegram (${typeof cause === 'string' ? cause : name}); check the network and run the install command again.`);
+    }
+}
+/** Each getUpdates waits up to five seconds for news; doctor's call gives up after eight. */
+async function updates(options, offset, pollSeconds = 5) {
+    const reply = await request(options, 'getUpdates', {
+        offset: String(offset),
+        timeout: String(pollSeconds),
+        allowed_updates: JSON.stringify(['message']),
+    });
+    if (reply.ok === true)
+        return reply.result ?? [];
+    // Telegram lets one reader at a time take a bot's updates; init and a daemon would keep
+    // stopping each other.
+    if (reply.error_code === 409)
+        throw new prompt_js_1.CliInputError("Another program is reading this bot's messages (another MAMA install?). Use a bot only this install uses, then run the install command again.");
+    throw new prompt_js_1.CliInputError(`Telegram refused to hand over the bot's messages (${String(reply.error_code ?? 'no code')}).`);
+}
+/** The bot's @name, which the pairing instructions give. */
+async function botName(options) {
+    const reply = await request(options, 'getMe', {});
+    const name = reply.result?.username;
+    if (reply.ok !== true || typeof name !== 'string')
+        throw new prompt_js_1.CliInputError('Telegram refused the bot token; copy it again from BotFather.');
+    return name;
+}
+async function send(options, chatId, text) {
+    const reply = await request(options, 'sendMessage', { chat_id: String(chatId), text });
+    return reply.ok === true;
+}
+/**
+ * Make the person setting up the first owner without a typed user ID: everyone who messages the
+ * bot privately while init waits gets a code, and the code `ask` returns names the owner. A code
+ * reaches only the chat it was sent to, so entering it proves that chat is this person's.
+ * Messages the bot held from before are dropped first: they were not sent to this setup, and an
+ * old /bind would otherwise name a group without a new word from the owner.
+ */
+async function pairOwner(options) {
+    // offset -1 returns only the newest held update and drops the rest; the next poll drops it too.
+    const held = await updates(options, -1, 0);
+    let offset = held.length > 0 ? held[held.length - 1].update_id + 1 : 0;
+    options.write(`Open Telegram and send @${options.botUsername} a new private message (one sent before now is dropped). It answers with a pairing code; enter it on the setup page.`);
+    const codes = new Map();
+    const senders = new Set();
+    // Group messages read while waiting for the code: a /bind sent early must not be lost.
+    const groupMessages = [];
+    let stopped = false;
+    let failure;
+    const pollingFailed = new AbortController();
+    const polling = (async () => {
+        while (!stopped) {
+            for (const update of await updates(options, offset)) {
+                offset = Math.max(offset, update.update_id + 1);
+                const message = update.message;
+                if (message?.chat?.type === 'group' || message?.chat?.type === 'supergroup')
+                    groupMessages.push(update);
+                if (!message?.chat || message.chat.type !== 'private' || !message.from)
+                    continue;
+                if (message.from.is_bot)
+                    continue;
+                const sender = String(message.from.id);
+                if (senders.has(sender) || senders.size >= MAX_CODES)
+                    continue;
+                let code;
+                do
+                    code = String((0, node_crypto_1.randomInt)(100_000, 1_000_000));
+                while (codes.has(code));
+                senders.add(sender);
+                codes.set(code, sender);
+                const sent = await send(options, message.chat.id, `Your MAMA pairing code: ${code}\nEnter it on the setup page.`);
+                // A chat that refuses the bot (blocked it, account gone) cannot show its code; that sender
+                // may unblock the bot and write again.
+                if (!sent) {
+                    senders.delete(sender);
+                    codes.delete(code);
+                    options.write('Telegram refused to deliver a pairing code to one chat. If it was yours, unblock the bot and send it another message.');
+                }
+            }
+        }
+    })().catch((error) => {
+        failure = error;
+        pollingFailed.abort();
+    });
+    let ownerId;
+    try {
+        while (ownerId === undefined) {
+            let answer;
+            try {
+                answer = (await options.ask('Pairing code (from the bot)', pollingFailed.signal)).trim();
+            }
+            catch (error) {
+                throw failure ?? error;
+            }
+            if (failure !== undefined)
+                throw failure;
+            ownerId = codes.get(answer);
+            if (ownerId === undefined)
+                options.write('That is not a code the bot sent; enter the code from its latest message.');
+        }
+    }
+    finally {
+        stopped = true;
+        await polling;
+    }
+    // Read after polling stopped, so every update it handled is counted.
+    return { ownerId, offset, groupMessages };
+}
+/** A `/bind` command at the start of a message, unaddressed or addressed to this bot. */
+function isBind(message, botUsername) {
+    const first = message.entities?.[0];
+    if (!message.text || first?.type !== 'bot_command' || first.offset !== 0)
+        return false;
+    const [name, addressee] = message.text.slice(1, first.length).split('@', 2);
+    return (name.toLowerCase() === 'bind' &&
+        (addressee === undefined || addressee.toLowerCase() === botUsername.toLowerCase()));
+}
+/**
+ * The common channel without a typed chat ID: the paired owner sends /bind in the group, and
+ * that group becomes it. Anyone else's message, or a /bind in a private chat, is ignored.
+ */
+async function bindCommonGroup(options) {
+    options.write(`Add @${options.botUsername} to the group for common work as an administrator (so it reads the group), then send /bind in that group.`);
+    const now = options.now ?? Date.now;
+    const deadline = now() + (options.waitMs ?? BIND_WAIT_MS);
+    let offset = options.offset;
+    let batch = options.earlier ?? [];
+    let toldAnonymous = false;
+    for (;;) {
+        for (const update of batch) {
+            offset = Math.max(offset, update.update_id + 1);
+            const message = update.message;
+            if (!message?.chat || !message.from)
+                continue;
+            if (message.chat.type !== 'group' && message.chat.type !== 'supergroup')
+                continue;
+            if (!isBind(message, options.botUsername))
+                continue;
+            // An anonymous administrator's message names the group, not the person, so it cannot count.
+            if (message.sender_chat !== undefined && !toldAnonymous) {
+                toldAnonymous = true;
+                options.write("A /bind came from an anonymous administrator, so it cannot count as yours. Turn off 'Remain anonymous' for yourself in the group's administrator settings and send /bind again.");
+            }
+            if (message.sender_chat !== undefined || String(message.from.id) !== options.ownerId)
+                continue;
+            // MAMA posts reports and notices there, so a group the bot cannot post in cannot be it.
+            if (await send(options, message.chat.id, "This group is now MAMA's common channel."))
+                return { chatId: String(message.chat.id), offset };
+            options.write('Telegram refused to let the bot post in that group. Let it post there, then send /bind again.');
+        }
+        if (now() >= deadline)
+            throw new prompt_js_1.CliInputError('No /bind arrived in the group; run the install command again to pair again.');
+        batch = await updates(options, offset);
+    }
+}
+/**
+ * Mark every update init read as handled, so the daemon's first poll does not take the pairing
+ * messages for an owner's questions.
+ */
+async function confirmUpdates(options) {
+    if (options.offset === 0)
+        return;
+    await updates(options, options.offset, 0);
+}
+//# sourceMappingURL=telegram-pairing.js.map

package/dist/cli/runtime/telegram-pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-pairing.js","sourceRoot":"","sources":["../../../src/cli/runtime/telegram-pairing.ts"],"names":[],"mappings":"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"}

package/dist/cli/runtime/update-journal.d.ts

@@ -0,0 +1,135 @@
+import type { LockPaths } from './daemon-control.js';
+/**
+ * `mama update`'s journal (docs/development/work/update.md, PR 3). The parent (the old CLI) writes
+ * it before it stops anything; the child (the new CLI) carries it on; a rollback, from either or
+ * from `mama update --rollback` after a killed updater, reads only it. Under runtime/, which the
+ * agents' native reads deny and a backup does not archive.
+ */
+/**
+ * prepare: the parent's steps 6-9; candidate: the new version boots with its claims held;
+ * committed: it runs at the new version and is never rolled back; rollback: the old version is
+ * being put back, and boots without a hold.
+ */
+export type UpdatePhase = 'prepare' | 'candidate' | 'committed' | 'rollback';
+export interface UpdateJournal {
+    readonly format: 'mama-update';
+    phase: UpdatePhase;
+    /** The step last begun (the step table's numbers). */
+    step: number;
+    readonly from: string;
+    readonly to: string;
+    /** npm's prefix, from the package's path. */
+    readonly prefix: string;
+    /** What `npm config get registry` answered at step 2. */
+    readonly registry: string;
+    /** start.sh's pinned Node. */
+    readonly nodePath: string;
+    /** The MAMA command inside the package (`dist/cli/index.js`). */
+    readonly packageCli: string;
+    /** The previous CLI's absolute path once the old package is set aside at step 8. */
+    readonly previousCli: string;
+    /** Step 3's doctor failures, which step 11 compares with its own. */
+    readonly failuresBefore: readonly DoctorFailure[];
+    /**
+     * The snapshot's archive, named before step 7's backup starts so an update cut off mid-backup
+     * still finds what it left; it is a complete snapshot only once `schemaBefore` is set.
+     */
+    snapshot: string | null;
+    /** That backup's staging folder, removed with the archive and its partial file. */
+    snapshotStaging: string | null;
+    /** Each migration source's stored version when the snapshot was taken. */
+    schemaBefore: readonly {
+        name: string;
+        stored: number;
+    }[] | null;
+    /** The newest mailbox input when the snapshot was taken; a restore drops those after it. */
+    lastInputId: number | null;
+    /** The installed toolkit's requirementsSha256 at step 7; null without a toolkit. */
+    toolkitBefore: string | null;
+    /** Step 12 ran `mama tools install`; a rollback runs the previous version's. */
+    toolkitInstalled: boolean;
+    /** start.sh and the service file, copied at step 7, which a rollback copies back. */
+    copies: readonly {
+        path: string;
+        copy: string;
+    }[];
+    /** The step that failed and its message, for the rollback's report. */
+    failure: {
+        step: number;
+        message: string;
+    } | null;
+    readonly startedAt: string;
+}
+/** A doctor failure as `mama update` compares them: its name and its stable code (or detail). */
+export interface DoctorFailure {
+    readonly name: string;
+    readonly code: string;
+}
+export interface UpdatePaths {
+    readonly journal: string;
+    readonly hold: string;
+    /** Where step 7 copies start.sh and the service file. */
+    readonly copies: string;
+    /** `update.lock`: one updater per install, CLI or chat (PR 4 reads its holder). */
+    readonly lock: LockPaths;
+    /**
+     * Held by the continuation child (`--continue`, `--rollback --continue`) for its life. A parent
+     * killed while its child runs frees update.lock; this one tells `--rollback` the child still
+     * writes the journal.
+     */
+    readonly continuation: LockPaths;
+}
+export declare function updatePaths(mamaRoot: string): UpdatePaths;
+export declare const PACKAGE_SCOPE = "@jungjaehoon";
+export declare const PACKAGE_BASENAME = "mama-os";
+/** The staging prefix's name, in the scope folder: same filesystem, so the swap is two renames. */
+export declare const STAGING_PREFIX = ".mama-update-";
+/** The previous package, set aside beside it; npm skips dot folders. */
+export declare const ASIDE_PREFIX = ".mama-os-";
+export interface PackagePlaces {
+    /** `<prefix>/lib/node_modules/@jungjaehoon`. */
+    readonly scope: string;
+    /** Where the service's package lives: the old one before the swap, the new one after. */
+    readonly package: string;
+    /** The previous package once set aside. */
+    readonly aside: string;
+    /** The staging prefix npm installs `<to>` into. */
+    readonly staging: string;
+    /** The package npm installed under the staging prefix. */
+    readonly staged: string;
+}
+export declare function packagePlaces(prefix: string, from: string, to: string): PackagePlaces;
+/** Staging prefixes left in a scope folder by an updater killed before its journal. */
+export declare function leftoverStaging(scope: string): string[];
+/** The open journal, or null when no update is unfinished. */
+export declare function readUpdateJournal(path: string): UpdateJournal | null;
+/** fsync a file or a folder (a folder's entries: a rename or a removal in it). */
+export declare function syncFile(path: string): void;
+/**
+ * Write the journal durably: a staged file, synced, renamed over the old one, and the folder
+ * synced, so a power cut leaves the old journal or the new one. `committed` must be on disk before
+ * the candidate is released (step 14).
+ */
+export declare function writeUpdateJournal(path: string, journal: UpdateJournal): void;
+/** The durable write both journals use (the Node move's is read by install.sh, line by line). */
+export declare function writeJournalFile(path: string, value: object): void;
+/** Remove a journal, and sync its folder so the removal is on disk. */
+export declare function removeUpdateJournal(path: string): void;
+/** The snapshot's archive, its partial file and its backup's staging folder, whatever exists. */
+export declare function removeSnapshot(journal: UpdateJournal): void;
+/**
+ * What an unfinished update leaves for `mama status` and doctor to name: an open journal and the
+ * command that resolves it, or a hold file with no journal, which start.sh exits on.
+ */
+export declare function unfinishedUpdate(mamaRoot: string): {
+    journal: UpdateJournal;
+    command: string;
+} | {
+    hold: string;
+} | null;
+/**
+ * The command that resolves an open journal, with absolute paths: the previous CLI where it is
+ * now (set aside after step 8, in place before it or once a rollback put it back).
+ */
+export declare function rollbackCommand(journal: UpdateJournal): string;
+//# sourceMappingURL=update-journal.d.ts.map

package/dist/cli/runtime/update-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-journal.d.ts","sourceRoot":"","sources":["../../../src/cli/runtime/update-journal.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mFAAmF;IACnF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,0EAA0E;IAC1E,YAAY,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI,CAAC;IACjE,4FAA4F;IAC5F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oFAAoF;IACpF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qFAAqF;IACrF,MAAM,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClD,uEAAuE;IACvE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;CAClC;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAgBzD;AAED,eAAO,MAAM,aAAa,iBAAiB,CAAC;AAC5C,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAC1C,mGAAmG;AACnG,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAC9C,wEAAwE;AACxE,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAUrF;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKvD;AAID,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAmBpE;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAO3C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAE7E;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMlE;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAQ3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GACf;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKvE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAM9D"}

package/dist/cli/runtime/update-journal.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASIDE_PREFIX = exports.STAGING_PREFIX = exports.PACKAGE_BASENAME = exports.PACKAGE_SCOPE = void 0;
+exports.updatePaths = updatePaths;
+exports.packagePlaces = packagePlaces;
+exports.leftoverStaging = leftoverStaging;
+exports.readUpdateJournal = readUpdateJournal;
+exports.syncFile = syncFile;
+exports.writeUpdateJournal = writeUpdateJournal;
+exports.writeJournalFile = writeJournalFile;
+exports.removeUpdateJournal = removeUpdateJournal;
+exports.removeSnapshot = removeSnapshot;
+exports.unfinishedUpdate = unfinishedUpdate;
+exports.rollbackCommand = rollbackCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const secrets_js_1 = require("../secrets.js");
+function updatePaths(mamaRoot) {
+    const runtime = (0, node_path_1.join)(mamaRoot, 'runtime');
+    return {
+        journal: (0, node_path_1.join)(runtime, 'update.json'),
+        // start.sh tests it relative to the MAMA root (UPDATE_HOLD_LINE).
+        hold: (0, node_path_1.join)(runtime, 'update.hold'),
+        copies: (0, node_path_1.join)(runtime, 'update'),
+        lock: {
+            lockPath: (0, node_path_1.join)(runtime, 'update.lock'),
+            holderPath: (0, node_path_1.join)(runtime, 'update.holder.json'),
+        },
+        continuation: {
+            lockPath: (0, node_path_1.join)(runtime, 'update.continue.lock'),
+            holderPath: (0, node_path_1.join)(runtime, 'update.continue.holder.json'),
+        },
+    };
+}
+exports.PACKAGE_SCOPE = '@jungjaehoon';
+exports.PACKAGE_BASENAME = 'mama-os';
+/** The staging prefix's name, in the scope folder: same filesystem, so the swap is two renames. */
+exports.STAGING_PREFIX = '.mama-update-';
+/** The previous package, set aside beside it; npm skips dot folders. */
+exports.ASIDE_PREFIX = '.mama-os-';
+function packagePlaces(prefix, from, to) {
+    const scope = (0, node_path_1.join)(prefix, 'lib', 'node_modules', exports.PACKAGE_SCOPE);
+    const staging = (0, node_path_1.join)(scope, `${exports.STAGING_PREFIX}${to}`);
+    return {
+        scope,
+        package: (0, node_path_1.join)(scope, exports.PACKAGE_BASENAME),
+        aside: (0, node_path_1.join)(scope, `${exports.ASIDE_PREFIX}${from}`),
+        staging,
+        staged: (0, node_path_1.join)(staging, 'lib', 'node_modules', exports.PACKAGE_SCOPE, exports.PACKAGE_BASENAME),
+    };
+}
+/** Staging prefixes left in a scope folder by an updater killed before its journal. */
+function leftoverStaging(scope) {
+    if (!(0, node_fs_1.existsSync)(scope))
+        return [];
+    return (0, node_fs_1.readdirSync)(scope)
+        .filter((name) => name.startsWith(exports.STAGING_PREFIX))
+        .map((name) => (0, node_path_1.join)(scope, name));
+}
+const PHASES = new Set(['prepare', 'candidate', 'committed', 'rollback']);
+/** The open journal, or null when no update is unfinished. */
+function readUpdateJournal(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    const value = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    if (value === null ||
+        typeof value !== 'object' ||
+        value.format !== 'mama-update' ||
+        !PHASES.has(String(value.phase)) ||
+        typeof value.step !== 'number' ||
+        typeof value.from !== 'string' ||
+        typeof value.to !== 'string' ||
+        typeof value.prefix !== 'string' ||
+        typeof value.nodePath !== 'string' ||
+        typeof value.previousCli !== 'string' ||
+        typeof value.packageCli !== 'string') {
+        throw new Error(`${path} is not a journal mama update wrote`);
+    }
+    return value;
+}
+/** fsync a file or a folder (a folder's entries: a rename or a removal in it). */
+function syncFile(path) {
+    const fd = (0, node_fs_1.openSync)(path, 'r');
+    try {
+        (0, node_fs_1.fsyncSync)(fd);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Write the journal durably: a staged file, synced, renamed over the old one, and the folder
+ * synced, so a power cut leaves the old journal or the new one. `committed` must be on disk before
+ * the candidate is released (step 14).
+ */
+function writeUpdateJournal(path, journal) {
+    writeJournalFile(path, journal);
+}
+/** The durable write both journals use (the Node move's is read by install.sh, line by line). */
+function writeJournalFile(path, value) {
+    const staged = `${path}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(staged, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    syncFile(staged);
+    (0, node_fs_1.renameSync)(staged, path);
+    syncFile((0, node_path_1.dirname)(path));
+}
+/** Remove a journal, and sync its folder so the removal is on disk. */
+function removeUpdateJournal(path) {
+    (0, node_fs_1.rmSync)(path, { force: true });
+    syncFile((0, node_path_1.dirname)(path));
+}
+/** The snapshot's archive, its partial file and its backup's staging folder, whatever exists. */
+function removeSnapshot(journal) {
+    if (journal.snapshot !== null) {
+        (0, node_fs_1.rmSync)(journal.snapshot, { force: true });
+        (0, node_fs_1.rmSync)(`${journal.snapshot}.partial`, { force: true });
+    }
+    if (journal.snapshotStaging !== null) {
+        (0, node_fs_1.rmSync)(journal.snapshotStaging, { recursive: true, force: true });
+    }
+}
+/**
+ * What an unfinished update leaves for `mama status` and doctor to name: an open journal and the
+ * command that resolves it, or a hold file with no journal, which start.sh exits on.
+ */
+function unfinishedUpdate(mamaRoot) {
+    const paths = updatePaths(mamaRoot);
+    const journal = readUpdateJournal(paths.journal);
+    if (journal !== null)
+        return { journal, command: rollbackCommand(journal) };
+    return (0, node_fs_1.existsSync)(paths.hold) ? { hold: paths.hold } : null;
+}
+/**
+ * The command that resolves an open journal, with absolute paths: the previous CLI where it is
+ * now (set aside after step 8, in place before it or once a rollback put it back).
+ */
+function rollbackCommand(journal) {
+    const places = packagePlaces(journal.prefix, journal.from, journal.to);
+    const cli = (0, node_fs_1.existsSync)(places.aside)
+        ? journal.previousCli
+        : (0, node_path_1.join)(places.package, journal.packageCli);
+    return `${(0, secrets_js_1.shellQuote)(journal.nodePath)} ${(0, secrets_js_1.shellQuote)(cli)} update --rollback`;
+}
+//# sourceMappingURL=update-journal.js.map

package/dist/cli/runtime/update-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-journal.js","sourceRoot":"","sources":["../../../src/cli/runtime/update-journal.ts"],"names":[],"mappings":"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"}

package/dist/cli/runtime/update-progress.d.ts

@@ -0,0 +1,95 @@
+import { defaultTelegramCall } from './diagnostics.js';
+export type UpdateProgress = {
+    readonly kind: 'plan';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'current';
+    readonly version: string;
+} | {
+    readonly kind: 'step';
+    readonly from: string;
+    readonly to: string;
+    readonly step: number;
+}
+/** A step of the new version failed; the rollback reports next. */
+ | {
+    readonly kind: 'failed';
+    readonly from: string;
+    readonly to: string;
+    readonly step: number;
+    readonly code: string | null;
+}
+/** The stop or the snapshot failed; nothing was swapped. */
+ | {
+    readonly kind: 'not_updated';
+    readonly from: string;
+    readonly to: string;
+    readonly step: number;
+    readonly code: string;
+} | {
+    readonly kind: 'rolling_back';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'rolled_back';
+    readonly from: string;
+    readonly to: string;
+    readonly step: number;
+} | {
+    readonly kind: 'rollback_stopped';
+    readonly from: string;
+    readonly to: string;
+}
+/** `running`: the daemon answered the release; false when it is not running now. */
+ | {
+    readonly kind: 'updated';
+    readonly from: string;
+    readonly to: string;
+    readonly running: boolean;
+}
+/** The update ended on an error: a refusal before anything changed, or a step that threw. */
+ | {
+    readonly kind: 'error';
+    readonly code: string;
+};
+/** The step table's names (update.md, PR 3), for the chat. */
+export declare const UPDATE_STEP_NAMES: Readonly<Record<number, string>>;
+/** A code as the chat may see it: a token, never free text. */
+export declare function progressCode(value: unknown): string | null;
+export declare function progressText(event: UpdateProgress): string;
+export interface ProgressSink {
+    send(event: UpdateProgress): void;
+    /**
+     * Wait until every event sent so far has gone out (or failed and been logged). Past
+     * PROGRESS_FLUSH_DEADLINE_MS, step messages not yet sent are dropped and counted in the log;
+     * the outcomes (updated, failed, rolled back, …) are still sent, each within its own timeout.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * One send's limit. The flushes before a child CLI and at the end run while MAMA is stopped, so
+ * a Bot API that does not answer must not hold the install down; Telegram answers in well under
+ * a second when it answers at all.
+ */
+export declare const PROGRESS_SEND_TIMEOUT_MS = 3000;
+/**
+ * How long a flush waits for step messages: past it, the steps still queued are dropped, so a
+ * slow Bot API holds the stopped install for this plus the few outcome sends at most.
+ */
+export declare const PROGRESS_FLUSH_DEADLINE_MS = 5000;
+export declare const NO_PROGRESS: ProgressSink;
+export type TelegramCall = typeof defaultTelegramCall;
+/**
+ * Progress to the /update's chat through the Bot API's sendMessage alone: the daemon may be
+ * stopped, and a getUpdates here would take its updates. The chat comes from
+ * runtime/update-request.json and the bot token alone from auth.env, as doctor reads it. A send
+ * that fails is logged (to update.log, the job's output) and the update goes on. Repeats of a step
+ * (the journal is saved more than once in a step) are sent once.
+ */
+export declare function telegramProgress(options: {
+    root: string;
+    log: (line: string) => void;
+    call?: TelegramCall;
+}): ProgressSink;
+//# sourceMappingURL=update-progress.d.ts.map

package/dist/cli/runtime/update-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-progress.d.ts","sourceRoot":"","sources":["../../../src/cli/runtime/update-progress.ts"],"names":[],"mappings":"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"}