@tolinax/ayoune-cli 2026.4.0 → 2026.6.0

package/lib/api/apiClient.js

@@ -28,6 +28,7 @@ const MODULE_HOST_OVERRIDES = {
     general: "https://api-v1.ayoune.app/api/general",
     usersettings: "https://api-v1.ayoune.app/api/usersettings",
     auth: "https://auth.ayoune.app",
+    aggregation: "https://aggregation.ayoune.app",
 };
 export function getModuleBaseUrl(module) {
     return MODULE_HOST_OVERRIDES[module] || `https://${module}-api.ayoune.app`;

package/lib/commands/createAggregateCommand.js

@@ -0,0 +1,656 @@
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { apiCallHandler } from "../api/apiCallHandler.js";
+import { handleResponseFormatOptions } from "../helpers/handleResponseFormatOptions.js";
+import { spinner } from "../../index.js";
+import { EXIT_GENERAL_ERROR, EXIT_MISUSE } from "../exitCodes.js";
+import { cliError } from "../helpers/cliError.js";
+import { readPipelineInput } from "../helpers/readPipelineInput.js";
+function wrapAggResult(res) {
+    if (Array.isArray(res)) {
+        return { payload: res, meta: { resultCount: res.length } };
+    }
+    if ((res === null || res === void 0 ? void 0 : res.payload) !== undefined)
+        return res;
+    return { payload: res, meta: {} };
+}
+export function createAggregateCommand(program) {
+    const agg = program
+        .command("aggregate")
+        .alias("agg")
+        .description("Run MongoDB aggregation pipelines, manage saved queries, and explore models")
+        .addHelpText("after", `
+Examples:
+  ay agg run consumers --pipeline '[{"$count":"total"}]'
+  ay agg wizard
+  ay agg exec monthly-revenue -r table
+  ay agg list
+  ay agg save --name "Active Users" --model consumers --pipeline '[{"$match":{"status":"active"}}]'
+  ay agg validate --pipeline '[{"$group":{"_id":"$type","count":{"$sum":1}}}]'
+  ay agg models consumers`);
+    // ─── ay agg run <model> ─────────────────────────────────────────
+    agg
+        .command("run <model>")
+        .description("Execute an aggregation pipeline on a model")
+        .option("--pipeline <json>", "Pipeline as JSON array string")
+        .option("--file <path>", "Read pipeline from a JSON file")
+        .option("--global", "Skip tenant filter (superuser only)")
+        .option("--replace", "Enable template variable replacement")
+        .option("--resultAsObject", "Return result as single object")
+        .option("--random", "Return one random result")
+        .addHelpText("after", `
+Examples:
+  ay agg run consumers --pipeline '[{"$match":{"status":"active"}},{"$count":"total"}]'
+  ay agg run orders --file pipeline.json -r table
+  cat pipeline.json | ay agg run products`)
+        .action(async (model, options) => {
+        var _a, _b;
+        try {
+            const opts = { ...program.opts(), ...options };
+            const pipeline = await readPipelineInput(opts);
+            spinner.start({ text: `Executing pipeline on ${model}...`, color: "magenta" });
+            const params = {};
+            if (opts.global)
+                params.global = true;
+            if (opts.replace)
+                params.replace = true;
+            if (opts.resultAsObject)
+                params.resultAsObject = true;
+            if (opts.random)
+                params.random = true;
+            const res = await apiCallHandler("aggregation", model, "post", pipeline, params);
+            const wrapped = wrapAggResult(res);
+            handleResponseFormatOptions(opts, wrapped);
+            spinner.success({ text: `Pipeline returned ${(_b = (_a = wrapped.meta) === null || _a === void 0 ? void 0 : _a.resultCount) !== null && _b !== void 0 ? _b : "?"} results` });
+        }
+        catch (e) {
+            cliError(e.message || "Pipeline execution failed", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay agg exec <slugOrId> ─────────────────────────────────────
+    agg
+        .command("exec <slugOrId>")
+        .description("Execute a saved query by slug name or ObjectId")
+        .addHelpText("after", `
+Examples:
+  ay agg exec monthly-revenue -r table
+  ay agg exec 507f1f77bcf86cd799439011 -r json --quiet`)
+        .action(async (slugOrId, options) => {
+        var _a, _b, _c, _d;
+        try {
+            const opts = { ...program.opts(), ...options };
+            const isObjectId = /^[a-f0-9]{24}$/i.test(slugOrId);
+            spinner.start({ text: `Executing query "${slugOrId}"...`, color: "magenta" });
+            let queryId = slugOrId;
+            if (!isObjectId) {
+                // Resolve slug to ID via config-api
+                const lookup = await apiCallHandler("config", "queries", "get", null, {
+                    slug: slugOrId,
+                    limit: 1,
+                    responseFormat: "json",
+                });
+                const entries = lookup === null || lookup === void 0 ? void 0 : lookup.payload;
+                if (!entries || (Array.isArray(entries) && entries.length === 0)) {
+                    cliError(`No query found with slug "${slugOrId}"`, EXIT_GENERAL_ERROR);
+                }
+                queryId = Array.isArray(entries) ? entries[0]._id : entries._id;
+            }
+            const res = await apiCallHandler("aggregation", `queries/execute/${queryId}`, "post");
+            const wrapped = wrapAggResult(res);
+            handleResponseFormatOptions(opts, wrapped);
+            const count = (_d = (_b = (_a = wrapped.meta) === null || _a === void 0 ? void 0 : _a.resultCount) !== null && _b !== void 0 ? _b : (_c = wrapped.payload) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : "?";
+            spinner.success({ text: `Query returned ${count} results` });
+        }
+        catch (e) {
+            cliError(e.message || "Query execution failed", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay agg list ────────────────────────────────────────────────
+    agg
+        .command("list")
+        .alias("ls")
+        .description("List saved aggregation queries")
+        .option("-l, --limit <number>", "Limit results", parseInt, 50)
+        .option("-p, --page <number>", "Page number", parseInt, 1)
+        .option("--search <term>", "Search by name")
+        .action(async (options) => {
+        var _a, _b, _c, _d, _e;
+        try {
+            const opts = { ...program.opts(), ...options };
+            spinner.start({ text: "Fetching queries...", color: "magenta" });
+            const params = {
+                page: opts.page,
+                limit: opts.limit,
+                responseFormat: opts.responseFormat,
+                verbosity: opts.verbosity,
+                "dataSource.source": "aggregation",
+            };
+            if (opts.search)
+                params.q = opts.search;
+            const res = await apiCallHandler("config", "queries", "get", null, params);
+            handleResponseFormatOptions(opts, res);
+            const total = (_e = (_c = (_b = (_a = res.meta) === null || _a === void 0 ? void 0 : _a.pageInfo) === null || _b === void 0 ? void 0 : _b.totalEntries) !== null && _c !== void 0 ? _c : (_d = res.payload) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0;
+            spinner.success({ text: `Found ${total} queries` });
+        }
+        catch (e) {
+            cliError(e.message || "Failed to list queries", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay agg save ────────────────────────────────────────────────
+    agg
+        .command("save")
+        .description("Save a pipeline as a reusable query")
+        .requiredOption("--name <name>", "Query name")
+        .requiredOption("--model <model>", "Aggregation model name")
+        .option("--pipeline <json>", "Pipeline as JSON array string")
+        .option("--file <path>", "Read pipeline from a JSON file")
+        .addHelpText("after", `
+Examples:
+  ay agg save --name "Monthly Revenue" --model orders --pipeline '[{"$group":{"_id":null,"total":{"$sum":"$amount"}}}]'
+  ay agg save --name "Active Users" --model consumers --file pipeline.json`)
+        .action(async (options) => {
+        var _a, _b;
+        try {
+            const opts = { ...program.opts(), ...options };
+            const pipeline = await readPipelineInput(opts);
+            spinner.start({ text: "Saving query...", color: "magenta" });
+            const body = {
+                name: opts.name,
+                dataSource: {
+                    source: "aggregation",
+                    aggregationModel: opts.model,
+                    aggregationPipeline: JSON.stringify(pipeline),
+                },
+                cache: { enabled: false },
+            };
+            const res = await apiCallHandler("config", "queries", "post", body, {
+                responseFormat: opts.responseFormat,
+            });
+            handleResponseFormatOptions(opts, res);
+            const slug = ((_a = res.payload) === null || _a === void 0 ? void 0 : _a.slug) || ((_b = res.payload) === null || _b === void 0 ? void 0 : _b.name) || opts.name;
+            spinner.success({ text: `Query saved — run with: ay agg exec ${slug}` });
+        }
+        catch (e) {
+            cliError(e.message || "Failed to save query", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay agg validate ───────────────────────────────────────────
+    agg
+        .command("validate")
+        .alias("check")
+        .description("Validate a pipeline without executing")
+        .option("--pipeline <json>", "Pipeline as JSON array string")
+        .option("--file <path>", "Read pipeline from a JSON file")
+        .action(async (options) => {
+        var _a, _b, _c;
+        try {
+            const opts = { ...program.opts(), ...options };
+            const pipeline = await readPipelineInput(opts);
+            spinner.start({ text: "Validating pipeline...", color: "magenta" });
+            const res = await apiCallHandler("aggregation", "models/validate", "post", { pipeline });
+            spinner.stop();
+            const v = res.payload || res;
+            const icon = v.valid ? chalk.green("✓") : chalk.red("✗");
+            console.log(`\n  ${icon} Pipeline is ${v.valid ? "valid" : "invalid"} (${(_a = v.stageCount) !== null && _a !== void 0 ? _a : pipeline.length} stages)`);
+            if ((_b = v.errors) === null || _b === void 0 ? void 0 : _b.length) {
+                for (const err of v.errors)
+                    console.log(chalk.red(`    - ${err}`));
+            }
+            if ((_c = v.warnings) === null || _c === void 0 ? void 0 : _c.length) {
+                for (const w of v.warnings)
+                    console.log(chalk.yellow(`    ! ${w}`));
+            }
+            console.log();
+            if (!v.valid)
+                process.exit(EXIT_GENERAL_ERROR);
+        }
+        catch (e) {
+            cliError(e.message || "Validation failed", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay agg models [model] ─────────────────────────────────────
+    agg
+        .command("models [model]")
+        .description("List available models, or show fields for a specific model")
+        .addHelpText("after", `
+Examples:
+  ay agg models                  List all available models
+  ay agg models consumers        Show fields for Consumers`)
+        .action(async (model, options) => {
+        var _a, _b, _c, _d, _e;
+        try {
+            const opts = { ...program.opts(), ...options };
+            if (model) {
+                spinner.start({ text: `Loading fields for ${model}...`, color: "magenta" });
+                const res = await apiCallHandler("aggregation", `models/${model}/fields`, "get");
+                handleResponseFormatOptions(opts, res);
+                const fieldCount = (_c = (_b = (_a = res.payload) === null || _a === void 0 ? void 0 : _a.fields) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0;
+                spinner.success({ text: `${model}: ${fieldCount} fields` });
+            }
+            else {
+                spinner.start({ text: "Loading models...", color: "magenta" });
+                const res = await apiCallHandler("aggregation", "models", "get");
+                handleResponseFormatOptions(opts, res);
+                const count = (_e = (_d = res.payload) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0;
+                spinner.success({ text: `${count} models available` });
+            }
+        }
+        catch (e) {
+            cliError(e.message || "Failed to load models", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay agg wizard ─────────────────────────────────────────────
+    agg
+        .command("wizard")
+        .alias("wiz")
+        .description("Interactive pipeline builder wizard")
+        .action(async (options) => {
+        var _a, _b, _c, _d, _e;
+        try {
+            const opts = { ...program.opts(), ...options };
+            if (!process.stdin.isTTY) {
+                cliError("Wizard requires an interactive terminal (TTY)", EXIT_MISUSE);
+            }
+            // Step 1: Select model
+            spinner.start({ text: "Loading models...", color: "magenta" });
+            const modelsRes = await apiCallHandler("aggregation", "models", "get");
+            spinner.stop();
+            const modelChoices = (modelsRes.payload || []).map((m) => ({
+                name: `${m.name} ${chalk.dim(`(${m.module})`)}`,
+                value: m.name,
+            }));
+            const { selectedModel } = await inquirer.prompt([
+                {
+                    type: "search-list",
+                    name: "selectedModel",
+                    message: "Select a model:",
+                    choices: modelChoices,
+                },
+            ]);
+            // Step 2: Fetch and display fields
+            spinner.start({ text: `Loading fields for ${selectedModel}...`, color: "magenta" });
+            const fieldsRes = await apiCallHandler("aggregation", `models/${selectedModel}/fields`, "get");
+            spinner.stop();
+            const fields = ((_a = fieldsRes.payload) === null || _a === void 0 ? void 0 : _a.fields) || [];
+            const fieldNames = fields.map((f) => f.field);
+            console.log(chalk.cyan(`\n  Fields for ${selectedModel}:\n`));
+            for (const f of fields) {
+                const ref = f.ref ? chalk.dim(` -> ${f.ref}`) : "";
+                const req = f.required ? chalk.yellow(" *") : "";
+                console.log(`    ${chalk.white(f.field)} ${chalk.dim(`(${f.type})`)}${ref}${req}`);
+            }
+            console.log();
+            // Step 3: Build stages iteratively
+            const pipeline = [];
+            let addMore = true;
+            while (addMore) {
+                const { stageType } = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "stageType",
+                        message: `Add stage ${pipeline.length + 1}:`,
+                        choices: [
+                            { name: "$match — Filter documents", value: "$match" },
+                            { name: "$group — Group and aggregate", value: "$group" },
+                            { name: "$sort — Sort results", value: "$sort" },
+                            { name: "$project — Include/exclude fields", value: "$project" },
+                            { name: "$unwind — Deconstruct array field", value: "$unwind" },
+                            { name: "$lookup — Join with another collection", value: "$lookup" },
+                            { name: "$limit — Limit results", value: "$limit" },
+                            { name: "$skip — Skip results", value: "$skip" },
+                            { name: "$count — Count documents", value: "$count" },
+                            { name: "$addFields — Add computed fields", value: "$addFields" },
+                            new inquirer.Separator(),
+                            { name: "Raw JSON stage", value: "$raw" },
+                            new inquirer.Separator(),
+                            { name: chalk.green("Done — preview and execute"), value: "$done" },
+                        ],
+                    },
+                ]);
+                if (stageType === "$done") {
+                    addMore = false;
+                    break;
+                }
+                const stage = await buildStage(stageType, fieldNames, fields);
+                if (stage) {
+                    pipeline.push(stage);
+                    console.log(chalk.dim(`  Added: ${JSON.stringify(stage)}\n`));
+                }
+            }
+            if (pipeline.length === 0) {
+                cliError("Pipeline is empty — add at least one stage", EXIT_MISUSE);
+            }
+            // Step 4: Preview
+            console.log(chalk.cyan("\n  Pipeline:\n"));
+            console.log(chalk.dim("  " + JSON.stringify(pipeline, null, 2).split("\n").join("\n  ")));
+            console.log();
+            spinner.start({ text: "Running preview (first 5 results)...", color: "magenta" });
+            const previewPipeline = [...pipeline, { $limit: 5 }];
+            const previewRes = await apiCallHandler("aggregation", selectedModel, "post", previewPipeline);
+            spinner.stop();
+            const previewWrapped = wrapAggResult(previewRes);
+            handleResponseFormatOptions({ ...opts, responseFormat: "yaml" }, previewWrapped);
+            // Step 5: Action choice
+            const { action } = await inquirer.prompt([
+                {
+                    type: "list",
+                    name: "action",
+                    message: "What would you like to do?",
+                    choices: [
+                        { name: "Execute full pipeline", value: "execute" },
+                        { name: "Save as reusable query", value: "save" },
+                        { name: "Execute and save", value: "both" },
+                        { name: "Print pipeline JSON", value: "print" },
+                        { name: "Cancel", value: "cancel" },
+                    ],
+                },
+            ]);
+            if (action === "execute" || action === "both") {
+                spinner.start({ text: "Executing full pipeline...", color: "magenta" });
+                const res = await apiCallHandler("aggregation", selectedModel, "post", pipeline);
+                const wrapped = wrapAggResult(res);
+                handleResponseFormatOptions(opts, wrapped);
+                spinner.success({ text: `Pipeline returned ${(_c = (_b = wrapped.meta) === null || _b === void 0 ? void 0 : _b.resultCount) !== null && _c !== void 0 ? _c : "?"} results` });
+            }
+            if (action === "save" || action === "both") {
+                const { queryName } = await inquirer.prompt([
+                    {
+                        type: "input",
+                        name: "queryName",
+                        message: "Query name:",
+                        validate: (v) => v.length > 0 || "Name is required",
+                    },
+                ]);
+                spinner.start({ text: "Saving query...", color: "magenta" });
+                const body = {
+                    name: queryName,
+                    dataSource: {
+                        source: "aggregation",
+                        aggregationModel: selectedModel,
+                        aggregationPipeline: JSON.stringify(pipeline),
+                    },
+                    cache: { enabled: false },
+                };
+                const saveRes = await apiCallHandler("config", "queries", "post", body, {
+                    responseFormat: "json",
+                });
+                const slug = ((_d = saveRes.payload) === null || _d === void 0 ? void 0 : _d.slug) || ((_e = saveRes.payload) === null || _e === void 0 ? void 0 : _e.name) || queryName;
+                spinner.success({ text: `Query saved — run with: ay agg exec ${slug}` });
+            }
+            if (action === "print") {
+                console.log(JSON.stringify(pipeline, null, 2));
+            }
+        }
+        catch (e) {
+            cliError(e.message || "Wizard failed", EXIT_GENERAL_ERROR);
+        }
+    });
+}
+// ─── Stage Builders ────────────────────────────────────────────────
+async function buildStage(stageType, fieldNames, fields) {
+    switch (stageType) {
+        case "$match":
+            return buildMatchStage(fieldNames, fields);
+        case "$group":
+            return buildGroupStage(fieldNames);
+        case "$sort":
+            return buildSortStage(fieldNames);
+        case "$project":
+            return buildProjectStage(fieldNames);
+        case "$unwind":
+            return buildUnwindStage(fieldNames);
+        case "$lookup":
+            return buildLookupStage();
+        case "$limit":
+            return buildNumberStage("$limit", "Maximum documents to return:");
+        case "$skip":
+            return buildNumberStage("$skip", "Documents to skip:");
+        case "$count":
+            return buildCountStage();
+        case "$addFields":
+            return buildRawStage("$addFields");
+        case "$raw":
+            return buildFullRawStage();
+        default:
+            return null;
+    }
+}
+async function buildMatchStage(fieldNames, fields) {
+    const match = {};
+    let addMore = true;
+    while (addMore) {
+        const { field } = await inquirer.prompt([
+            { type: "search-list", name: "field", message: "Field to match:", choices: fieldNames },
+        ]);
+        const fieldMeta = fields.find((f) => f.field === field);
+        const isNumber = (fieldMeta === null || fieldMeta === void 0 ? void 0 : fieldMeta.type) === "Number";
+        const isDate = (fieldMeta === null || fieldMeta === void 0 ? void 0 : fieldMeta.type) === "Date";
+        const isBool = (fieldMeta === null || fieldMeta === void 0 ? void 0 : fieldMeta.type) === "Boolean";
+        const { operator } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "operator",
+                message: "Operator:",
+                choices: [
+                    { name: "equals", value: "eq" },
+                    { name: "not equals", value: "$ne" },
+                    { name: "greater than", value: "$gt" },
+                    { name: "less than", value: "$lt" },
+                    { name: "greater or equal", value: "$gte" },
+                    { name: "less or equal", value: "$lte" },
+                    { name: "in (comma-separated)", value: "$in" },
+                    { name: "not in", value: "$nin" },
+                    { name: "regex", value: "$regex" },
+                    { name: "exists", value: "$exists" },
+                ],
+            },
+        ]);
+        let value;
+        if (operator === "$exists") {
+            const { exists } = await inquirer.prompt([
+                { type: "confirm", name: "exists", message: "Field should exist?", default: true },
+            ]);
+            value = exists;
+            match[field] = { $exists: value };
+        }
+        else if (isBool) {
+            const { boolVal } = await inquirer.prompt([
+                { type: "confirm", name: "boolVal", message: `${field} =`, default: true },
+            ]);
+            match[field] = operator === "eq" ? boolVal : { [operator]: boolVal };
+        }
+        else if (operator === "$in" || operator === "$nin") {
+            const { vals } = await inquirer.prompt([
+                { type: "input", name: "vals", message: "Values (comma-separated):" },
+            ]);
+            const arr = vals.split(",").map((v) => coerceValue(v.trim(), isNumber, isDate));
+            match[field] = { [operator]: arr };
+        }
+        else {
+            const { val } = await inquirer.prompt([
+                { type: "input", name: "val", message: "Value:" },
+            ]);
+            const coerced = coerceValue(val, isNumber, isDate);
+            match[field] = operator === "eq" ? coerced : { [operator]: coerced };
+        }
+        const { more } = await inquirer.prompt([
+            { type: "confirm", name: "more", message: "Add another match condition?", default: false },
+        ]);
+        addMore = more;
+    }
+    return { $match: match };
+}
+async function buildGroupStage(fieldNames) {
+    const { idType } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "idType",
+            message: "Group by:",
+            choices: [
+                { name: "Single field", value: "single" },
+                { name: "Multiple fields", value: "multi" },
+                { name: "null (aggregate all)", value: "null" },
+            ],
+        },
+    ]);
+    let _id = null;
+    if (idType === "single") {
+        const { field } = await inquirer.prompt([
+            { type: "search-list", name: "field", message: "Group by field:", choices: fieldNames },
+        ]);
+        _id = `$${field}`;
+    }
+    else if (idType === "multi") {
+        const { selected } = await inquirer.prompt([
+            { type: "checkbox", name: "selected", message: "Select fields:", choices: fieldNames },
+        ]);
+        _id = {};
+        for (const f of selected)
+            _id[f] = `$${f}`;
+    }
+    const group = { _id };
+    let addAcc = true;
+    while (addAcc) {
+        const { outputName } = await inquirer.prompt([
+            { type: "input", name: "outputName", message: "Output field name:", validate: (v) => v.length > 0 },
+        ]);
+        const { accumulator } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "accumulator",
+                message: "Accumulator:",
+                choices: ["$sum", "$avg", "$min", "$max", "$count", "$push", "$first", "$last"],
+            },
+        ]);
+        if (accumulator === "$count") {
+            group[outputName] = { $count: {} };
+        }
+        else {
+            const { srcField } = await inquirer.prompt([
+                { type: "search-list", name: "srcField", message: "Source field:", choices: ["1 (constant)", ...fieldNames] },
+            ]);
+            group[outputName] = { [accumulator]: srcField === "1 (constant)" ? 1 : `$${srcField}` };
+        }
+        const { more } = await inquirer.prompt([
+            { type: "confirm", name: "more", message: "Add another accumulator?", default: false },
+        ]);
+        addAcc = more;
+    }
+    return { $group: group };
+}
+async function buildSortStage(fieldNames) {
+    const sort = {};
+    let addMore = true;
+    while (addMore) {
+        const { field } = await inquirer.prompt([
+            { type: "search-list", name: "field", message: "Sort by field:", choices: fieldNames },
+        ]);
+        const { direction } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "direction",
+                message: "Direction:",
+                choices: [
+                    { name: "Ascending (1)", value: 1 },
+                    { name: "Descending (-1)", value: -1 },
+                ],
+            },
+        ]);
+        sort[field] = direction;
+        const { more } = await inquirer.prompt([
+            { type: "confirm", name: "more", message: "Add another sort field?", default: false },
+        ]);
+        addMore = more;
+    }
+    return { $sort: sort };
+}
+async function buildProjectStage(fieldNames) {
+    const { mode } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "mode",
+            message: "Projection mode:",
+            choices: [
+                { name: "Include selected fields (1)", value: "include" },
+                { name: "Exclude selected fields (0)", value: "exclude" },
+            ],
+        },
+    ]);
+    const { selected } = await inquirer.prompt([
+        {
+            type: "checkbox",
+            name: "selected",
+            message: `Fields to ${mode}:`,
+            choices: fieldNames,
+            validate: (v) => v.length > 0 || "Select at least one field",
+        },
+    ]);
+    const project = {};
+    for (const f of selected)
+        project[f] = mode === "include" ? 1 : 0;
+    return { $project: project };
+}
+async function buildUnwindStage(fieldNames) {
+    const { field } = await inquirer.prompt([
+        { type: "search-list", name: "field", message: "Array field to unwind:", choices: fieldNames },
+    ]);
+    return { $unwind: `$${field}` };
+}
+async function buildLookupStage() {
+    const answers = await inquirer.prompt([
+        { type: "input", name: "from", message: "Foreign collection (lowercase):" },
+        { type: "input", name: "localField", message: "Local field:" },
+        { type: "input", name: "foreignField", message: "Foreign field:", default: "_id" },
+        { type: "input", name: "as", message: "Output array field name:" },
+    ]);
+    return { $lookup: answers };
+}
+async function buildNumberStage(op, message) {
+    const { num } = await inquirer.prompt([
+        { type: "input", name: "num", message, validate: (v) => !isNaN(parseInt(v)) || "Must be a number" },
+    ]);
+    return { [op]: parseInt(num) };
+}
+async function buildCountStage() {
+    const { field } = await inquirer.prompt([
+        { type: "input", name: "field", message: "Count output field name:", default: "count" },
+    ]);
+    return { $count: field };
+}
+async function buildRawStage(op) {
+    const { json } = await inquirer.prompt([
+        { type: "input", name: "json", message: `${op} body (JSON):` },
+    ]);
+    try {
+        return { [op]: JSON.parse(json) };
+    }
+    catch (_a) {
+        console.log(chalk.red("  Invalid JSON — stage skipped"));
+        return null;
+    }
+}
+async function buildFullRawStage() {
+    const { json } = await inquirer.prompt([
+        { type: "input", name: "json", message: "Full stage (JSON object):" },
+    ]);
+    try {
+        return JSON.parse(json);
+    }
+    catch (_a) {
+        console.log(chalk.red("  Invalid JSON — stage skipped"));
+        return null;
+    }
+}
+function coerceValue(val, isNumber, isDate) {
+    if (val === "true")
+        return true;
+    if (val === "false")
+        return false;
+    if (val === "null")
+        return null;
+    if (isNumber && !isNaN(Number(val)))
+        return Number(val);
+    if (isDate && !isNaN(Date.parse(val)))
+        return { $date: val };
+    return val;
+}