telegram-ask 0.1.1

package/dist/install/registry.js

@@ -0,0 +1,98 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_PORT, readConfigFile } from '../config/index.js';
+import { createComposeTarget } from './compose.js';
+import { INTEGER_PATTERN, TARGET_ORDER } from './constants.js';
+import { readEnvFile } from './envfile.js';
+import { createQuadletTarget } from './quadlet.js';
+import { readInstall } from './state.js';
+import { createSystemdTarget, findUnitConfigFile, resolveDefaultConfigFile } from './systemd.js';
+/** Builds all three install targets from the same dependencies. */
+export function createTargets(deps, cli) {
+    return {
+        quadlet: createQuadletTarget(deps),
+        compose: createComposeTarget(deps),
+        systemd: createSystemdTarget(deps, cli),
+    };
+}
+/** Asks each target if it is usable, in `TARGET_ORDER`. */
+export async function detectTargets(targets) {
+    const detected = [];
+    for (const name of TARGET_ORDER) {
+        detected.push({ name, ...(await targets[name].available()) });
+    }
+    return detected;
+}
+/** First available target in the given order, or undefined when none is usable. */
+export function findDefaultTarget(detected) {
+    return detected.find((candidate) => candidate.ok)?.name;
+}
+/**
+ * Install recorded in install.json, else a legacy systemd install rebuilt from its unit file
+ * (`legacy: true`); undefined when neither exists.
+ */
+export function findExistingInstall(paths, _targets, env = process.env) {
+    const record = readInstall(paths.installFile);
+    if (record) {
+        return { record, legacy: false };
+    }
+    let unit;
+    try {
+        unit = readFileSync(paths.systemdUnit, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    // The legacy unit may pin its own config path; prefer it over this shell's env.
+    const configFile = findUnitConfigFile(unit) ?? resolveDefaultConfigFile(paths, env);
+    let port = DEFAULT_PORT;
+    try {
+        port = readConfigFile(configFile).port ?? DEFAULT_PORT;
+    }
+    catch {
+        // Unreadable config: fall back to the default port.
+    }
+    return { record: { target: 'systemd', port, version: 'legacy', configFile }, legacy: true };
+}
+function readEnvSecrets(path) {
+    const values = readEnvFile(path);
+    return {
+        ...(values.BOT_TOKEN ? { token: values.BOT_TOKEN } : {}),
+        ...(values.OWNER_ID && INTEGER_PATTERN.test(values.OWNER_ID)
+            ? { ownerId: Number(values.OWNER_ID) }
+            : {}),
+    };
+}
+function readConfigSecrets(path) {
+    try {
+        const config = readConfigFile(path);
+        return {
+            ...(config.botToken ? { token: config.botToken } : {}),
+            ...(config.ownerId !== undefined && Number.isSafeInteger(config.ownerId)
+                ? { ownerId: config.ownerId }
+                : {}),
+        };
+    }
+    catch {
+        // Corrupt config: treat as nothing left over.
+        return {};
+    }
+}
+/**
+ * Token and owner left behind by an uninstall that kept them (no install.json any more).
+ * Only reads files; never runs a container. First source with a token wins.
+ */
+export function findLeftoverSecrets(paths, env = process.env) {
+    const sources = [
+        () => readEnvSecrets(join(paths.quadletDirectory, '.env')),
+        () => readEnvSecrets(join(paths.composeDirectory, '.env')),
+        () => readConfigSecrets(resolveDefaultConfigFile(paths, env)),
+    ];
+    for (const read of sources) {
+        const secrets = read();
+        if (secrets.token !== undefined) {
+            return secrets;
+        }
+    }
+    return {};
+}

package/dist/install/schema.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/** Shape of install.json. */
+export const installRecordSchema = z.object({
+    target: z.enum(['systemd', 'compose', 'quadlet']),
+    port: z.number(),
+    version: z.string(),
+    cliPath: z.string().optional(),
+    /** Absolute config.json path the systemd unit was installed with. */
+    configFile: z.string().optional(),
+});

package/dist/install/state.js

@@ -0,0 +1,24 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { writeFileAtomic } from '../system/index.js';
+import { SECRET_FILE_MODE } from './constants.js';
+import { installRecordSchema } from './schema.js';
+/** Undefined when the file is missing, unreadable or invalid. */
+export function readInstall(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const result = installRecordSchema.safeParse(parsed);
+    return result.success ? result.data : undefined;
+}
+/** Atomic write with owner-only permissions. */
+export function writeInstall(file, record) {
+    writeFileAtomic(file, `${JSON.stringify(record, null, 2)}\n`, SECRET_FILE_MODE);
+}
+/** Deletes install.json; fine if it is already gone. */
+export function removeInstall(file) {
+    rmSync(file, { force: true });
+}

package/dist/install/systemd.js

@@ -0,0 +1,151 @@
+import { accessSync, constants, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { readConfigFile, updateConfigFile } from '../config/index.js';
+import { ensureLinger } from '../system/index.js';
+import { CONFIG_ENV_PREFIX, ENVIRONMENT_LINE_PATTERN, ESCAPED_CHAR_PATTERN, PACKAGE_NAME, SERVICE_NAME, } from './constants.js';
+import { formatSystemdUnit } from './templates.js';
+function isUnder(file, root) {
+    return root !== '' && file.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+function isWritable(directory) {
+    try {
+        accessSync(directory, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The config file a systemd install uses when nothing recorded one: $TELEGRAM_ASK_CONFIG or the default, absolute. */
+export function resolveDefaultConfigFile(paths, env) {
+    return resolve(env.TELEGRAM_ASK_CONFIG || paths.configFile);
+}
+/** Best-effort read of the TELEGRAM_ASK_CONFIG value from a unit's Environment= lines. */
+export function findUnitConfigFile(unit) {
+    for (const line of unit.split('\n')) {
+        const rawValue = ENVIRONMENT_LINE_PATTERN.exec(line)?.[1];
+        if (rawValue === undefined) {
+            continue;
+        }
+        const trimmed = rawValue.trim();
+        const unquoted = trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+            ? trimmed.slice(1, -1).replace(ESCAPED_CHAR_PATTERN, '$1')
+            : trimmed;
+        const value = unquoted.replaceAll('%%', '%');
+        if (value.startsWith(CONFIG_ENV_PREFIX) && value.length > CONFIG_ENV_PREFIX.length) {
+            return resolve(value.slice(CONFIG_ENV_PREFIX.length));
+        }
+    }
+    return undefined;
+}
+/**
+ * systemd user service target running the npm-installed CLI; keeps its settings in the config file.
+ */
+export function createSystemdTarget(deps, cli) {
+    const { exec, paths, env, user } = deps;
+    const systemctl = (...args) => exec('systemctl', ['--user', ...args]);
+    // The unit always pins TELEGRAM_ASK_CONFIG to this absolute path, and install.json records it,
+    // so later commands don't depend on the environment they happen to run in.
+    const configFile = resolveDefaultConfigFile(paths, env);
+    const resolveConfigFile = (record) => record.configFile ?? configFile;
+    const fallbackRoot = join(paths.userNpmPrefix, 'lib', 'node_modules');
+    async function resolveCli(options) {
+        const root = (await exec('npm', ['root', '-g'])).stdout.trim();
+        if (isUnder(cli.selfPath, root)) {
+            options.print(`Using the installed CLI at ${cli.selfPath}`);
+            return cli.selfPath;
+        }
+        if (isUnder(cli.selfPath, fallbackRoot)) {
+            options.print(`Using the installed CLI at ${cli.selfPath}`);
+            return cli.selfPath;
+        }
+        const packageSpec = options.tarball ?? `${PACKAGE_NAME}@${options.version}`;
+        const prefix = (await exec('npm', ['prefix', '-g'])).stdout.trim();
+        let installRoot;
+        let args;
+        if (prefix !== '' && isWritable(prefix)) {
+            options.print(`Installing ${packageSpec} globally with npm`);
+            args = ['i', '-g', packageSpec];
+            installRoot = root;
+        }
+        else {
+            options.print(`Global npm prefix isn't writable; installing ${packageSpec} into ${paths.userNpmPrefix}`);
+            mkdirSync(paths.userNpmPrefix, { recursive: true });
+            args = ['i', '-g', '--prefix', paths.userNpmPrefix, packageSpec];
+            installRoot = fallbackRoot;
+        }
+        const result = await exec('npm', args);
+        if (result.code !== 0) {
+            throw new Error(`npm install failed: ${result.stderr.trim()}`);
+        }
+        return join(installRoot, PACKAGE_NAME, 'dist', 'cli.js');
+    }
+    return {
+        name: 'systemd',
+        async available() {
+            const result = await systemctl('show-environment');
+            return result.code === 0
+                ? { ok: true }
+                : { ok: false, reason: 'systemd user session not available' };
+        },
+        async install(options) {
+            const cliPath = await resolveCli(options);
+            // Only touch ownerId when we have one; clearOwner is the explicit way to drop it.
+            updateConfigFile(configFile, {
+                botToken: options.token,
+                port: options.port,
+                ...(options.ownerId === undefined ? {} : { ownerId: options.ownerId }),
+            });
+            mkdirSync(dirname(paths.systemdUnit), { recursive: true });
+            writeFileSync(paths.systemdUnit, formatSystemdUnit({ node: cli.nodePath, cli: cliPath, config: configFile }));
+            for (const args of [['daemon-reload'], ['enable', '--now', 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: 'systemd',
+                port: options.port,
+                version: options.version,
+                cliPath,
+                configFile,
+            };
+        },
+        async readSecrets(record) {
+            const config = readConfigFile(resolveConfigFile(record));
+            return {
+                ...(config.botToken === undefined ? {} : { token: config.botToken }),
+                ...(config.ownerId === undefined ? {} : { ownerId: config.ownerId }),
+            };
+        },
+        async remove(record, purge) {
+            await systemctl('disable', '--now', SERVICE_NAME);
+            rmSync(paths.systemdUnit, { force: true });
+            await systemctl('daemon-reload');
+            if (purge) {
+                rmSync(resolveConfigFile(record), { force: true });
+                const prefix = record.cliPath !== undefined && isUnder(record.cliPath, fallbackRoot)
+                    ? `--prefix ${paths.userNpmPrefix} `
+                    : '';
+                console.log(`The npm package was left in place; remove it with: npm rm -g ${prefix}${PACKAGE_NAME}`);
+            }
+        },
+        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) {
+            updateConfigFile(resolveConfigFile(record), { ownerId: null });
+        },
+        async isRunning() {
+            return (await systemctl('is-active', '--quiet', SERVICE_NAME)).code === 0;
+        },
+        logsHint() {
+            return `journalctl --user -u ${SERVICE_NAME} -f`;
+        },
+    };
+}

package/dist/install/templates.js

@@ -0,0 +1,87 @@
+import { basename } from 'node:path';
+/** Wraps in double quotes, escaping backslash and `"`, and doubling `%` (systemd specifier). */
+export function quoteSystemdValue(value) {
+    return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`;
+}
+/** Quotes one ExecStart word; `$` is also escaped there because systemd expands `$VAR` in ExecStart. */
+export function quoteExecWord(word) {
+    return quoteSystemdValue(word).replaceAll('$', () => '$$');
+}
+/**
+ * Image that installs the package from npm, or from a local tarball when given, and runs `start` as
+ * the node user.
+ */
+export function formatDockerfile(options) {
+    const install = options.tarball === undefined
+        ? `RUN npm i -g telegram-ask@${options.version}`
+        : `COPY ${basename(options.tarball)} /tmp/pkg.tgz\nRUN npm i -g /tmp/pkg.tgz && rm /tmp/pkg.tgz`;
+    return `FROM node:24-slim
+ENV NODE_ENV=production TELEGRAM_ASK_CONFIG=/data/config.json HOST=0.0.0.0
+${install}
+RUN mkdir /data && chown node:node /data
+VOLUME /data
+USER node
+CMD ["telegram-ask","start"]
+`;
+}
+/** Compose file publishing `port` on loopback only, with a named volume for /data. */
+export function formatComposeYaml(port) {
+    return `name: telegram-ask
+services:
+  bot:
+    build: .
+    restart: unless-stopped
+    env_file: .env
+    ports:
+      - "127.0.0.1:${port}:${port}"
+    volumes:
+      - data:/data
+volumes:
+  data: {}
+`;
+}
+/** KEY=VALUE lines for the container; `OWNER_ID` is included only when known. */
+export function formatEnvFile(options) {
+    const lines = [
+        `BOT_TOKEN=${options.token}`,
+        `PORT=${options.port}`,
+        ...(options.ownerId === undefined ? [] : [`OWNER_ID=${options.ownerId}`]),
+    ];
+    return lines.join('\n') + '\n';
+}
+/** Quadlet .container unit; publishes `port` on loopback only and reads the env file. */
+export function formatQuadletContainer(options) {
+    return `[Unit]
+Description=telegram-ask service
+
+[Container]
+Image=localhost/telegram-ask:${options.version}
+ContainerName=telegram-ask
+Volume=telegram-ask-data:/data
+EnvironmentFile=${quoteSystemdValue(options.envFile)}
+PublishPort=127.0.0.1:${options.port}:${options.port}
+
+[Service]
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** User unit that runs `node cli start` with TELEGRAM_ASK_CONFIG pinned to `config`. */
+export function formatSystemdUnit(options) {
+    return `[Unit]
+Description=telegram-ask service
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Environment=${quoteSystemdValue(`TELEGRAM_ASK_CONFIG=${options.config}`)}
+ExecStart=${quoteExecWord(options.node)} ${quoteExecWord(options.cli)} start
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}

package/dist/install/types.js

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

package/dist/server/constants.js

@@ -0,0 +1,2 @@
+/** Request body cap; larger bodies get a 413. */
+export const MAX_BODY_BYTES = 65_536;

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export { statusInfoSchema } from './schema.js';
+export { createApiServer } from './server.js';

package/dist/server/schema.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+/** Shape of the /status response; `code` is present only while unpaired. */
+export const statusInfoSchema = z.discriminatedUnion('paired', [
+    z.object({ paired: z.literal(true), bot: z.string() }),
+    z.object({ paired: z.literal(false), code: z.string(), bot: z.string() }),
+]);

package/dist/server/server.js

@@ -0,0 +1,74 @@
+import Fastify from 'fastify';
+import { parseApprovalRequest, SendError } from '../approval/index.js';
+import { MAX_BODY_BYTES } from './constants.js';
+/**
+ * Builds the HTTP API (POST /request, GET /status) without listening. Aborting the connection
+ * cancels the pending request; errors return JSON bodies.
+ */
+export function createApiServer(service, status) {
+    // Pending requests can hang for minutes; close() shouldn't wait for them.
+    const app = Fastify({ bodyLimit: MAX_BODY_BYTES, forceCloseConnections: true });
+    // Take the body as text whatever the content type, so bad JSON gets our own 400.
+    app.removeAllContentTypeParsers();
+    app.addContentTypeParser('*', { parseAs: 'string' }, (_request, body, done) => done(null, body));
+    app.setNotFoundHandler((request, reply) => {
+        // Not new URL(): it throws on targets like '//'.
+        const path = request.url.split('?')[0];
+        if (path === '/request') {
+            return reply.code(405).header('Allow', 'POST').send({ error: 'method not allowed' });
+        }
+        if (path === '/status') {
+            return reply.code(405).header('Allow', 'GET').send({ error: 'method not allowed' });
+        }
+        return reply.code(404).send({ error: 'not found' });
+    });
+    app.setErrorHandler((error, request, reply) => {
+        if (error instanceof SendError) {
+            return reply.code(502).send({ error: 'failed to send Telegram message' });
+        }
+        if (error.statusCode === 413) {
+            // Drop the rest of the upload once the response is flushed.
+            reply.raw.once('finish', () => request.raw.destroy());
+            return reply.code(413).header('Connection', 'close').send({ error: 'request body too large' });
+        }
+        if (error.statusCode !== undefined && error.statusCode < 500) {
+            return reply.code(error.statusCode).send({ error: error.message });
+        }
+        console.error('unexpected error handling /request', error);
+        return reply.code(500).send({ error: 'internal server error' });
+    });
+    app.get('/status', async () => status());
+    app.post('/request', async (request, reply) => {
+        if (!status().paired) {
+            return reply.code(503).send({ error: 'not paired' });
+        }
+        let json;
+        try {
+            json = JSON.parse(request.body ?? '');
+        }
+        catch {
+            return reply.code(400).send({ error: 'body must be valid JSON' });
+        }
+        const parsed = parseApprovalRequest(json);
+        if (!parsed.ok) {
+            return reply.code(400).send({ error: parsed.error });
+        }
+        const controller = new AbortController();
+        reply.raw.on('close', () => {
+            if (!reply.raw.writableEnded) {
+                controller.abort();
+            }
+        });
+        // The client may have gone while the body was being read, before 'close' was observed.
+        if (reply.raw.destroyed) {
+            controller.abort();
+        }
+        const result = await service.request(parsed.value, controller.signal);
+        if (result.kind === 'cancelled') {
+            // Normally because the client is gone, so this write is a no-op.
+            return reply.code(500).send({ error: 'request was cancelled' });
+        }
+        return result.outcome;
+    });
+    return app;
+}

package/dist/server/types.js

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

package/dist/system/constants.js

@@ -0,0 +1,6 @@
+/** Matches `Linger=yes` in `loginctl show-user` output. */
+export const LINGER_ON_PATTERN = /Linger=yes/;
+/** Matches `Linger=no` in `loginctl show-user` output. */
+export const LINGER_OFF_PATTERN = /Linger=no/;
+/** How long to wait for Telegram when checking a token. */
+export const TOKEN_CHECK_TIMEOUT_SECONDS = 10;

package/dist/system/exec.js

@@ -0,0 +1,30 @@
+import { spawn } from 'node:child_process';
+/** Thrown by `realExec` when the binary doesn't exist. */
+export class MissingCommandError extends Error {
+    command;
+    constructor(command) {
+        super(`command ${JSON.stringify(command)} not found`);
+        this.name = 'MissingCommandError';
+        this.command = command;
+    }
+}
+/** Never rejects on a non-zero exit; rejects only when the binary doesn't exist. */
+export const realExec = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        env: options.env ?? process.env,
+        stdio: options.inherit ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => (stdout += chunk.toString()));
+    child.stderr?.on('data', (chunk) => (stderr += chunk.toString()));
+    child.on('error', (error) => {
+        if (error.code === 'ENOENT') {
+            reject(new MissingCommandError(command));
+        }
+        else {
+            reject(error);
+        }
+    });
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+});

package/dist/system/files.js

@@ -0,0 +1,50 @@
+import { closeSync, fchmodSync, fsyncSync, mkdirSync, openSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Writes `contents` to `path` via a temp file, fsync and rename, so readers never see a partial
+ * file. Creates the parent directory. A symlinked `path` is written through: the link is kept and
+ * its target replaced. On failure removes the temp file (best effort) and rethrows; an existing
+ * file is left as it was.
+ */
+export function writeFileAtomic(path, contents, mode) {
+    const target = resolveWriteTarget(path);
+    mkdirSync(dirname(target), { recursive: true });
+    const temp = `${target}.${process.pid}.tmp`;
+    try {
+        const fd = openSync(temp, 'w', mode);
+        try {
+            // The umask can strip bits when the file is created.
+            fchmodSync(fd, mode);
+            writeFileSync(fd, contents);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, target);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+            // Best effort: the original error is the one worth reporting.
+        }
+        throw error;
+    }
+}
+function resolveWriteTarget(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return path;
+        }
+        throw error;
+    }
+}
+/** True when `error` is a Node error with code `ENOENT`. */
+export function isMissingFileError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}

package/dist/system/host.js

@@ -0,0 +1,48 @@
+import { Api } from 'grammy';
+import net from 'node:net';
+import { LINGER_OFF_PATTERN, LINGER_ON_PATTERN, TOKEN_CHECK_TIMEOUT_SECONDS } from './constants.js';
+/** True when 127.0.0.1:`port` can be bound; any bind error counts as in use. */
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+    });
+}
+/**
+ * Enables systemd linger for `user` so the service survives logout. Never throws; prints the manual
+ * command if it can't.
+ */
+export async function ensureLinger(exec, user, print) {
+    const printFallback = () => print(`Run "loginctl enable-linger ${user}" so it keeps running after logout.`);
+    try {
+        const show = await exec('loginctl', ['show-user', user, '-p', 'Linger']);
+        if (show.code === 0 && LINGER_ON_PATTERN.test(show.stdout)) {
+            return;
+        }
+        if (show.code === 0 && !LINGER_OFF_PATTERN.test(show.stdout)) {
+            return;
+        }
+        const result = await exec('loginctl', ['enable-linger', user]);
+        if (result.code !== 0) {
+            printFallback();
+        }
+    }
+    catch {
+        printFallback();
+    }
+}
+/** Returns the bot username, or undefined on any failure. Never exposes the token or error text. */
+export async function validateToken(token, apiRoot) {
+    try {
+        // No global fetch here: Node's fetch rejects grammY's polyfilled AbortSignal on every call.
+        const botUser = await new Api(token, {
+            timeoutSeconds: TOKEN_CHECK_TIMEOUT_SECONDS,
+            ...(apiRoot === undefined ? {} : { apiRoot }),
+        }).getMe();
+        return botUser.username || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/system/index.js

@@ -0,0 +1,3 @@
+export { MissingCommandError, realExec } from './exec.js';
+export { ensureLinger, isPortFree, validateToken } from './host.js';
+export { isMissingFileError, writeFileAtomic } from './files.js';

package/dist/system/types.js

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