gerdur 0.0.0-probe → 1.0.0

package/dist/src/kyrie.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const os_1 = require("os");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const commander_1 = require("commander");
+const gradient_string_1 = __importDefault(require("gradient-string"));
+const kyrie_core_1 = require("kyrie-core");
+const prompts_1 = __importDefault(require("prompts"));
+const log_update_1 = __importDefault(require("log-update"));
+const p_queue_1 = __importDefault(require("p-queue"));
+const chalk_1 = __importDefault(require("chalk"));
+const true_case_path_1 = require("true-case-path");
+const signale_1 = __importDefault(require("./lib/signale"));
+const download_track_1 = __importDefault(require("./lib/download-track"));
+const config_1 = __importDefault(require("./lib/config"));
+const update_check_1 = __importDefault(require("./lib/update-check"));
+const auto_updater_1 = __importDefault(require("./lib/auto-updater"));
+const arl_setup_1 = require("./lib/arl-setup");
+const util_1 = require("./lib/util");
+const package_json_1 = __importDefault(require("../package.json"));
+// App info
+console.log((0, gradient_string_1.default)('red', 'yellow', 'orange')(`             ♥ kyrie - ${package_json_1.default.version} ♥         `) +
+    '\n' +
+    (0, gradient_string_1.default)('orange', 'yellow', 'red')(' ──────────────────────────────────────────────') +
+    '\n' +
+    (0, gradient_string_1.default)('red', 'yellow', 'orange')(' │ repo   https://github.com/soulwax/kyrie   │ ') +
+    '\n' +
+    (0, gradient_string_1.default)('red', 'yellow', 'orange')(' │ github https://github.com/soulwax        │ ') +
+    '\n' +
+    (0, gradient_string_1.default)('red', 'yellow', 'orange')(' ──────────────────────────────────────────────'));
+const cmd = new commander_1.Command()
+    .option('-q, --quality <quality>', 'The quality of the files to download: 128/320/flac ')
+    .option('-o, --output <template>', 'Output filename template')
+    .option('-u, --url <url>', 'Deezer album/artist/playlist/track url')
+    .option('-i, --input-file <file>', 'Downloads all urls listed in text file')
+    .option('-c, --concurrency <number>', 'Download concurrency for album, artists and playlist')
+    .option('-a, --set-arl <string>', 'Set arl cookie')
+    .option('-s, --setup', 'Run guided first-time setup (enter your arl cookie)')
+    .option('--experimental-login', 'Deprecated: email/password login is now offered by default')
+    .option('-w, --overwrite', 'Re-download and overwrite files that already exist')
+    .option('-d, --headless', 'Run in headless mode for scripting automation', false)
+    .option('-conf, --config-file <file>', 'Custom location to your config file', 'kyrie.config.json')
+    .option('-rfp, --resolve-full-path', 'Use absolute path for playlists')
+    .option('-cp, --create-playlist', 'Force create a playlist file for non playlists');
+if (process.pkg) {
+    cmd.option('-U, --update', 'Update this program to latest version');
+}
+const options = cmd.parse(process.argv).opts();
+// Support a bare `kyrie setup` subcommand as an alias for `--setup`.
+if (cmd.args[0] && cmd.args[0].toLowerCase() === 'setup') {
+    options.setup = true;
+    cmd.args.shift();
+}
+if (!options.url && cmd.args[0]) {
+    options.url = cmd.args[0];
+}
+if (options.headless && !options.quality) {
+    console.error(signale_1.default.error('Missing parameters --quality'));
+    console.error(signale_1.default.note('Quality must be provided with headless mode'));
+    process.exit(1);
+}
+if (options.headless && !options.url && !options.inputFile) {
+    console.error(signale_1.default.error('Missing parameters --url'));
+    console.error(signale_1.default.note('URL must be provided with headless mode'));
+    process.exit(1);
+}
+const conf = new config_1.default(options.configFile);
+if (conf.userConfigLocation) {
+    console.log(signale_1.default.info('Config loaded --> ' + conf.userConfigLocation));
+}
+const queue = new p_queue_1.default({ concurrency: Number(options.concurrency || conf.get('concurrency')) });
+const urlRegex = /https?:\/\/.*\w+\.\w+\/\w+/;
+const onCancel = () => {
+    console.info(signale_1.default.note('Aborted!'));
+    process.exit();
+};
+const startDownload = async (saveLayout, url, skipPrompt) => {
+    try {
+        if (!options.quality) {
+            const { musicQuality } = await (0, prompts_1.default)([
+                {
+                    type: 'select',
+                    name: 'musicQuality',
+                    message: 'Select music quality:',
+                    choices: [
+                        { title: 'MP3  - 128 kbps', value: '128' },
+                        { title: 'MP3  - 320 kbps', value: '320' },
+                        { title: 'FLAC - 1411 kbps', value: 'flac' },
+                    ],
+                    initial: 1,
+                },
+            ], { onCancel });
+            options.quality = musicQuality;
+        }
+        if (!url) {
+            const { query } = await (0, prompts_1.default)([
+                {
+                    type: 'text',
+                    name: 'query',
+                    message: 'Enter URL or search:',
+                    validate: (value) => (value ? true : false),
+                },
+            ], { onCancel });
+            url = query;
+        }
+        let searchData = null;
+        if (!url.match(urlRegex)) {
+            if (options.headless) {
+                throw new Error('Please provide a valid URL. Unknown URL: ' + url);
+            }
+            if (url.startsWith('artist:')) {
+                const { ARTIST } = await (0, kyrie_core_1.searchMusic)(url.replace('artist:', ''), ['ARTIST'], 50);
+                const choice = await (0, prompts_1.default)([
+                    {
+                        type: 'select',
+                        name: 'items',
+                        message: `Select one artist. (found ${ARTIST.data.length} artists)`,
+                        choices: ARTIST.data.map((a) => ({
+                            title: a.ART_NAME,
+                            value: a,
+                            description: `${a.NB_FAN} fans`,
+                        })),
+                    },
+                ], { onCancel });
+                console.log(signale_1.default.info('Fetching data. Please hold on.'));
+                url = `https://deezer.com/us/artist/${choice.items.ART_ID}`;
+            }
+            else if (url.startsWith('album:')) {
+                const { ALBUM } = await (0, kyrie_core_1.searchMusic)(url.replace('album:', ''), ['ALBUM'], 50);
+                const choice = await (0, prompts_1.default)([
+                    {
+                        type: 'select',
+                        name: 'items',
+                        message: `Select one album. (found ${ALBUM.data.length} albums)`,
+                        choices: ALBUM.data.map((a) => ({
+                            title: a.ALB_TITLE,
+                            value: a,
+                            description: `by ${a.ART_NAME}, ${a.NUMBER_TRACK} tracks`,
+                        })),
+                    },
+                ], { onCancel });
+                url = `https://deezer.com/us/album/${choice.items.ALB_ID}`;
+            }
+            else if (url.startsWith('playlist:')) {
+                const { PLAYLIST } = await (0, kyrie_core_1.searchMusic)(url.replace('playlist:', ''), ['PLAYLIST'], 50);
+                const choice = await (0, prompts_1.default)([
+                    {
+                        type: 'select',
+                        name: 'items',
+                        message: `Select one playlist. (found ${PLAYLIST.data.length} playlists)`,
+                        choices: PLAYLIST.data.map((p) => ({
+                            title: p.TITLE,
+                            value: p,
+                            description: `by ${p.PARENT_USERNAME}, ${p.NB_SONG} tracks`,
+                        })),
+                    },
+                ], { onCancel });
+                url = `https://deezer.com/us/playlist/${choice.items.PLAYLIST_ID}`;
+            }
+            else {
+                const { TRACK } = await (0, kyrie_core_1.searchMusic)(url, ['TRACK']);
+                searchData = {
+                    info: { type: 'track', id: url },
+                    linktype: 'track',
+                    linkinfo: {},
+                    tracks: TRACK.data.map((t) => {
+                        if (t.VERSION && !t.SNG_TITLE.includes(t.VERSION)) {
+                            t.SNG_TITLE += ' ' + t.VERSION;
+                        }
+                        return t;
+                    }),
+                };
+            }
+        }
+        else if (url.match(/playlist|artist/)) {
+            console.log(signale_1.default.info('Fetching data. Please hold on.'));
+        }
+        const data = searchData ? searchData : await (0, kyrie_core_1.parseInfo)(url);
+        if (!options.headless && data.tracks.length > 1) {
+            const choices = await (0, prompts_1.default)([
+                {
+                    type: 'multiselect',
+                    name: 'items',
+                    message: `Select songs to download. Total of ${data.tracks.length} tracks.`,
+                    choices: data.tracks.map((t) => ({
+                        title: t.SNG_TITLE,
+                        value: t,
+                        description: `Artist: ${t.ART_NAME}\nAlbum: ${t.ALB_TITLE}\nDuration: ${(0, util_1.formatSecondsReadable)(Number(t.DURATION))}`,
+                    })),
+                },
+            ], { onCancel });
+            data.tracks = choices.items;
+        }
+        if (data && data.tracks.length > 0) {
+            console.log(signale_1.default.info(`Proceeding to download ${data.tracks.length} tracks. Be patient.`));
+            if (data.linktype === 'playlist') {
+                const filteredTracks = data.tracks.filter((item, index, self) => index === self.findIndex((t) => t.SNG_ID === item.SNG_ID));
+                const duplicateTracks = data.tracks.length - filteredTracks.length;
+                if (duplicateTracks > 0) {
+                    data.tracks = filteredTracks
+                        .sort((a, b) => a.TRACK_POSITION - b.TRACK_POSITION)
+                        .map((t, i) => {
+                        t.TRACK_POSITION = i + 1;
+                        return t;
+                    });
+                    console.log(signale_1.default.warn(`Removed ${duplicateTracks} duplicate ${duplicateTracks > 1 ? 'tracks' : 'track'}.`));
+                }
+            }
+            const coverSizes = conf.get('coverSize');
+            const trackNumber = conf.get('trackNumber', true);
+            const fallbackTrack = conf.get('fallbackTrack', true);
+            const fallbackQuality = conf.get('fallbackQuality', true);
+            const overwrite = options.overwrite ?? conf.get('overwrite', false);
+            const resolveFullPath = options.resolveFullPath ?? conf.get('playlist.resolveFullPath');
+            const savedFiles = [];
+            let m3u8 = [];
+            await queue.addAll(data.tracks.map((track, index) => {
+                return async () => {
+                    const savedPath = await (0, download_track_1.default)({
+                        track,
+                        quality: options.quality,
+                        info: data.linkinfo,
+                        coverSizes,
+                        path: options.output ? options.output : saveLayout[data.linktype],
+                        totalTracks: data ? data.tracks.length : 10,
+                        trackNumber,
+                        fallbackTrack,
+                        fallbackQuality,
+                        overwrite,
+                        message: `(${index}/${data.tracks.length})`,
+                    });
+                    // Add to saved list
+                    if (savedPath) {
+                        m3u8.push((0, path_1.resolve)(process.env.SIMULATE ? savedPath : (0, true_case_path_1.trueCasePathSync)(savedPath)));
+                        savedFiles.push(savedPath);
+                    }
+                };
+            }));
+            // Display downloaded location
+            if (savedFiles.length > 0) {
+                const savedIn = new Set(savedFiles.map((l) => (0, path_1.dirname)(l)));
+                console.log(signale_1.default.info('Saved in ' + [...savedIn].map((d) => chalk_1.default.bgGreen(d)).join(', ')));
+            }
+            if ((options.createPlaylist || data.linktype === 'playlist') && !process.env.SIMULATE && m3u8.length > 1) {
+                const playlistDir = (0, util_1.commonPath)([...new Set(savedFiles.map(path_1.dirname))]);
+                const playlistFile = (0, path_1.join)(playlistDir, (0, util_1.sanitizeFilename)(data.linkinfo.TITLE || data.linkinfo.ALB_TITLE));
+                if (!resolveFullPath) {
+                    const resolvedPlaylistDir = (0, path_1.resolve)(playlistDir) + path_1.sep;
+                    m3u8 = m3u8.map((file) => file.replace(resolvedPlaylistDir, ''));
+                }
+                const m3u8Content = '#EXTM3U' + os_1.EOL + m3u8.sort().join(os_1.EOL);
+                (0, fs_1.writeFileSync)(playlistFile + '.m3u8', m3u8Content, { encoding: 'utf-8' });
+            }
+        }
+        else {
+            console.log(signale_1.default.info('No items to download!'));
+        }
+    }
+    catch (err) {
+        console.error(signale_1.default.error(err.message));
+    }
+    // Ask for new download
+    if (!options.headless && !skipPrompt) {
+        startDownload(saveLayout, '', skipPrompt);
+    }
+};
+/**
+ * Application init.
+ */
+const initApp = async () => {
+    if (options.setup) {
+        await (0, arl_setup_1.runSetup)(conf, options.headless, options.experimentalLogin);
+        return;
+    }
+    if (options.setArl) {
+        const configPath = conf.set('cookies.arl', options.setArl);
+        console.log(signale_1.default.info('cookies.arl set to --> ' + options.setArl));
+        console.log(signale_1.default.note(configPath));
+        process.exit();
+    }
+    (0, log_update_1.default)(signale_1.default.pending('Initializing session...'));
+    let arl = await (0, arl_setup_1.ensureArl)(conf, options.headless, options.experimentalLogin);
+    const login = async (cookie) => {
+        (0, log_update_1.default)(signale_1.default.pending('Verifying session...'));
+        await (0, kyrie_core_1.initDeezerApi)(cookie);
+        return (0, kyrie_core_1.getUser)();
+    };
+    let user;
+    try {
+        user = await login(arl);
+    }
+    catch (err) {
+        log_update_1.default.clear();
+        const newArl = await (0, arl_setup_1.recoverFromLoginFailure)(conf, options.headless, err, options.experimentalLogin);
+        if (!newArl) {
+            throw err;
+        }
+        arl = newArl;
+        user = await login(arl);
+    }
+    (0, log_update_1.default)(signale_1.default.success('Logged in as ' + user.BLOG_NAME));
+    log_update_1.default.done();
+    const saveLayout = conf.get('saveLayout');
+    if (options.inputFile) {
+        const urls = (0, fs_1.readFileSync)(options.inputFile, 'utf-8')
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.match(urlRegex));
+        if (!options.quality && !options.headless) {
+            for (const url of urls) {
+                console.log(signale_1.default.info('Starting download: ' + url));
+                await startDownload(saveLayout, url, true);
+            }
+        }
+        else {
+            await Promise.all(urls.map((url) => {
+                console.log(signale_1.default.info('Starting download: ' + url));
+                return startDownload(saveLayout, url, true);
+            }));
+        }
+    }
+    else {
+        startDownload(saveLayout, options.url, false);
+    }
+};
+if (options.update) {
+    (0, auto_updater_1.default)(package_json_1.default).catch((err) => {
+        console.error(signale_1.default.error(err.message));
+        process.exit(1);
+    });
+}
+else {
+    // Check for update
+    (0, update_check_1.default)(package_json_1.default);
+    // Init interface
+    initApp().catch((err) => {
+        console.error(signale_1.default.error(err.message));
+        process.exit(1);
+    });
+}

package/dist/src/lib/api-download.d.ts

@@ -0,0 +1,54 @@
+/// <reference types="node" />
+import type { trackType } from 'gerdur-core/types';
+/** Music quality accepted by the API. */
+export type Quality = '128' | '320' | 'flac' | 1 | 3 | 9;
+export interface GetTrackBufferOptions {
+    /** Album cover size (px) embedded in tags. Default 500. */
+    coverSize?: number;
+    /**
+     * If the requested quality is unavailable, try lower qualities (320 -> 128)
+     * before giving up. Default true.
+     */
+    fallbackQuality?: boolean;
+}
+/**
+ * Download, decrypt, and tag a single track entirely in memory.
+ *
+ * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
+ * is not available for download. Nothing is written to disk and nothing is
+ * logged.
+ *
+ * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
+ * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
+ */
+export declare const getTrackBuffer: (track: trackType, quality?: Quality, { coverSize, fallbackQuality }?: GetTrackBufferOptions) => Promise<Buffer | null>;
+export interface DownloadTrackOptions extends GetTrackBufferOptions {
+    /**
+     * Output file path or a `saveLayout` template (e.g. `{ART_NAME} - {SNG_TITLE}`).
+     * The correct extension (`.mp3` / `.flac`) is appended automatically.
+     * Default: `{ART_NAME} - {SNG_TITLE}`.
+     */
+    output?: string;
+    /** Album info used to resolve album-level template tokens. */
+    albumInfo?: {
+        [key: string]: any;
+    };
+    /** Prefix the filename with the track number. Default false. */
+    trackNumber?: boolean;
+    /** Re-download even if the destination file already exists. Default false. */
+    overwrite?: boolean;
+}
+export interface DownloadResult {
+    /** The path the file was written to (or would have been, if skipped). */
+    path: string;
+    /** True if the file was written; false if skipped because it already existed. */
+    written: boolean;
+}
+/**
+ * Download a single track to disk (silent). Resolves the destination path from
+ * the `output` template, skips existing files unless `overwrite` is set, and
+ * creates parent directories as needed.
+ *
+ * Returns `{path, written}`, or `null` if the track was not available.
+ */
+export declare const downloadTrackToFile: (track: trackType, quality?: Quality, options?: DownloadTrackOptions) => Promise<DownloadResult | null>;

package/dist/src/lib/api-download.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadTrackToFile = exports.getTrackBuffer = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const got_1 = __importDefault(require("got"));
+const gerdur_core_1 = require("gerdur-core");
+const decrypt_1 = require("./decrypt");
+const util_1 = require("./util");
+const QUALITY_MAP = {
+    '1': { q: 1, ext: '.mp3', size: 'FILESIZE_MP3_128' },
+    '128': { q: 1, ext: '.mp3', size: 'FILESIZE_MP3_128' },
+    '3': { q: 3, ext: '.mp3', size: 'FILESIZE_MP3_320' },
+    '320': { q: 3, ext: '.mp3', size: 'FILESIZE_MP3_320' },
+    '9': { q: 9, ext: '.flac', size: 'FILESIZE_FLAC' },
+    flac: { q: 9, ext: '.flac', size: 'FILESIZE_FLAC' },
+};
+const resolveQuality = (quality) => {
+    const key = String(quality).toLowerCase();
+    return QUALITY_MAP[key] ?? QUALITY_MAP['320'];
+};
+/**
+ * Download, decrypt, and tag a single track entirely in memory.
+ *
+ * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
+ * is not available for download. Nothing is written to disk and nothing is
+ * logged.
+ *
+ * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
+ * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
+ */
+const getTrackBuffer = async (track, quality = '320', { coverSize = 500, fallbackQuality = true } = {}) => {
+    const order = fallbackQuality ? [quality, '320', '128'] : [quality];
+    const tried = new Set();
+    for (const q of order) {
+        const { q: qNum } = resolveQuality(q);
+        if (tried.has(qNum)) {
+            continue;
+        }
+        tried.add(qNum);
+        let trackData;
+        try {
+            trackData = await (0, gerdur_core_1.getTrackDownloadUrl)(track, qNum);
+        }
+        catch (err) {
+            if (err instanceof gerdur_core_1.GeoBlocked) {
+                throw err;
+            }
+            trackData = null;
+        }
+        if (!trackData) {
+            continue;
+        }
+        const { body } = await (0, got_1.default)(trackData.trackUrl, { responseType: 'buffer' });
+        const decrypted = trackData.isEncrypted ? (0, decrypt_1.decryptDownload)(body, track.SNG_ID) : body;
+        return (0, gerdur_core_1.addTrackTags)(decrypted, track, coverSize);
+    }
+    return null;
+};
+exports.getTrackBuffer = getTrackBuffer;
+/**
+ * Download a single track to disk (silent). Resolves the destination path from
+ * the `output` template, skips existing files unless `overwrite` is set, and
+ * creates parent directories as needed.
+ *
+ * Returns `{path, written}`, or `null` if the track was not available.
+ */
+const downloadTrackToFile = async (track, quality = '320', options = {}) => {
+    const { output = '{ART_NAME} - {SNG_TITLE}', albumInfo = {}, trackNumber = false, overwrite = false } = options;
+    const { ext } = resolveQuality(quality);
+    const savePath = (0, util_1.saveLayout)({ track, album: albumInfo, path: output, trackNumber, minimumIntegerDigits: 2 }) + ext;
+    if ((0, fs_1.existsSync)(savePath) && !overwrite) {
+        return { path: savePath, written: false };
+    }
+    const buffer = await (0, exports.getTrackBuffer)(track, quality, options);
+    if (!buffer) {
+        return null;
+    }
+    const dir = (0, path_1.dirname)(savePath);
+    if (dir && !(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(savePath, buffer);
+    return { path: savePath, written: true };
+};
+exports.downloadTrackToFile = downloadTrackToFile;

package/dist/src/lib/arl-setup.d.ts

@@ -0,0 +1,82 @@
+import type Config from './config';
+/**
+ * True when we are attached to an interactive terminal and not running in a
+ * scripted / headless context. Only then is it safe to block on a prompt.
+ */
+export declare const isInteractive: (headless: boolean) => boolean;
+/**
+ * Print short, copy-pasteable instructions on where to obtain a Deezer arl cookie.
+ */
+export declare const printArlInstructions: () => void;
+/**
+ * Interactively ask the user to paste an arl cookie and persist it to config.
+ *
+ * Returns the entered arl, or `null` if the user aborted / gave nothing.
+ * The caller is responsible for only invoking this in an interactive context.
+ */
+export declare const promptForArl: (conf: Config) => Promise<string | null>;
+/**
+ * Resolve email/password credentials from (in order): explicit config, then the
+ * `GERDUR_EMAIL` / `GERDUR_PASSWORD` environment variables. Used for non-interactive
+ * login attempts. Returns `null` if either half is missing.
+ */
+export declare const resolveCredentials: (conf: Config) => {
+    email: string;
+    password: string;
+} | null;
+/**
+ * Attempt an email/password login and, on success, persist the fetched arl.
+ * The password itself is never written to disk by this function.
+ *
+ * Returns the arl on success, or `null` on any failure (the caller should fall
+ * back to pasting an arl).
+ */
+export declare const tryEmailLogin: (conf: Config, email: string, password: string, { persistCredentials }?: {
+    persistCredentials?: boolean | undefined;
+}) => Promise<string | null>;
+/**
+ * Interactively prompt for email + password (password masked), attempt login,
+ * and persist the arl on success. Offers to save the credentials to config
+ * (with a plaintext warning) if the login worked.
+ *
+ * Returns the arl on success, or `null` on failure/cancel so the caller can
+ * fall back to pasting an arl.
+ */
+export declare const promptForEmailLogin: (conf: Config) => Promise<string | null>;
+/**
+ * Interactive picker for how to configure an arl.
+ *
+ * Offers email/password login (which fetches the arl automatically via Deezer's
+ * mobile OAuth flow) and pasting an arl. Email login falls back to arl paste if
+ * it fails. The `_experimentalLogin` parameter is retained for backward
+ * compatibility and no longer gates the email option.
+ *
+ * Returns the arl on success or `null` if nothing was configured.
+ */
+export declare const chooseAndConfigureArl: (conf: Config, _experimentalLogin?: boolean) => Promise<string | null>;
+/**
+ * Ensure a usable arl is configured before attempting to log in.
+ *
+ * When no user-supplied arl exists (empty or still the bundled default) and we
+ * are in an interactive terminal, print instructions and prompt for one.
+ * In non-interactive / headless contexts this is a no-op so existing scripted
+ * behavior is preserved.
+ *
+ * Returns the arl to use for the session.
+ */
+export declare const ensureArl: (conf: Config, headless: boolean, experimentalLogin?: boolean) => Promise<string>;
+/**
+ * On-demand guided setup, triggered by `gerdur setup` / `--setup`.
+ *
+ * Always prints instructions and prompts for an arl (even when one is already
+ * configured), so users can (re)configure without hunting for the flag.
+ * Requires an interactive terminal.
+ */
+export declare const runSetup: (conf: Config, headless: boolean, experimentalLogin?: boolean) => Promise<void>;
+/**
+ * Handle a failed login by offering to enter a fresh arl and retrying.
+ *
+ * Returns the new arl if the user provided one, otherwise `null` (and the
+ * original error should be surfaced by the caller).
+ */
+export declare const recoverFromLoginFailure: (conf: Config, headless: boolean, err: Error, experimentalLogin?: boolean) => Promise<string | null>;