@tolinax/ayoune-cli 2026.5.0 → 2026.6.1

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;
+}

package/lib/commands/createDbCommand.js

@@ -0,0 +1,307 @@
+import chalk from "chalk";
+import { spinner } from "../../index.js";
+import { EXIT_GENERAL_ERROR, EXIT_MISUSE } from "../exitCodes.js";
+import { cliError } from "../helpers/cliError.js";
+import { handleResponseFormatOptions } from "../helpers/handleResponseFormatOptions.js";
+import { executeCopy, getDbStats } from "../db/copyEngine.js";
+import { addCopyConfig, loadCopyConfigs, removeCopyConfig, getDecryptedConfig, updateCopyConfigLastRun, maskUri, } from "../db/copyConfigStore.js";
+import { isCronDue, getNextRun, validateCron } from "../db/cronMatcher.js";
+function generateId() {
+    return Math.random().toString(36).substring(2, 10) + Date.now().toString(36);
+}
+function getSourceUri(opts) {
+    const uri = opts.from || process.env.MONGO_CONNECTSTRING || process.env.MONGODB_URI;
+    if (!uri) {
+        cliError("No source database configured. Set MONGO_CONNECTSTRING env var or use --from <uri>", EXIT_MISUSE);
+    }
+    if (!uri.startsWith("mongodb")) {
+        cliError("Source URI must be a MongoDB URI (mongodb:// or mongodb+srv://)", EXIT_MISUSE);
+    }
+    return uri;
+}
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
+}
+export function createDbCommand(program) {
+    const db = program
+        .command("db")
+        .description("MongoDB database operations (copy, stats, scheduled replication)")
+        .addHelpText("after", `
+Source is automatically resolved from MONGO_CONNECTSTRING env var.
+
+Examples:
+  ay db copy --to "mongodb://backup-host/ayoune" --collections "users,orders"
+  ay db copy --to "mongodb://..." --all --schedule "0 */6 * * *"
+  ay db copy --from "mongodb://other/db" --to "mongodb://..." --collections "logs"
+  ay db schedules list
+  ay db stats`);
+    // ─── ay db copy ─────────────────────────────────────────────────
+    db.command("copy")
+        .description("Copy data from aYOUne database to another MongoDB instance")
+        .requiredOption("--to <uri>", "Target MongoDB connection URI")
+        .option("--from <uri>", "Source URI override (default: MONGO_CONNECTSTRING env var)")
+        .option("--collections <list>", "Comma-separated collection names")
+        .option("--all", "Copy all collections")
+        .option("--query <json>", "JSON filter query for source documents")
+        .option("--drop", "Drop target collection before copying")
+        .option("--upsert", "Upsert documents by _id (idempotent, safe to re-run)")
+        .option("--batch-size <number>", "Documents per batch", parseInt, 1000)
+        .option("--schedule <cron>", "Save as scheduled copy (cron expression) instead of executing")
+        .addHelpText("after", `
+Source defaults to MONGO_CONNECTSTRING env var (the aYOUne database).
+
+Examples:
+  ay db copy --to "mongodb://backup-host/ayoune" --collections "users,orders"
+  ay db copy --to "mongodb://..." --all --drop
+  ay db copy --to "mongodb://..." --collections "logs" --query '{"status":"active"}'
+  ay db copy --to "mongodb://..." --all --upsert --schedule "0 */6 * * *"
+  ay db copy --from "mongodb://other/db" --to "mongodb://..." --collections "data"`)
+        .action(async (options) => {
+        try {
+            const opts = { ...program.opts(), ...options };
+            // Validate input
+            if (!opts.collections && !opts.all) {
+                cliError("Provide --collections or --all", EXIT_MISUSE);
+            }
+            if (opts.collections && opts.all) {
+                cliError("Use either --collections or --all, not both", EXIT_MISUSE);
+            }
+            const fromUri = getSourceUri(opts);
+            if (!opts.to.startsWith("mongodb")) {
+                cliError("--to must be a MongoDB URI (mongodb:// or mongodb+srv://)", EXIT_MISUSE);
+            }
+            let query;
+            if (opts.query) {
+                try {
+                    query = JSON.parse(opts.query);
+                }
+                catch (_a) {
+                    cliError("--query must be valid JSON", EXIT_MISUSE);
+                }
+            }
+            const collections = opts.all ? ["*"] : opts.collections.split(",").map((c) => c.trim());
+            // Schedule mode
+            if (opts.schedule) {
+                const cronError = validateCron(opts.schedule);
+                if (cronError)
+                    cliError(`Invalid cron expression: ${cronError}`, EXIT_MISUSE);
+                const config = {
+                    id: generateId(),
+                    createdAt: new Date().toISOString(),
+                    from: maskUri(fromUri),
+                    to: maskUri(opts.to),
+                    fromUri: fromUri, // Will be encrypted by addCopyConfig
+                    toUri: opts.to,
+                    collections,
+                    query,
+                    drop: opts.drop || false,
+                    upsert: opts.upsert || false,
+                    batchSize: opts.batchSize,
+                    schedule: opts.schedule,
+                };
+                addCopyConfig(config);
+                const nextRun = getNextRun(opts.schedule);
+                console.log(chalk.green(`\n  Scheduled copy saved (ID: ${config.id})`));
+                console.log(chalk.dim(`  Source: ${config.from}`));
+                console.log(chalk.dim(`  Target: ${config.to}`));
+                console.log(chalk.dim(`  Collections: ${collections.join(", ")}`));
+                console.log(chalk.dim(`  Schedule: ${opts.schedule}`));
+                if (nextRun)
+                    console.log(chalk.dim(`  Next run: ${nextRun.toISOString()}`));
+                console.log();
+                console.log(chalk.yellow("  Set up a cron job to run scheduled copies:"));
+                console.log(chalk.dim("    Linux/macOS: crontab -e → */5 * * * * ay db schedules run"));
+                console.log(chalk.dim("    Windows: schtasks /create /tn ayoune-db-sync /tr \"ay db schedules run\" /sc minute /mo 5"));
+                console.log();
+                return;
+            }
+            // Execute copy
+            spinner.start({ text: `Copying from ${maskUri(fromUri)} to ${maskUri(opts.to)}...`, color: "cyan" });
+            const summary = await executeCopy(fromUri, opts.to, collections, {
+                query,
+                drop: opts.drop,
+                upsert: opts.upsert,
+                batchSize: opts.batchSize,
+            }, (progress) => {
+                spinner.update({
+                    text: `${progress.collection}: ${progress.copied}/${progress.total} docs${progress.errors ? chalk.red(` (${progress.errors} errors)`) : ""}`,
+                });
+            });
+            spinner.stop();
+            // Display summary
+            const wrapped = {
+                payload: summary,
+                meta: {
+                    totalCopied: summary.totalCopied,
+                    totalErrors: summary.totalErrors,
+                    duration: summary.duration,
+                },
+            };
+            if (opts.responseFormat === "json" || opts.responseFormat === "yaml") {
+                handleResponseFormatOptions(opts, wrapped);
+            }
+            else {
+                console.log(chalk.cyan.bold("\n  Copy Summary\n"));
+                for (const col of summary.collections) {
+                    const icon = col.errors === 0 ? chalk.green("●") : chalk.yellow("●");
+                    console.log(`  ${icon} ${col.name}: ${col.copied} docs copied${col.errors ? chalk.red(` (${col.errors} errors)`) : ""} ${chalk.dim(`(${col.duration}ms)`)}`);
+                }
+                console.log();
+                console.log(`  ${chalk.green(summary.totalCopied + " total")}${summary.totalErrors ? `  ${chalk.red(summary.totalErrors + " errors")}` : ""} ${chalk.dim(`in ${summary.duration}ms`)}`);
+                console.log();
+            }
+            if (summary.totalErrors > 0)
+                process.exit(EXIT_GENERAL_ERROR);
+        }
+        catch (e) {
+            cliError(e.message || "Copy failed", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay db schedules ────────────────────────────────────────────
+    const schedules = db.command("schedules").alias("sched").description("Manage scheduled copy jobs");
+    // ay db schedules list
+    schedules
+        .command("list")
+        .alias("ls")
+        .description("List all scheduled copy jobs")
+        .action(async (options) => {
+        try {
+            const opts = { ...program.opts(), ...options };
+            const configs = loadCopyConfigs();
+            if (configs.length === 0) {
+                console.log(chalk.dim("\n  No scheduled copies configured.\n"));
+                return;
+            }
+            const wrapped = { payload: configs.map(displayConfig), meta: { total: configs.length } };
+            handleResponseFormatOptions(opts, wrapped);
+        }
+        catch (e) {
+            cliError(e.message || "Failed to list schedules", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ay db schedules remove <id>
+    schedules
+        .command("remove <id>")
+        .alias("rm")
+        .description("Remove a scheduled copy job")
+        .action(async (id) => {
+        const removed = removeCopyConfig(id);
+        if (removed) {
+            spinner.success({ text: `Schedule ${id} removed` });
+        }
+        else {
+            cliError(`No schedule found with ID "${id}"`, EXIT_GENERAL_ERROR);
+        }
+    });
+    // ay db schedules run
+    schedules
+        .command("run")
+        .description("Execute all copy jobs that are due now")
+        .option("--id <id>", "Run a specific schedule by ID")
+        .action(async (options) => {
+        try {
+            const configs = loadCopyConfigs();
+            const now = new Date();
+            const toRun = options.id
+                ? configs.filter((c) => c.id === options.id)
+                : configs.filter((c) => isCronDue(c.schedule, c.lastRun, now));
+            if (toRun.length === 0) {
+                console.log(chalk.dim("\n  No copies due.\n"));
+                return;
+            }
+            console.log(chalk.cyan(`\n  Running ${toRun.length} scheduled copies...\n`));
+            for (const config of toRun) {
+                const { fromUri, toUri } = getDecryptedConfig(config);
+                console.log(chalk.dim(`  ${config.id}: ${config.from} → ${config.to}`));
+                try {
+                    spinner.start({ text: `${config.id}: copying...`, color: "cyan" });
+                    const summary = await executeCopy(fromUri, toUri, config.collections, {
+                        query: config.query,
+                        drop: config.drop,
+                        upsert: config.upsert,
+                        batchSize: config.batchSize,
+                    }, (progress) => {
+                        spinner.update({
+                            text: `${config.id}: ${progress.collection} ${progress.copied}/${progress.total}`,
+                        });
+                    });
+                    updateCopyConfigLastRun(config.id, "success");
+                    spinner.success({ text: `${config.id}: ${summary.totalCopied} docs copied${summary.totalErrors ? `, ${summary.totalErrors} errors` : ""}` });
+                }
+                catch (e) {
+                    updateCopyConfigLastRun(config.id, "failed", e.message);
+                    spinner.error({ text: `${config.id}: ${e.message}` });
+                }
+            }
+            console.log();
+        }
+        catch (e) {
+            cliError(e.message || "Scheduled run failed", EXIT_GENERAL_ERROR);
+        }
+    });
+    // ─── ay db stats [uri] ──────────────────────────────────────────
+    db.command("stats [uri]")
+        .description("Show database statistics (defaults to aYOUne database)")
+        .addHelpText("after", `
+Defaults to MONGO_CONNECTSTRING (the aYOUne database) when no URI is given.
+
+Examples:
+  ay db stats                            Stats for aYOUne database
+  ay db stats "mongodb://other/db"       Stats for a different database
+  ay db stats -r table`)
+        .action(async (uri, options) => {
+        try {
+            const opts = { ...program.opts(), ...options };
+            const dbUri = uri || process.env.MONGO_CONNECTSTRING || process.env.MONGODB_URI;
+            if (!dbUri) {
+                cliError("No database URI. Set MONGO_CONNECTSTRING env var or pass a URI argument.", EXIT_MISUSE);
+            }
+            if (!dbUri.startsWith("mongodb")) {
+                cliError("URI must start with mongodb:// or mongodb+srv://", EXIT_MISUSE);
+            }
+            spinner.start({ text: `Connecting to ${maskUri(dbUri)}...`, color: "cyan" });
+            const stats = await getDbStats(dbUri);
+            spinner.stop();
+            const wrapped = {
+                payload: stats,
+                meta: {
+                    database: stats.database,
+                    collectionCount: stats.collections.length,
+                    totalSize: formatBytes(stats.totalSize),
+                },
+            };
+            if (opts.responseFormat === "json" || opts.responseFormat === "yaml") {
+                handleResponseFormatOptions(opts, wrapped);
+            }
+            else {
+                console.log(chalk.cyan.bold(`\n  Database: ${stats.database}\n`));
+                console.log(`  ${chalk.dim("Total size:")} ${formatBytes(stats.totalSize)}`);
+                console.log(`  ${chalk.dim("Collections:")} ${stats.collections.length}\n`);
+                for (const col of stats.collections) {
+                    console.log(`  ${chalk.white(col.name)}: ${col.documents.toLocaleString()} docs ${chalk.dim(`(${formatBytes(col.size)})`)}`);
+                }
+                console.log();
+            }
+        }
+        catch (e) {
+            cliError(e.message || "Failed to get stats", EXIT_GENERAL_ERROR);
+        }
+    });
+}
+function displayConfig(config) {
+    const nextRun = getNextRun(config.schedule);
+    return {
+        id: config.id,
+        from: config.from,
+        to: config.to,
+        collections: config.collections.join(", "),
+        schedule: config.schedule,
+        nextRun: (nextRun === null || nextRun === void 0 ? void 0 : nextRun.toISOString()) || "—",
+        lastRun: config.lastRun || "never",
+        lastStatus: config.lastStatus || "—",
+    };
+}

package/lib/commands/createProgram.js

@@ -47,6 +47,8 @@ import { createStatusCommand } from "./createStatusCommand.js";
 import { createSelfHostUpdateCommand } from "./createSelfHostUpdateCommand.js";
 import { createContextCommand } from "./createContextCommand.js";
 import { createAccessCommand } from "./createAccessCommand.js";
+import { createAggregateCommand } from "./createAggregateCommand.js";
+import { createDbCommand } from "./createDbCommand.js";
 import { secureStorage } from "../helpers/secureStorage.js";
 import { login } from "../api/login.js";
 import { loadConfig } from "../helpers/configLoader.js";
@@ -121,6 +123,8 @@ export function createProgram(program) {
     createPermissionsCommand(program);
     createTemplateCommand(program);
     createAccessCommand(program);
+    createAggregateCommand(program);
+    createDbCommand(program);
     createSetupCommand(program);
     createStatusCommand(program);
     createSelfHostUpdateCommand(program);
@@ -200,7 +204,7 @@ export function createProgram(program) {
         }
         // First-run onboarding: auto-login if no token stored
         const cmdName = thisCommand.name();
-        const skipAuth = ["login", "logout", "whoami", "completions", "alias", "config", "help", "setup", "status", "self-host-update", "context"];
+        const skipAuth = ["login", "logout", "whoami", "completions", "alias", "config", "help", "setup", "status", "self-host-update", "context", "db"];
         if (!skipAuth.includes(cmdName) && process.stdin.isTTY) {
             const token = secureStorage.getItem("token");
             if (!token) {

package/lib/db/copyConfigStore.js

@@ -0,0 +1,88 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+const CONFIG_PATH = path.join(os.homedir(), ".config", "ayoune", "db-copies.json");
+const ALGORITHM = "aes-256-cbc";
+function deriveKey() {
+    const seed = `ayoune-cli:${os.hostname()}:${os.userInfo().username}`;
+    return crypto.createHash("sha256").update(seed).digest();
+}
+function encrypt(text) {
+    const key = deriveKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    let encrypted = cipher.update(text, "utf8", "hex");
+    encrypted += cipher.final("hex");
+    return iv.toString("hex") + ":" + encrypted;
+}
+function decrypt(data) {
+    const key = deriveKey();
+    const [ivHex, encrypted] = data.split(":");
+    if (!ivHex || !encrypted)
+        return data;
+    try {
+        const iv = Buffer.from(ivHex, "hex");
+        const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+        let decrypted = decipher.update(encrypted, "hex", "utf8");
+        decrypted += decipher.final("utf8");
+        return decrypted;
+    }
+    catch (_a) {
+        return data;
+    }
+}
+export function maskUri(uri) {
+    return uri.replace(/:\/\/([^:]+):([^@]+)@/, "://***:***@");
+}
+export function loadCopyConfigs() {
+    if (!existsSync(CONFIG_PATH))
+        return [];
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    catch (_a) {
+        return [];
+    }
+}
+export function saveCopyConfigs(configs) {
+    const dir = path.dirname(CONFIG_PATH);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(configs, null, 2), "utf-8");
+}
+export function addCopyConfig(config) {
+    const configs = loadCopyConfigs();
+    // Encrypt URIs before saving
+    config.fromUri = encrypt(config.fromUri);
+    config.toUri = encrypt(config.toUri);
+    configs.push(config);
+    saveCopyConfigs(configs);
+}
+export function removeCopyConfig(id) {
+    const configs = loadCopyConfigs();
+    const filtered = configs.filter((c) => c.id !== id);
+    if (filtered.length === configs.length)
+        return false;
+    saveCopyConfigs(filtered);
+    return true;
+}
+export function getDecryptedConfig(config) {
+    return {
+        fromUri: decrypt(config.fromUri),
+        toUri: decrypt(config.toUri),
+    };
+}
+export function updateCopyConfigLastRun(id, status, error) {
+    const configs = loadCopyConfigs();
+    const config = configs.find((c) => c.id === id);
+    if (config) {
+        config.lastRun = new Date().toISOString();
+        config.lastStatus = status;
+        if (error)
+            config.lastError = error;
+        else
+            delete config.lastError;
+        saveCopyConfigs(configs);
+    }
+}

package/lib/db/copyEngine.js

@@ -0,0 +1,123 @@
+import { MongoClient } from "mongodb";
+export async function executeCopy(fromUri, toUri, collections, options, onProgress) {
+    const startTime = Date.now();
+    const sourceClient = new MongoClient(fromUri);
+    const targetClient = new MongoClient(toUri);
+    const results = [];
+    try {
+        await sourceClient.connect();
+        await targetClient.connect();
+        const sourceDb = sourceClient.db();
+        const targetDb = targetClient.db();
+        // Resolve collections if --all was used
+        let collectionNames = collections;
+        if (collections.length === 1 && collections[0] === "*") {
+            const colls = await sourceDb.listCollections().toArray();
+            collectionNames = colls
+                .map((c) => c.name)
+                .filter((n) => !n.startsWith("system."));
+        }
+        for (const name of collectionNames) {
+            const colStart = Date.now();
+            let copied = 0;
+            let errors = 0;
+            const sourceCol = sourceDb.collection(name);
+            const targetCol = targetDb.collection(name);
+            if (options.drop) {
+                try {
+                    await targetCol.drop();
+                }
+                catch (_a) {
+                    // Collection may not exist — ignore
+                }
+            }
+            const query = options.query || {};
+            const total = await sourceCol.countDocuments(query);
+            onProgress({ collection: name, copied: 0, total, errors: 0 });
+            const cursor = sourceCol.find(query).batchSize(options.batchSize);
+            let batch = [];
+            for await (const doc of cursor) {
+                batch.push(doc);
+                if (batch.length >= options.batchSize) {
+                    const result = await writeBatch(targetCol, batch, options.upsert || false);
+                    copied += result.written;
+                    errors += result.errors;
+                    batch = [];
+                    onProgress({ collection: name, copied, total, errors });
+                }
+            }
+            // Write remaining docs
+            if (batch.length > 0) {
+                const result = await writeBatch(targetCol, batch, options.upsert || false);
+                copied += result.written;
+                errors += result.errors;
+                onProgress({ collection: name, copied, total, errors });
+            }
+            results.push({ name, copied, errors, duration: Date.now() - colStart });
+        }
+        const totalCopied = results.reduce((s, r) => s + r.copied, 0);
+        const totalErrors = results.reduce((s, r) => s + r.errors, 0);
+        return { collections: results, totalCopied, totalErrors, duration: Date.now() - startTime };
+    }
+    finally {
+        await sourceClient.close();
+        await targetClient.close();
+    }
+}
+async function writeBatch(collection, docs, upsert) {
+    var _a, _b, _c, _d;
+    try {
+        if (upsert) {
+            const ops = docs.map((doc) => ({
+                updateOne: {
+                    filter: { _id: doc._id },
+                    update: { $set: doc },
+                    upsert: true,
+                },
+            }));
+            const result = await collection.bulkWrite(ops, { ordered: false });
+            return { written: (result.upsertedCount || 0) + (result.modifiedCount || 0), errors: 0 };
+        }
+        else {
+            const result = await collection.insertMany(docs, { ordered: false });
+            return { written: result.insertedCount, errors: 0 };
+        }
+    }
+    catch (e) {
+        // Partial success on ordered:false — count what made it through
+        const written = (_d = (_b = (_a = e.result) === null || _a === void 0 ? void 0 : _a.nInserted) !== null && _b !== void 0 ? _b : (_c = e.result) === null || _c === void 0 ? void 0 : _c.insertedCount) !== null && _d !== void 0 ? _d : 0;
+        const errorCount = docs.length - written;
+        return { written, errors: errorCount };
+    }
+}
+export async function getDbStats(uri) {
+    const client = new MongoClient(uri);
+    try {
+        await client.connect();
+        const db = client.db();
+        const stats = await db.stats();
+        const collList = await db.listCollections().toArray();
+        const collections = [];
+        for (const col of collList) {
+            if (col.name.startsWith("system."))
+                continue;
+            try {
+                const count = await db.collection(col.name).estimatedDocumentCount();
+                const colStats = await db.command({ collStats: col.name });
+                collections.push({ name: col.name, documents: count, size: colStats.size || 0 });
+            }
+            catch (_a) {
+                collections.push({ name: col.name, documents: 0, size: 0 });
+            }
+        }
+        collections.sort((a, b) => b.documents - a.documents);
+        return {
+            database: stats.db,
+            collections,
+            totalSize: stats.dataSize || 0,
+        };
+    }
+    finally {
+        await client.close();
+    }
+}

package/lib/db/cronMatcher.js

@@ -0,0 +1,42 @@
+import cronParser from "cron-parser";
+/**
+ * Determines whether a cron-scheduled job is due for execution.
+ * Returns true if the current time has passed the next scheduled run after lastRun.
+ */
+export function isCronDue(expression, lastRun, now = new Date()) {
+    try {
+        if (!lastRun)
+            return true; // Never run before → always due
+        const lastRunDate = new Date(lastRun);
+        const interval = cronParser.parseExpression(expression, { currentDate: lastRunDate });
+        const nextRun = interval.next().toDate();
+        return now >= nextRun;
+    }
+    catch (_a) {
+        return false; // Invalid cron expression
+    }
+}
+/**
+ * Returns the next scheduled run time for a cron expression.
+ */
+export function getNextRun(expression, after = new Date()) {
+    try {
+        const interval = cronParser.parseExpression(expression, { currentDate: after });
+        return interval.next().toDate();
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Validates a cron expression. Returns null if valid, error message if invalid.
+ */
+export function validateCron(expression) {
+    try {
+        cronParser.parseExpression(expression);
+        return null;
+    }
+    catch (e) {
+        return e.message || "Invalid cron expression";
+    }
+}

package/lib/db/types.js

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

package/lib/helpers/readPipelineInput.js

@@ -0,0 +1,50 @@
+import { readFileSync } from "fs";
+import { cliError } from "./cliError.js";
+import { EXIT_MISUSE } from "../exitCodes.js";
+/**
+ * Resolves a MongoDB aggregation pipeline from one of three sources:
+ * 1. --pipeline flag (JSON string)
+ * 2. --file flag (path to JSON file)
+ * 3. stdin (piped input)
+ *
+ * Returns the parsed pipeline array.
+ */
+export async function readPipelineInput(opts) {
+    let raw;
+    if (opts.pipeline) {
+        raw = opts.pipeline;
+    }
+    else if (opts.file) {
+        try {
+            raw = readFileSync(opts.file, "utf-8");
+        }
+        catch (e) {
+            cliError(`Failed to read file: ${e.message}`, EXIT_MISUSE);
+        }
+    }
+    else if (!process.stdin.isTTY) {
+        raw = await readStdin();
+    }
+    if (!raw) {
+        cliError("Provide a pipeline via --pipeline, --file, or stdin", EXIT_MISUSE);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (_a) {
+        cliError("Invalid JSON — pipeline must be a valid JSON array", EXIT_MISUSE);
+    }
+    if (!Array.isArray(parsed)) {
+        cliError("Pipeline must be a JSON array of stage objects", EXIT_MISUSE);
+    }
+    return parsed;
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolinax/ayoune-cli",
-  "version": "2026.5.0",
+  "version": "2026.6.1",
   "description": "CLI for the aYOUne Business-as-a-Service platform",
   "type": "module",
   "main": "./index.js",
@@ -119,6 +119,7 @@
     "chalk": "^5.3.0",
     "chalk-animation": "^2.0.3",
     "commander": "^12.0.0",
+    "cron-parser": "^4.9.0",
     "figlet": "^1.7.0",
     "gradient-string": "^2.0.2",
     "inquirer": "^9.2.14",
@@ -134,6 +135,7 @@
     "lodash": "^4.17.21",
     "mkdirp": "^3.0.1",
     "moment": "^2.30.1",
+    "mongodb": "^6.21.0",
     "nanospinner": "^1.1.0",
     "node-localstorage": "^3.0.5",
     "os": "^0.1.2",