telegram-ask 0.1.1

package/dist/config/store.js

@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { isMissingFileError, writeFileAtomic } from '../system/index.js';
+import { DEFAULT_HOST, DEFAULT_PORT, INIT_HINT, INTEGER_PATTERN, SECRET_FILE_MODE, } from './constants.js';
+import { fileConfigSchema } from './schema.js';
+function findEnvValue(env, key) {
+    const value = env[key];
+    return value === undefined || value === '' ? undefined : value;
+}
+/**
+ * Path of config.json: $TELEGRAM_ASK_CONFIG, else under $XDG_CONFIG_HOME or ~/.config. Empty env
+ * values count as unset.
+ */
+export function resolveConfigPath(env = process.env) {
+    const explicit = findEnvValue(env, 'TELEGRAM_ASK_CONFIG');
+    if (explicit) {
+        return explicit;
+    }
+    const xdgConfigHome = findEnvValue(env, 'XDG_CONFIG_HOME');
+    const base = xdgConfigHome ?? join(findEnvValue(env, 'HOME') ?? homedir(), '.config');
+    return join(base, 'telegram-ask', 'config.json');
+}
+/** Default config directory, ignoring $TELEGRAM_ASK_CONFIG; install files live here. */
+export function resolveConfigDirectory(env = process.env) {
+    const { TELEGRAM_ASK_CONFIG: _ignored, ...rest } = env;
+    return dirname(resolveConfigPath(rest));
+}
+/**
+ * Returns {} when the file is missing. Throws on invalid JSON or fields, without quoting the file,
+ * since it may hold the bot token. Read errors other than a missing file are rethrown.
+ */
+export function readConfigFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return {};
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Don't include the parser's message: V8 can quote part of the file, which may hold the bot
+        // token.
+        throw new Error(`config file ${JSON.stringify(path)} contains invalid JSON; ${INIT_HINT}`);
+    }
+    const result = fileConfigSchema.safeParse(parsed);
+    // Don't include zod's issues either; keep the token out of error output.
+    if (!result.success) {
+        throw new Error(`config file ${JSON.stringify(path)} has invalid or missing fields; ${INIT_HINT}`);
+    }
+    return result.data;
+}
+function toInteger(value) {
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? value : undefined;
+    }
+    if (typeof value === 'string' && INTEGER_PATTERN.test(value.trim())) {
+        return Number(value.trim());
+    }
+    return undefined;
+}
+/**
+ * Env vars (BOT_TOKEN, OWNER_ID, PORT, HOST) override the config file. Throws a user-facing error
+ * on a missing token or invalid owner id or port; read errors other than a missing config file
+ * are rethrown.
+ */
+export function loadConfig(env = process.env) {
+    const file = readConfigFile(resolveConfigPath(env));
+    const botToken = findEnvValue(env, 'BOT_TOKEN') ?? file.botToken;
+    if (typeof botToken !== 'string' || botToken === '') {
+        throw new Error(`missing bot token; ${INIT_HINT} (or set BOT_TOKEN)`);
+    }
+    const rawOwnerId = findEnvValue(env, 'OWNER_ID') ?? file.ownerId;
+    const ownerId = rawOwnerId === undefined ? undefined : toInteger(rawOwnerId);
+    if (rawOwnerId !== undefined && (ownerId === undefined || !Number.isSafeInteger(ownerId))) {
+        throw new Error(`invalid owner id; ${INIT_HINT} (or set OWNER_ID)`);
+    }
+    const rawPort = findEnvValue(env, 'PORT') ?? file.port ?? DEFAULT_PORT;
+    const port = toInteger(rawPort);
+    if (port === undefined || port < 1 || port > 65535) {
+        throw new Error(`invalid port ${JSON.stringify(String(rawPort))}: must be an integer 1-65535`);
+    }
+    return { botToken, ownerId, port, host: findEnvValue(env, 'HOST') ?? DEFAULT_HOST };
+}
+/** Merges `patch` into the file's JSON object; a `null` value deletes that key. */
+export function updateConfigFile(path, patch) {
+    const next = { ...readConfigFile(path) };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete next[key];
+        }
+        else if (value !== undefined) {
+            next[key] = value;
+        }
+    }
+    writeFileAtomic(path, `${JSON.stringify(next, null, 2)}\n`, SECRET_FILE_MODE);
+}

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/daemon/index.js

@@ -0,0 +1 @@
+export { runService } from './service.js';

package/dist/daemon/service.js

@@ -0,0 +1,82 @@
+import { Bot, GrammyError } from 'grammy';
+import { ApprovalService } from '../approval/index.js';
+import { loadConfig, resolveConfigPath } from '../config/index.js';
+import { createApiServer } from '../server/index.js';
+import { createOnPaired, createTelegramMessenger, formatCode, generateCode, Pairing, registerPairingHandler, registerTapHandler, } from '../telegram/index.js';
+/**
+ * Starts the bot and API. Exits the process with 1 on bad config, a rejected token, Telegram being
+ * unreachable at startup, an HTTP server error, or a fatal polling error (409 means another
+ * instance is polling with the same token).
+ */
+export async function runService(env = process.env) {
+    let config;
+    try {
+        config = loadConfig(env);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+    const owner = { id: config.ownerId };
+    const bot = new Bot(config.botToken);
+    const service = new ApprovalService(createTelegramMessenger(bot, owner));
+    registerTapHandler(bot, owner, (id, optionIndex) => service.tap(id, optionIndex));
+    // Log handler errors instead of crashing; grammY's error text doesn't include the token.
+    bot.catch((error) => {
+        console.error('bot error:', error.error instanceof Error ? error.error.message : error.error);
+    });
+    try {
+        await bot.init();
+    }
+    catch (error) {
+        // Don't print the error text; it can embed the request URL with the token.
+        console.error(error instanceof GrammyError
+            ? `Telegram rejected the bot token (${error.error_code}); check it with \`telegram-ask init\``
+            : 'could not reach Telegram to verify the bot token');
+        process.exit(1);
+    }
+    const botUsername = bot.botInfo.username;
+    let pairing;
+    if (owner.id === undefined) {
+        const code = generateCode();
+        pairing = new Pairing(code);
+        console.log(`Not paired. Send "/start ${formatCode(code)}" to @${botUsername}, or open https://t.me/${botUsername}?start=${code}`);
+        registerPairingHandler(bot, pairing, createOnPaired(owner, resolveConfigPath(env)));
+    }
+    const server = createApiServer(service, () => owner.id !== undefined || pairing === undefined || pairing.code === undefined
+        ? { paired: true, bot: botUsername }
+        : { paired: false, code: formatCode(pairing.code), bot: botUsername });
+    server.listen({ port: config.port, host: config.host }).then(() => console.log(`listening on ${config.host}:${config.port}`), (error) => {
+        console.error('http server error:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+    let stopping = false;
+    function shutdown() {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        setTimeout(() => process.exit(0), 5000).unref();
+        server.close().catch(() => { });
+        bot
+            .stop()
+            .catch(() => { })
+            .finally(() => process.exit(0));
+    }
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    bot
+        .start({ onStart: (botUser) => console.log(`bot @${botUser.username} polling`) })
+        .catch((error) => {
+        if (stopping) {
+            return;
+        }
+        if (error instanceof GrammyError && error.error_code === 409) {
+            console.error('another instance is already polling with this bot token; exiting');
+        }
+        else {
+            console.error('bot stopped:', error instanceof Error ? error.message : String(error));
+        }
+        process.exit(1);
+    });
+}

package/dist/install/compose.js

@@ -0,0 +1,123 @@
+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { DOCKERIGNORE, INTEGER_PATTERN, PACKAGE_NAME } from './constants.js';
+import { readEnvFile, removeEnvKey, writeEnvFile } from './envfile.js';
+import { formatComposeYaml, formatDockerfile, formatEnvFile } from './templates.js';
+async function tryExec(exec, command, args) {
+    try {
+        return await exec(command, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Docker Compose target; writes its files under the compose directory and drives `docker compose`.
+ */
+export function createComposeTarget(deps) {
+    const { exec, paths } = deps;
+    const file = join(paths.composeDirectory, 'compose.yaml');
+    const envPath = join(paths.composeDirectory, '.env');
+    const compose = (args, options) => exec('docker', ['compose', '-f', file, ...args], options);
+    return {
+        name: 'compose',
+        async available() {
+            const version = await tryExec(exec, 'docker', ['compose', 'version']);
+            if (version === undefined) {
+                return { ok: false, reason: 'docker not installed' };
+            }
+            if (version.code !== 0) {
+                return { ok: false, reason: 'docker compose v2 not available' };
+            }
+            const info = await tryExec(exec, 'docker', ['info']);
+            if (info === undefined || info.code !== 0) {
+                return { ok: false, reason: "can't talk to docker (not in the docker group?)" };
+            }
+            return { ok: true };
+        },
+        async install(options) {
+            mkdirSync(paths.composeDirectory, { recursive: true });
+            if (options.tarball !== undefined) {
+                const destination = join(paths.composeDirectory, basename(options.tarball));
+                if (resolve(options.tarball) !== resolve(destination)) {
+                    copyFileSync(options.tarball, destination);
+                }
+            }
+            // Keep the token out of the build context.
+            writeFileSync(join(paths.composeDirectory, '.dockerignore'), DOCKERIGNORE);
+            writeFileSync(join(paths.composeDirectory, 'Dockerfile'), formatDockerfile({
+                version: options.version,
+                ...(options.tarball ? { tarball: options.tarball } : {}),
+            }));
+            writeFileSync(file, formatComposeYaml(options.port));
+            writeEnvFile(envPath, formatEnvFile({
+                token: options.token,
+                port: options.port,
+                ...(options.ownerId === undefined ? {} : { ownerId: options.ownerId }),
+            }));
+            const result = await compose(['up', '-d', '--build'], { inherit: true });
+            if (result.code !== 0) {
+                throw new Error(`docker compose up failed (exit ${result.code})`);
+            }
+            return { target: 'compose', port: options.port, version: options.version };
+        },
+        async readSecrets() {
+            const values = readEnvFile(envPath);
+            const tokenSecrets = values.BOT_TOKEN ? { token: values.BOT_TOKEN } : {};
+            if (values.OWNER_ID && INTEGER_PATTERN.test(values.OWNER_ID)) {
+                return { ...tokenSecrets, ownerId: Number(values.OWNER_ID) };
+            }
+            const result = await compose([
+                'run',
+                '--rm',
+                '--no-deps',
+                'bot',
+                PACKAGE_NAME,
+                'owner',
+                'get',
+            ]);
+            const output = result.stdout.trim();
+            if (result.code === 0 && INTEGER_PATTERN.test(output)) {
+                return { ...tokenSecrets, ownerId: Number(output) };
+            }
+            return tokenSecrets;
+        },
+        async remove(_record, purge) {
+            const result = await compose(purge ? ['down', '-v'] : ['down']);
+            if (result.code !== 0) {
+                throw new Error(`docker compose down failed: ${result.stderr.trim()}`);
+            }
+            if (purge) {
+                rmSync(paths.composeDirectory, { recursive: true, force: true });
+            }
+        },
+        async restart() {
+            const result = await compose(['up', '-d', '--force-recreate']);
+            if (result.code !== 0) {
+                throw new Error(`docker compose up failed (exit ${result.code})`);
+            }
+        },
+        async clearOwner() {
+            removeEnvKey(envPath, 'OWNER_ID');
+            const result = await compose([
+                'run',
+                '--rm',
+                '--no-deps',
+                'bot',
+                PACKAGE_NAME,
+                'owner',
+                'clear',
+            ]);
+            if (result.code !== 0) {
+                throw new Error(`couldn't clear the owner in the container: ${result.stderr.trim()}`);
+            }
+        },
+        async isRunning() {
+            const result = await compose(['ps', '--status', 'running', '-q', 'bot']);
+            return result.code === 0 && result.stdout.trim() !== '';
+        },
+        logsHint() {
+            return `docker compose -f ${file} logs -f`;
+        },
+    };
+}

package/dist/install/constants.js

@@ -0,0 +1,28 @@
+/** Preference order; the first available target is the default. */
+export const TARGET_ORDER = ['quadlet', 'compose', 'systemd'];
+/** Name of the systemd unit and container. */
+export const SERVICE_NAME = 'telegram-ask';
+/** npm package name, also the container's command. */
+export const PACKAGE_NAME = 'telegram-ask';
+/** Podman volume holding /data (the config file). */
+export const VOLUME_NAME = 'telegram-ask-data';
+/** Keeps the .env file with the bot token out of the image build context. */
+export const DOCKERIGNORE = '.env\n';
+/** Quadlet needs podman 4.4 or newer (major part). */
+export const MIN_PODMAN_MAJOR = 4;
+/** Quadlet needs podman 4.4 or newer (minor part). */
+export const MIN_PODMAN_MINOR = 4;
+/** Whole numbers in env files and command output. */
+export const INTEGER_PATTERN = /^-?\d+$/;
+/** podman stderr meaning the thing is already gone, which purge treats as success. */
+export const NOT_FOUND_PATTERN = /no such|not found|does not exist/i;
+/** Captures major, minor and optional patch from `podman --version`. */
+export const PODMAN_VERSION_PATTERN = /(\d+)\.(\d+)(?:\.(\d+))?/;
+/** Matches an `Environment=` line in a unit file. */
+export const ENVIRONMENT_LINE_PATTERN = /^\s*Environment=(.*)$/;
+/** Matches a backslash escape inside a quoted unit value. */
+export const ESCAPED_CHAR_PATTERN = /\\(.)/g;
+/** Variable the unit sets to pin the config file path. */
+export const CONFIG_ENV_PREFIX = 'TELEGRAM_ASK_CONFIG=';
+/** Owner read/write only, for files that hold the bot token. */
+export const SECRET_FILE_MODE = 0o600;

package/dist/install/envfile.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { isMissingFileError, writeFileAtomic } from '../system/index.js';
+import { SECRET_FILE_MODE } from './constants.js';
+function readTextIfPresent(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Parses KEY=VALUE lines, skipping blanks and comments; returns {} when the file is missing. Values
+ * are taken literally (no unquoting).
+ */
+export function readEnvFile(path) {
+    const text = readTextIfPresent(path);
+    if (text === undefined) {
+        return {};
+    }
+    const values = {};
+    for (const line of text.split('\n')) {
+        if (line.trim() === '' || line.startsWith('#')) {
+            continue;
+        }
+        const index = line.indexOf('=');
+        if (index > 0) {
+            values[line.slice(0, index)] = line.slice(index + 1);
+        }
+    }
+    return values;
+}
+/** Atomic write with owner-only permissions, since the file holds the bot token. */
+export function writeEnvFile(path, contents) {
+    writeFileAtomic(path, contents, SECRET_FILE_MODE);
+}
+/**
+ * Drops every `key=` line, rewriting the file atomically; does nothing when the file is missing.
+ */
+export function removeEnvKey(path, key) {
+    const text = readTextIfPresent(path);
+    if (text === undefined) {
+        return;
+    }
+    const kept = text.split('\n').filter((line) => !line.startsWith(`${key}=`));
+    writeEnvFile(path, kept.join('\n'));
+}

package/dist/install/index.js

@@ -0,0 +1,9 @@
+export { createComposeTarget } from './compose.js';
+export { TARGET_ORDER } from './constants.js';
+export { readEnvFile, removeEnvKey, writeEnvFile } from './envfile.js';
+export { resolveInstallPaths } from './paths.js';
+export { createQuadletTarget } from './quadlet.js';
+export { createTargets, detectTargets, findDefaultTarget, findExistingInstall, findLeftoverSecrets, } from './registry.js';
+export { readInstall, removeInstall, writeInstall } from './state.js';
+export { createSystemdTarget, findUnitConfigFile } from './systemd.js';
+export { formatComposeYaml, formatDockerfile, formatEnvFile, formatQuadletContainer, formatSystemdUnit, quoteExecWord, quoteSystemdValue, } from './templates.js';

package/dist/install/paths.js

@@ -0,0 +1,23 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveConfigDirectory } from '../config/index.js';
+function toNonEmpty(value) {
+    return value === undefined || value === '' ? undefined : value;
+}
+/** Where each target keeps its files, derived from the env; touches no files. */
+export function resolveInstallPaths(env = process.env) {
+    const home = toNonEmpty(env.HOME) ?? homedir();
+    const configDirectory = resolveConfigDirectory(env);
+    const xdgConfigHome = toNonEmpty(env.XDG_CONFIG_HOME) ?? join(home, '.config');
+    const xdgDataHome = toNonEmpty(env.XDG_DATA_HOME) ?? join(home, '.local', 'share');
+    return {
+        configDirectory,
+        configFile: join(configDirectory, 'config.json'),
+        installFile: join(configDirectory, 'install.json'),
+        composeDirectory: join(configDirectory, 'compose'),
+        quadletDirectory: join(configDirectory, 'quadlet'),
+        systemdUnit: join(xdgConfigHome, 'systemd', 'user', 'telegram-ask.service'),
+        quadletUnit: join(xdgConfigHome, 'containers', 'systemd', 'telegram-ask.container'),
+        userNpmPrefix: join(xdgDataHome, 'telegram-ask', 'npm'),
+    };
+}

package/dist/install/quadlet.js

@@ -0,0 +1,167 @@
+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { ensureLinger } from '../system/index.js';
+import { DOCKERIGNORE, INTEGER_PATTERN, MIN_PODMAN_MAJOR, MIN_PODMAN_MINOR, NOT_FOUND_PATTERN, PODMAN_VERSION_PATTERN, SERVICE_NAME, VOLUME_NAME, } from './constants.js';
+import { readEnvFile, removeEnvKey, writeEnvFile } from './envfile.js';
+import { formatDockerfile, formatEnvFile, formatQuadletContainer } from './templates.js';
+function formatImageTag(version) {
+    return `localhost/${SERVICE_NAME}:${version}`;
+}
+/**
+ * Podman Quadlet target (needs podman 4.4+); builds the image locally and runs it as a user systemd
+ * unit.
+ */
+export function createQuadletTarget(deps) {
+    const { exec, paths, user } = deps;
+    const envPath = join(paths.quadletDirectory, '.env');
+    const systemctl = (...args) => exec('systemctl', ['--user', ...args]);
+    return {
+        name: 'quadlet',
+        async available() {
+            let output;
+            try {
+                const result = await exec('podman', ['--version']);
+                if (result.code !== 0) {
+                    return { ok: false, reason: 'podman not installed' };
+                }
+                output = result.stdout;
+            }
+            catch {
+                return { ok: false, reason: 'podman not installed' };
+            }
+            const match = PODMAN_VERSION_PATTERN.exec(output);
+            if (!match) {
+                return { ok: false, reason: `can't parse podman version: ${output.trim()}` };
+            }
+            const major = Number(match[1]);
+            const minor = Number(match[2]);
+            if (major > MIN_PODMAN_MAJOR || (major === MIN_PODMAN_MAJOR && minor >= MIN_PODMAN_MINOR)) {
+                return { ok: true };
+            }
+            return { ok: false, reason: `podman ${match[0]} is too old; quadlet needs 4.4 or newer` };
+        },
+        async install(options) {
+            mkdirSync(paths.quadletDirectory, { recursive: true });
+            if (options.tarball !== undefined) {
+                const destination = join(paths.quadletDirectory, basename(options.tarball));
+                if (resolve(options.tarball) !== resolve(destination)) {
+                    copyFileSync(options.tarball, destination);
+                }
+            }
+            // Keep the token out of the build context.
+            writeFileSync(join(paths.quadletDirectory, '.dockerignore'), DOCKERIGNORE);
+            writeFileSync(join(paths.quadletDirectory, 'Dockerfile'), formatDockerfile({
+                version: options.version,
+                ...(options.tarball ? { tarball: options.tarball } : {}),
+            }));
+            writeEnvFile(envPath, formatEnvFile({
+                token: options.token,
+                port: options.port,
+                ...(options.ownerId === undefined ? {} : { ownerId: options.ownerId }),
+            }));
+            const build = await exec('podman', ['build', '-t', formatImageTag(options.version), paths.quadletDirectory], { inherit: true });
+            if (build.code !== 0) {
+                throw new Error(`podman build failed (exit ${build.code})`);
+            }
+            mkdirSync(dirname(paths.quadletUnit), { recursive: true });
+            writeFileSync(paths.quadletUnit, formatQuadletContainer({ version: options.version, port: options.port, envFile: envPath }));
+            for (const args of [['daemon-reload'], ['start', SERVICE_NAME]]) {
+                const result = await systemctl(...args);
+                if (result.code !== 0) {
+                    throw new Error(`systemctl ${args.join(' ')} failed: ${result.stderr.trim()}`);
+                }
+            }
+            await ensureLinger(exec, user, options.print);
+            return { target: 'quadlet', port: options.port, version: options.version };
+        },
+        async readSecrets(record) {
+            const values = readEnvFile(envPath);
+            const tokenSecrets = values.BOT_TOKEN ? { token: values.BOT_TOKEN } : {};
+            if (values.OWNER_ID && INTEGER_PATTERN.test(values.OWNER_ID)) {
+                return { ...tokenSecrets, ownerId: Number(values.OWNER_ID) };
+            }
+            const result = await exec('podman', [
+                'run',
+                '--rm',
+                '-v',
+                `${VOLUME_NAME}:/data`,
+                formatImageTag(record.version),
+                SERVICE_NAME,
+                'owner',
+                'get',
+            ]);
+            const output = result.stdout.trim();
+            if (result.code === 0 && INTEGER_PATTERN.test(output)) {
+                return { ...tokenSecrets, ownerId: Number(output) };
+            }
+            return tokenSecrets;
+        },
+        async remove(record, purge) {
+            await systemctl('stop', SERVICE_NAME);
+            rmSync(paths.quadletUnit, { force: true });
+            await systemctl('daemon-reload');
+            if (!purge) {
+                return;
+            }
+            const failures = [];
+            const step = async (label, args) => {
+                try {
+                    const result = await exec('podman', args);
+                    if (result.code === 0 || NOT_FOUND_PATTERN.test(result.stderr)) {
+                        return true;
+                    }
+                    failures.push(`${label}: ${result.stderr.trim() || `exit ${result.code}`}`);
+                }
+                catch (error) {
+                    failures.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                return false;
+            };
+            const isVolumeRemoved = await step('podman volume rm', ['volume', 'rm', VOLUME_NAME]);
+            await step('podman rmi', ['rmi', formatImageTag(record.version)]);
+            if (isVolumeRemoved) {
+                rmSync(paths.quadletDirectory, { recursive: true, force: true });
+            }
+            if (failures.length > 0) {
+                throw new Error(`purge incomplete: ${failures.join('; ')}`);
+            }
+        },
+        async restart() {
+            const result = await systemctl('restart', SERVICE_NAME);
+            if (result.code !== 0) {
+                throw new Error(`systemctl restart failed (exit ${result.code})`);
+            }
+        },
+        async clearOwner(record) {
+            removeEnvKey(envPath, 'OWNER_ID');
+            try {
+                const result = await exec('podman', ['exec', SERVICE_NAME, SERVICE_NAME, 'owner', 'clear']);
+                if (result.code === 0) {
+                    return;
+                }
+            }
+            catch {
+                // fall through to the one-off container
+            }
+            const result = await exec('podman', [
+                'run',
+                '--rm',
+                '-v',
+                `${VOLUME_NAME}:/data`,
+                formatImageTag(record.version),
+                SERVICE_NAME,
+                'owner',
+                'clear',
+            ]);
+            if (result.code !== 0) {
+                throw new Error(`couldn't clear the owner in the container: ${result.stderr.trim()}`);
+            }
+        },
+        async isRunning() {
+            return (await systemctl('is-active', '--quiet', SERVICE_NAME)).code === 0;
+        },
+        logsHint() {
+            return `journalctl --user -u ${SERVICE_NAME} -f`;
+        },
+    };
+}