@semics-tech/mongolite 1.2.0 → 1.3.0

package/dist/cjs/cli/explorer.js

@@ -0,0 +1,929 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Explorer = void 0;
+/**
+ * The guided MongoLite explorer.
+ *
+ * The flow is deliberately linear — pick a database, pick a collection, pick
+ * something to do — and every step offers real choices derived from the data
+ * rather than asking the user to type something they have to know already.
+ * MongoDB syntax stays available under "Advanced", and every guided query
+ * prints the filter it built, so the CLI teaches the syntax instead of hiding
+ * it.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const index_js_1 = require("../index.js");
+const discover_js_1 = require("./discover.js");
+const schema_js_1 = require("./schema.js");
+const filter_builder_js_1 = require("./filter-builder.js");
+const format_js_1 = require("./format.js");
+const ui_js_1 = require("./ui.js");
+class Explorer {
+    constructor(options = {}) {
+        this.options = options;
+        this.client = null;
+        this.dbPath = null;
+        this.collectionName = null;
+        this.schema = null;
+        this.lastSql = null;
+        this.lastQuery = null;
+        /**
+         * `-d`/`-c` are a starting point, not a preference. Once they have been
+         * honoured they are forgotten, otherwise "open a different database" would
+         * take you straight back to the one on the command line.
+         */
+        this.startingDatabaseUsed = false;
+        this.startingCollectionUsed = false;
+        this.sampleSize = options.sampleSize ?? 200;
+        this.pageSize = options.pageSize ?? 20;
+    }
+    // ---------------------------------------------------------------- lifecycle
+    async run() {
+        (0, ui_js_1.info)(`${ui_js_1.style.bold('MongoLite')} ${ui_js_1.style.grey('· interactive explorer')}`);
+        (0, ui_js_1.info)(ui_js_1.style.grey('Ctrl+C to quit at any point.\n'));
+        try {
+            for (;;) {
+                if (!this.client) {
+                    const connected = await this.chooseDatabase();
+                    if (!connected)
+                        return;
+                }
+                if (!this.collectionName) {
+                    const chosen = await this.chooseCollection();
+                    if (chosen === 'quit')
+                        return;
+                    if (chosen === 'switch-database') {
+                        await this.disconnect();
+                        continue;
+                    }
+                }
+                const outcome = await this.collectionMenu();
+                if (outcome === 'quit')
+                    return;
+                if (outcome === 'switch-collection') {
+                    this.collectionName = null;
+                    this.schema = null;
+                }
+                if (outcome === 'switch-database') {
+                    await this.disconnect();
+                    this.collectionName = null;
+                    this.schema = null;
+                }
+            }
+        }
+        finally {
+            await this.disconnect();
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch {
+                // Closing a database we may never have opened is not worth reporting.
+            }
+        }
+        this.client = null;
+        this.dbPath = null;
+    }
+    // ------------------------------------------------------------ step 1: file
+    async chooseDatabase() {
+        // An explicit -d wins the first time round, as long as it is usable.
+        if (this.options.database && !this.startingDatabaseUsed) {
+            this.startingDatabaseUsed = true;
+            const resolved = (0, discover_js_1.resolveDatabasePath)(this.options.database);
+            if ((0, discover_js_1.databaseExists)(resolved)) {
+                if (await this.connect(resolved))
+                    return true;
+            }
+            else {
+                (0, ui_js_1.warn)(`No database at ${ui_js_1.style.bold(resolved)} — pick one below.`);
+            }
+        }
+        for (;;) {
+            const candidates = (0, discover_js_1.findDatabaseFiles)(process.cwd());
+            const choices = candidates.map((candidate) => ({
+                label: candidate.relativePath,
+                value: candidate.path,
+                hint: `${(0, discover_js_1.formatBytes)(candidate.sizeBytes)} · ${(0, discover_js_1.formatRelativeTime)(candidate.modified)}`,
+            }));
+            if (choices.length === 0) {
+                (0, ui_js_1.warn)('No .db/.sqlite files found in this directory.');
+            }
+            choices.push({ label: 'Enter a path manually…', value: '__manual__' });
+            choices.push({ label: 'Quit', value: '__quit__' });
+            let picked;
+            try {
+                picked = await (0, ui_js_1.select)({
+                    message: 'Which database do you want to open?',
+                    choices,
+                    hint: '  ↑/↓ move · type to filter · enter to open',
+                });
+            }
+            catch (err) {
+                if (err instanceof ui_js_1.PromptCancelledError)
+                    return false;
+                throw err;
+            }
+            if (picked === '__quit__')
+                return false;
+            const target = picked === '__manual__'
+                ? (0, discover_js_1.resolveDatabasePath)(await (0, ui_js_1.text)({
+                    message: 'Path to the database file',
+                    defaultValue: node_path_1.default.join(process.cwd(), 'mongolite.db'),
+                }))
+                : picked;
+            if (!(0, discover_js_1.databaseExists)(target)) {
+                (0, ui_js_1.error)(`No file at ${target}`);
+                continue;
+            }
+            if (await this.connect(target))
+                return true;
+        }
+    }
+    async connect(dbPath) {
+        try {
+            const client = new index_js_1.MongoLite(dbPath, { verbose: this.options.verbose });
+            await client.connect();
+            this.client = client;
+            this.dbPath = dbPath;
+            (0, ui_js_1.success)(`Opened ${ui_js_1.style.bold(node_path_1.default.relative(process.cwd(), dbPath) || dbPath)}`);
+            return true;
+        }
+        catch (err) {
+            (0, ui_js_1.error)(`Could not open that database: ${message(err)}`);
+            return false;
+        }
+    }
+    // ------------------------------------------------------ step 2: collection
+    async chooseCollection() {
+        const client = this.requireClient();
+        let collections;
+        try {
+            collections = await (0, discover_js_1.listCollectionInfo)(client.database);
+        }
+        catch (err) {
+            (0, ui_js_1.error)(`Could not read the collections: ${message(err)}`);
+            return 'switch-database';
+        }
+        const usable = collections.filter((collection) => collection.isMongoLite);
+        const foreign = collections.filter((collection) => !collection.isMongoLite);
+        if (usable.length === 0) {
+            (0, ui_js_1.warn)('This database has no MongoLite collections.');
+            if (foreign.length > 0) {
+                (0, ui_js_1.info)(ui_js_1.style.grey(`  It does contain ${foreign.length} other table(s): ${foreign
+                    .map((table) => table.name)
+                    .slice(0, 5)
+                    .join(', ')}`));
+                (0, ui_js_1.info)(ui_js_1.style.grey('  You can still inspect them with the raw SQL option.'));
+            }
+            const next = await (0, ui_js_1.select)({
+                message: 'What now?',
+                choices: [
+                    { label: 'Open a different database', value: 'switch-database' },
+                    { label: 'Run raw SQL against this one', value: 'sql' },
+                    { label: 'Quit', value: 'quit' },
+                ],
+            });
+            if (next === 'sql') {
+                await this.runRawSql();
+                return this.chooseCollection();
+            }
+            return next;
+        }
+        // An explicit -c only counts the first time, and only if it is really there.
+        if (this.options.collection && !this.startingCollectionUsed) {
+            this.startingCollectionUsed = true;
+            const match = usable.find((collection) => collection.name === this.options.collection);
+            if (match) {
+                await this.useCollection(match.name);
+                return 'ok';
+            }
+            (0, ui_js_1.warn)(`No collection named "${this.options.collection}" in this database.`);
+        }
+        const choices = usable.map((collection) => ({
+            label: collection.name,
+            value: collection.name,
+            hint: `${collection.count.toLocaleString()} document${collection.count === 1 ? '' : 's'}`,
+        }));
+        choices.push({ label: 'Open a different database', value: '__switch__' });
+        choices.push({ label: 'Quit', value: '__quit__' });
+        let picked;
+        try {
+            picked = await (0, ui_js_1.select)({ message: 'Which collection?', choices });
+        }
+        catch (err) {
+            if (err instanceof ui_js_1.PromptCancelledError)
+                return 'switch-database';
+            throw err;
+        }
+        if (picked === '__quit__')
+            return 'quit';
+        if (picked === '__switch__')
+            return 'switch-database';
+        await this.useCollection(picked);
+        return 'ok';
+    }
+    async useCollection(name) {
+        this.collectionName = name;
+        this.lastQuery = null;
+        const collection = this.collection();
+        try {
+            const sample = (await collection.find({}).limit(this.sampleSize).toArray());
+            this.schema = (0, schema_js_1.inferSchema)(sample);
+            const total = await collection.countDocuments({});
+            const fieldCount = this.schema.fields.length;
+            (0, ui_js_1.info)(ui_js_1.style.grey(`  ${total.toLocaleString()} documents · ${fieldCount} field${fieldCount === 1 ? '' : 's'} inferred from ${sample.length.toLocaleString()} sampled`));
+            if (total === 0) {
+                (0, ui_js_1.warn)('This collection is empty, so there is not much to explore yet.');
+            }
+        }
+        catch (err) {
+            (0, ui_js_1.warn)(`Could not sample "${name}": ${message(err)}`);
+            this.schema = { sampled: 0, fields: [] };
+        }
+    }
+    // -------------------------------------------------------- step 3: what now
+    async collectionMenu() {
+        const choices = [
+            { label: 'Browse documents', value: 'browse', hint: '— page through everything' },
+            { label: 'Find documents', value: 'find', hint: '— build a filter step by step' },
+            { label: 'Count documents', value: 'count', hint: '— how many match a filter' },
+            { label: 'List the values in a field', value: 'distinct', hint: '— distinct values' },
+            { label: 'Count documents by field', value: 'group', hint: '— e.g. orders per status' },
+            { label: 'Show the fields in this collection', value: 'schema' },
+            { label: 'Show indexes', value: 'indexes' },
+            { label: 'Advanced', value: 'json-filter', separator: true },
+            { label: 'Write a MongoDB filter yourself', value: 'json-filter', hint: '— JSON' },
+            { label: 'Run raw SQL', value: 'sql' },
+            { label: 'Show the SQL for the last query', value: 'last-sql' },
+            { label: ' ', value: 'quit', separator: true },
+            { label: 'Switch collection', value: 'switch-collection' },
+            { label: 'Open a different database', value: 'switch-database' },
+            { label: 'Quit', value: 'quit' },
+        ];
+        let action;
+        try {
+            action = await (0, ui_js_1.select)({
+                message: `${this.collectionName} — what would you like to do?`,
+                choices,
+                pageSize: 16,
+            });
+        }
+        catch (err) {
+            if (err instanceof ui_js_1.PromptCancelledError)
+                return 'switch-collection';
+            throw err;
+        }
+        try {
+            switch (action) {
+                case 'browse':
+                    await this.runQuery({ filter: {}, sort: null, description: 'all documents' });
+                    break;
+                case 'find':
+                    await this.guidedFind();
+                    break;
+                case 'count':
+                    await this.countFlow();
+                    break;
+                case 'distinct':
+                    await this.distinctFlow();
+                    break;
+                case 'group':
+                    await this.groupFlow();
+                    break;
+                case 'schema':
+                    await this.showSchema();
+                    break;
+                case 'indexes':
+                    await this.showIndexes();
+                    break;
+                case 'json-filter':
+                    await this.jsonFilterFlow();
+                    break;
+                case 'sql':
+                    await this.runRawSql();
+                    break;
+                case 'last-sql':
+                    this.showLastSql();
+                    await (0, ui_js_1.pause)();
+                    break;
+                case 'switch-collection':
+                    return 'switch-collection';
+                case 'switch-database':
+                    return 'switch-database';
+                case 'quit':
+                    return 'quit';
+            }
+        }
+        catch (err) {
+            if (!(err instanceof ui_js_1.PromptCancelledError)) {
+                (0, ui_js_1.error)(message(err));
+                await (0, ui_js_1.pause)();
+            }
+        }
+        return 'stay';
+    }
+    // ------------------------------------------------------------ guided query
+    async guidedFind() {
+        const conditions = await this.buildConditions();
+        if (conditions === null)
+            return;
+        let filter = {};
+        let description = 'all documents';
+        if (conditions.length > 0) {
+            const mode = conditions.length === 1
+                ? 'all'
+                : await (0, ui_js_1.select)({
+                    message: 'Should documents match…',
+                    choices: [
+                        { label: 'all of these conditions', value: 'all', hint: '— AND' },
+                        { label: 'any of these conditions', value: 'any', hint: '— OR' },
+                    ],
+                });
+            filter = (0, filter_builder_js_1.combineConditions)(conditions, mode);
+            description = conditions
+                .map((condition) => (0, filter_builder_js_1.describeCondition)(condition))
+                .join(mode === 'all' ? ' and ' : ' or ');
+        }
+        const sort = await this.chooseSort();
+        await this.runQuery({ filter, sort, description });
+    }
+    /** Collect conditions until the user is done. Returns null when cancelled. */
+    async buildConditions(existing = []) {
+        const conditions = [...existing];
+        for (;;) {
+            if (conditions.length > 0) {
+                (0, ui_js_1.heading)('Conditions so far');
+                conditions.forEach((condition, index) => {
+                    (0, ui_js_1.info)(`  ${index + 1}. ${(0, filter_builder_js_1.describeCondition)(condition)}`);
+                });
+                (0, ui_js_1.info)('');
+            }
+            const choices = [
+                {
+                    label: conditions.length === 0 ? 'Add a condition' : 'Add another condition',
+                    value: 'add',
+                },
+                {
+                    label: conditions.length === 0 ? 'Run without any filter' : 'Run the query',
+                    value: 'run',
+                },
+            ];
+            if (conditions.length > 0)
+                choices.push({ label: 'Remove a condition', value: 'remove' });
+            choices.push({ label: 'Cancel', value: 'cancel' });
+            let step;
+            try {
+                step = await (0, ui_js_1.select)({ message: 'Build your query', choices });
+            }
+            catch (err) {
+                if (err instanceof ui_js_1.PromptCancelledError)
+                    return null;
+                throw err;
+            }
+            if (step === 'cancel')
+                return null;
+            if (step === 'run')
+                return conditions;
+            if (step === 'remove') {
+                const index = await (0, ui_js_1.select)({
+                    message: 'Remove which condition?',
+                    choices: conditions.map((condition, position) => ({
+                        label: (0, filter_builder_js_1.describeCondition)(condition),
+                        value: position,
+                    })),
+                });
+                conditions.splice(index, 1);
+                continue;
+            }
+            const condition = await this.buildOneCondition();
+            if (condition)
+                conditions.push(condition);
+        }
+    }
+    async buildOneCondition() {
+        const schema = this.schema;
+        if (!schema || schema.fields.length === 0) {
+            (0, ui_js_1.warn)('No fields were found in this collection, so there is nothing to filter on.');
+            return null;
+        }
+        let field;
+        try {
+            field = await (0, ui_js_1.select)({
+                message: 'Which field?',
+                choices: [
+                    ...schema.fields.map((candidate) => ({
+                        label: candidate.path,
+                        value: candidate,
+                        hint: (0, schema_js_1.describeField)(candidate),
+                    })),
+                    { label: 'Type a field name myself…', value: '__custom__' },
+                ],
+                pageSize: 14,
+            });
+        }
+        catch (err) {
+            if (err instanceof ui_js_1.PromptCancelledError)
+                return null;
+            throw err;
+        }
+        const resolved = field === '__custom__'
+            ? {
+                path: await (0, ui_js_1.text)({
+                    message: 'Field name (dot notation for nested fields, e.g. address.city)',
+                }),
+                types: ['string'],
+                primaryType: 'string',
+                count: 0,
+                presence: 0,
+                examples: [],
+                lowCardinality: false,
+            }
+            : field;
+        const operators = (0, filter_builder_js_1.operatorsFor)(resolved);
+        let operatorId;
+        try {
+            operatorId = await (0, ui_js_1.select)({
+                message: `${resolved.path} …`,
+                choices: operators.map((operator) => ({
+                    label: operator.label,
+                    value: operator.id,
+                    hint: operator.hint ? `— ${operator.hint}` : undefined,
+                })),
+                pageSize: 14,
+            });
+        }
+        catch (err) {
+            if (err instanceof ui_js_1.PromptCancelledError)
+                return null;
+            throw err;
+        }
+        const operator = operators.find((candidate) => candidate.id === operatorId);
+        if (!operator)
+            return null;
+        // Values are parsed as the element type for array fields, so
+        // "tags contains work" compares against the strings inside the array.
+        const valueType = resolved.primaryType === 'array'
+            ? (resolved.elementTypes?.find((type) => type !== 'null') ?? 'string')
+            : resolved.primaryType;
+        const values = [];
+        try {
+            if (operator.arity === 'one') {
+                values.push(await this.askForValue(resolved, valueType, operator.valuePrompt ?? 'Value'));
+            }
+            else if (operator.arity === 'two') {
+                values.push(await this.askForValue(resolved, valueType, operator.valuePrompt ?? 'From'));
+                values.push(await this.askForValue(resolved, valueType, operator.secondValuePrompt ?? 'To'));
+            }
+            else if (operator.arity === 'many') {
+                const raw = await (0, ui_js_1.text)({
+                    message: operator.valuePrompt ?? 'Values (comma separated)',
+                    validate: (input) => {
+                        try {
+                            (0, filter_builder_js_1.parseValueList)(input, valueType);
+                            return undefined;
+                        }
+                        catch (err) {
+                            return message(err);
+                        }
+                    },
+                });
+                values.push(...(0, filter_builder_js_1.parseValueList)(raw, valueType));
+            }
+        }
+        catch (err) {
+            if (err instanceof ui_js_1.PromptCancelledError)
+                return null;
+            throw err;
+        }
+        return { field: resolved.path, operator: operatorId, values, fieldType: valueType };
+    }
+    /**
+     * Ask for one value. When the field has few distinct values in the sample we
+     * offer them as a menu — no typing, no guessing at spelling or casing.
+     */
+    async askForValue(field, valueType, prompt) {
+        if (field.lowCardinality && field.distinctValues && field.distinctValues.length > 1) {
+            const picked = await (0, ui_js_1.select)({
+                message: prompt,
+                choices: [
+                    ...field.distinctValues.map((value) => ({
+                        label: (0, format_js_1.formatCell)(value),
+                        value,
+                    })),
+                    { label: 'Something else…', value: '__other__' },
+                ],
+                hint: ui_js_1.style.grey(`  values seen in ${field.count} sampled document(s)`),
+                pageSize: 14,
+            });
+            if (picked !== '__other__')
+                return picked;
+        }
+        const raw = await (0, ui_js_1.text)({
+            message: prompt,
+            hint: field.examples.length
+                ? ui_js_1.style.grey(`  examples: ${field.examples.slice(0, 3).map(format_js_1.formatCell).join(', ')}`)
+                : undefined,
+            validate: (input) => {
+                try {
+                    (0, filter_builder_js_1.parseValue)(input, valueType);
+                    return undefined;
+                }
+                catch (err) {
+                    return message(err);
+                }
+            },
+        });
+        return (0, filter_builder_js_1.parseValue)(raw, valueType);
+    }
+    async chooseSort() {
+        const schema = this.schema;
+        if (!schema || schema.fields.length === 0)
+            return null;
+        const sortable = schema.fields.filter((field) => ['string', 'number', 'date', 'boolean'].includes(field.primaryType));
+        if (sortable.length === 0)
+            return null;
+        const field = await (0, ui_js_1.select)({
+            message: 'Sort the results by…',
+            choices: [
+                { label: "Don't sort", value: null },
+                ...sortable.map((candidate) => ({
+                    label: candidate.path,
+                    value: candidate.path,
+                    hint: (0, schema_js_1.describeField)(candidate),
+                })),
+            ],
+            pageSize: 12,
+        });
+        if (!field)
+            return null;
+        const direction = await (0, ui_js_1.select)({
+            message: `Sort ${field}…`,
+            choices: [
+                { label: 'ascending', value: 1, hint: '— A→Z, smallest first, oldest first' },
+                { label: 'descending', value: -1, hint: '— Z→A, largest first, newest first' },
+            ],
+        });
+        return { [field]: direction };
+    }
+    // -------------------------------------------------------------- run & view
+    async runQuery(query) {
+        this.lastQuery = query;
+        const collection = this.collection();
+        let total;
+        try {
+            total = await collection.countDocuments(query.filter);
+        }
+        catch (err) {
+            (0, ui_js_1.error)(`That query could not run: ${message(err)}`);
+            await (0, ui_js_1.pause)();
+            return;
+        }
+        (0, ui_js_1.heading)('Query');
+        (0, ui_js_1.info)(`  ${ui_js_1.style.grey('matching')} ${query.description}`);
+        (0, ui_js_1.info)(`  ${ui_js_1.style.grey('filter')}   ${JSON.stringify(query.filter)}`);
+        if (query.sort)
+            (0, ui_js_1.info)(`  ${ui_js_1.style.grey('sort')}     ${JSON.stringify(query.sort)}`);
+        (0, ui_js_1.info)(`  ${ui_js_1.style.grey('matches')}  ${ui_js_1.style.bold(total.toLocaleString())} document(s)`);
+        if (total === 0) {
+            (0, ui_js_1.info)('');
+            (0, ui_js_1.info)(ui_js_1.style.grey('  Nothing matched. Try a looser condition, or check the field spelling.'));
+            await (0, ui_js_1.pause)();
+            return;
+        }
+        let columns = this.schema ? (0, schema_js_1.defaultColumns)(this.schema) : ['_id'];
+        let offset = 0;
+        for (;;) {
+            const cursor = collection.find(query.filter).skip(offset).limit(this.pageSize);
+            if (query.sort)
+                cursor.sort(query.sort);
+            this.lastSql = cursor.toSQL();
+            let docs;
+            try {
+                docs = (await cursor.toArray());
+            }
+            catch (err) {
+                (0, ui_js_1.error)(`Could not fetch results: ${message(err)}`);
+                await (0, ui_js_1.pause)();
+                return;
+            }
+            if (docs.length === 0 && offset > 0) {
+                (0, ui_js_1.info)(ui_js_1.style.grey('  No more documents.'));
+                offset = Math.max(0, offset - this.pageSize);
+                continue;
+            }
+            (0, ui_js_1.info)('');
+            (0, ui_js_1.info)((0, format_js_1.renderTable)(docs, { columns, startIndex: offset }));
+            (0, ui_js_1.info)(ui_js_1.style.grey(`  showing ${offset + 1}-${offset + docs.length} of ${total.toLocaleString()}`));
+            (0, ui_js_1.info)('');
+            const choices = [];
+            if (offset + docs.length < total) {
+                choices.push({ label: `Show the next ${this.pageSize}`, value: 'next' });
+            }
+            if (offset > 0)
+                choices.push({ label: 'Show the previous page', value: 'prev' });
+            choices.push({ label: 'View one document in full', value: 'view' });
+            choices.push({ label: 'Choose which columns to show', value: 'columns' });
+            choices.push({ label: 'Save these results to a JSON file', value: 'export' });
+            choices.push({ label: 'Show the SQL this ran', value: 'sql' });
+            choices.push({ label: 'Change the filter', value: 'refine' });
+            choices.push({ label: 'Back to the menu', value: 'done' });
+            let action;
+            try {
+                action = await (0, ui_js_1.select)({ message: 'Results', choices, pageSize: 12 });
+            }
+            catch (err) {
+                if (err instanceof ui_js_1.PromptCancelledError)
+                    return;
+                throw err;
+            }
+            switch (action) {
+                case 'next':
+                    offset += this.pageSize;
+                    break;
+                case 'prev':
+                    offset = Math.max(0, offset - this.pageSize);
+                    break;
+                case 'view': {
+                    const doc = await (0, ui_js_1.select)({
+                        message: 'Which document?',
+                        choices: docs.map((candidate, index) => ({
+                            label: `${offset + index + 1}. ${(0, format_js_1.formatCell)(candidate._id)}`,
+                            value: candidate,
+                            hint: columns
+                                .filter((column) => column !== '_id')
+                                .slice(0, 2)
+                                .map((column) => (0, format_js_1.formatCell)((0, schema_js_1.getPath)(candidate, column)))
+                                .join(' · '),
+                        })),
+                        pageSize: 12,
+                    });
+                    (0, ui_js_1.heading)('Document');
+                    (0, ui_js_1.info)((0, format_js_1.renderDocument)(doc));
+                    await (0, ui_js_1.pause)();
+                    break;
+                }
+                case 'columns':
+                    columns = await this.chooseColumns(columns);
+                    break;
+                case 'export':
+                    await this.exportDocuments(query, total);
+                    break;
+                case 'sql':
+                    this.showLastSql();
+                    await (0, ui_js_1.pause)();
+                    break;
+                case 'refine':
+                    return this.guidedFind();
+                case 'done':
+                    return;
+            }
+        }
+    }
+    async chooseColumns(current) {
+        const schema = this.schema;
+        if (!schema)
+            return current;
+        (0, ui_js_1.info)(ui_js_1.style.grey(`  Current columns: ${current.join(', ')}`));
+        // No defaultValue: `text` substitutes it for a blank line, which would make
+        // "blank for all fields" mean "keep what you already have".
+        const raw = await (0, ui_js_1.text)({
+            message: 'Columns to show (comma separated, blank for all fields)',
+            allowEmpty: true,
+            hint: ui_js_1.style.grey(`  available: ${schema.fields.map((field) => field.path).join(', ')}`),
+        });
+        if (raw.trim() === '')
+            return schema.fields.map((field) => field.path);
+        const columns = raw
+            .split(',')
+            .map((column) => column.trim())
+            .filter((column) => column !== '');
+        return columns.length > 0 ? columns : current;
+    }
+    async exportDocuments(query, total) {
+        const limitRaw = await (0, ui_js_1.text)({
+            message: `How many documents? (up to ${total})`,
+            defaultValue: String(Math.min(total, 1000)),
+            validate: (input) => Number.isInteger(Number(input)) && Number(input) > 0 ? undefined : 'Enter a whole number.',
+        });
+        const limit = Number(limitRaw);
+        const file = await (0, ui_js_1.text)({
+            message: 'Save to which file?',
+            defaultValue: node_path_1.default.join(process.cwd(), `${this.collectionName}-export.json`),
+        });
+        const cursor = this.collection().find(query.filter).limit(limit);
+        if (query.sort)
+            cursor.sort(query.sort);
+        const docs = await cursor.toArray();
+        const target = node_path_1.default.resolve(file);
+        if ((0, node_fs_1.existsSync)(target)) {
+            const overwrite = await (0, ui_js_1.confirm)(`${target} already exists. Overwrite it?`, false);
+            if (!overwrite) {
+                (0, ui_js_1.info)(ui_js_1.style.grey('  Not saved.'));
+                return;
+            }
+        }
+        (0, node_fs_1.writeFileSync)(target, `${JSON.stringify(docs, null, 2)}\n`, 'utf8');
+        (0, ui_js_1.success)(`Wrote ${docs.length.toLocaleString()} document(s) to ${target}`);
+    }
+    // ------------------------------------------------------------ other actions
+    async countFlow() {
+        const conditions = await this.buildConditions();
+        if (conditions === null)
+            return;
+        const mode = conditions.length > 1
+            ? await (0, ui_js_1.select)({
+                message: 'Should documents match…',
+                choices: [
+                    { label: 'all of these conditions', value: 'all', hint: '— AND' },
+                    { label: 'any of these conditions', value: 'any', hint: '— OR' },
+                ],
+            })
+            : 'all';
+        const filter = (0, filter_builder_js_1.combineConditions)(conditions, mode);
+        const count = await this.collection().countDocuments(filter);
+        (0, ui_js_1.heading)('Count');
+        (0, ui_js_1.info)(`  ${ui_js_1.style.grey('filter')} ${JSON.stringify(filter)}`);
+        (0, ui_js_1.info)(`  ${ui_js_1.style.bold(count.toLocaleString())} document(s) match`);
+        await (0, ui_js_1.pause)();
+    }
+    async distinctFlow() {
+        const field = await this.pickField('Show the distinct values of which field?');
+        if (!field)
+            return;
+        const values = await this.collection().distinct(field);
+        (0, ui_js_1.heading)(`Values of ${field}`);
+        if (values.length === 0) {
+            (0, ui_js_1.info)(ui_js_1.style.grey('  No values found.'));
+        }
+        else {
+            const shown = values.slice(0, 200);
+            shown.forEach((value) => (0, ui_js_1.info)(`  ${(0, format_js_1.formatCell)(value)}`));
+            (0, ui_js_1.info)(ui_js_1.style.grey(`  ${values.length.toLocaleString()} distinct value(s)${values.length > shown.length ? `, showing the first ${shown.length}` : ''}`));
+        }
+        await (0, ui_js_1.pause)();
+    }
+    async groupFlow() {
+        const field = await this.pickField('Count documents by which field?');
+        if (!field)
+            return;
+        const results = (await this.collection()
+            .aggregate([{ $group: { _id: `$${field}`, count: { $sum: 1 } } }, { $sort: { count: -1 } }])
+            .toArray());
+        (0, ui_js_1.heading)(`Documents per ${field}`);
+        if (results.length === 0) {
+            (0, ui_js_1.info)(ui_js_1.style.grey('  Nothing to count.'));
+        }
+        else {
+            // `$group` names the grouping key `_id`; label it with the real field so
+            // the table reads the way the question was asked.
+            const rows = results.map((row) => ({ [field]: row._id, count: row.count }));
+            (0, ui_js_1.info)((0, format_js_1.renderTable)(rows, {
+                columns: [field, 'count'],
+                showRowNumbers: false,
+            }));
+            (0, ui_js_1.info)(ui_js_1.style.grey(`  ${results.length.toLocaleString()} group(s)`));
+        }
+        await (0, ui_js_1.pause)();
+    }
+    async pickField(message_) {
+        const schema = this.schema;
+        if (!schema || schema.fields.length === 0) {
+            (0, ui_js_1.warn)('No fields were found in this collection.');
+            await (0, ui_js_1.pause)();
+            return null;
+        }
+        try {
+            const picked = await (0, ui_js_1.select)({
+                message: message_,
+                choices: [
+                    ...schema.fields.map((field) => ({
+                        label: field.path,
+                        value: field.path,
+                        hint: (0, schema_js_1.describeField)(field),
+                    })),
+                    { label: 'Type a field name myself…', value: '__custom__' },
+                ],
+                pageSize: 14,
+            });
+            if (picked !== '__custom__')
+                return picked;
+            return await (0, ui_js_1.text)({ message: 'Field name' });
+        }
+        catch (err) {
+            if (err instanceof ui_js_1.PromptCancelledError)
+                return null;
+            throw err;
+        }
+    }
+    async showSchema() {
+        const schema = this.schema;
+        (0, ui_js_1.heading)(`Fields in ${this.collectionName}`);
+        if (!schema) {
+            (0, ui_js_1.info)(ui_js_1.style.grey('  Nothing sampled yet.'));
+        }
+        else {
+            (0, ui_js_1.info)((0, format_js_1.renderSchema)(schema));
+            (0, ui_js_1.info)(ui_js_1.style.grey(`\n  Inferred from ${schema.sampled.toLocaleString()} sampled document(s) — fields that only appear in rarer documents may be missing.`));
+        }
+        await (0, ui_js_1.pause)();
+    }
+    async showIndexes() {
+        (0, ui_js_1.heading)(`Indexes on ${this.collectionName}`);
+        try {
+            const indexes = await this.collection().listIndexes().toArray();
+            if (indexes.length === 0) {
+                (0, ui_js_1.info)(ui_js_1.style.grey('  No indexes beyond the _id primary key.'));
+            }
+            else {
+                for (const index of indexes) {
+                    (0, ui_js_1.info)(`  ${ui_js_1.style.bold(index.name)} ${ui_js_1.style.grey(JSON.stringify(index.key))}`);
+                }
+            }
+        }
+        catch (err) {
+            (0, ui_js_1.error)(message(err));
+        }
+        await (0, ui_js_1.pause)();
+    }
+    // ------------------------------------------------------------------ escape
+    // hatches for people who do know MongoDB / SQL
+    async jsonFilterFlow() {
+        (0, ui_js_1.info)(ui_js_1.style.grey('  Enter a MongoDB-style filter as JSON, e.g. {"age": {"$gt": 25}, "isActive": true}'));
+        const raw = await (0, ui_js_1.text)({
+            message: 'Filter',
+            defaultValue: '{}',
+            validate: (input) => {
+                try {
+                    const parsed = JSON.parse(input);
+                    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                        return 'A filter must be a JSON object.';
+                    }
+                    return undefined;
+                }
+                catch (err) {
+                    return `That is not valid JSON: ${message(err)}`;
+                }
+            },
+        });
+        const filter = JSON.parse(raw);
+        const sort = await this.chooseSort();
+        await this.runQuery({ filter, sort, description: `filter ${raw}` });
+    }
+    async runRawSql() {
+        const client = this.requireClient();
+        (0, ui_js_1.info)(ui_js_1.style.grey(`  Documents live in a "data" JSON column, e.g. SELECT _id, json_extract(data, '$.name') FROM "${this.collectionName ?? 'collection'}"`));
+        const sql = await (0, ui_js_1.multilineText)('SQL to run');
+        if (sql.trim() === '')
+            return;
+        try {
+            const rows = await client.database.all(sql);
+            (0, ui_js_1.heading)('Rows');
+            if (rows.length === 0) {
+                (0, ui_js_1.info)(ui_js_1.style.grey('  No rows returned.'));
+            }
+            else {
+                const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+                (0, ui_js_1.info)((0, format_js_1.renderTable)(rows, { columns }));
+                (0, ui_js_1.info)(ui_js_1.style.grey(`  ${rows.length.toLocaleString()} row(s)`));
+            }
+            this.lastSql = { sql, params: [] };
+        }
+        catch (err) {
+            (0, ui_js_1.error)(`SQL error: ${message(err)}`);
+        }
+        await (0, ui_js_1.pause)();
+    }
+    showLastSql() {
+        (0, ui_js_1.heading)('Last query');
+        if (!this.lastSql) {
+            (0, ui_js_1.info)(ui_js_1.style.grey('  Nothing has run yet.'));
+            return;
+        }
+        if (this.lastQuery) {
+            (0, ui_js_1.info)(`${ui_js_1.style.bold('Filter')}\n${JSON.stringify(this.lastQuery.filter, null, 2)}`);
+        }
+        (0, ui_js_1.info)((0, format_js_1.renderSql)(this.lastSql.sql, this.lastSql.params));
+    }
+    // ------------------------------------------------------------------ helpers
+    requireClient() {
+        if (!this.client)
+            throw new Error('No database is open.');
+        return this.client;
+    }
+    collection() {
+        if (!this.collectionName)
+            throw new Error('No collection is selected.');
+        return this.requireClient().collection(this.collectionName);
+    }
+}
+exports.Explorer = Explorer;
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}