@testchimp/cli 0.1.0

package/dist/cli/program.js

@@ -0,0 +1,366 @@
+import { Command, Option } from "commander";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { DEFAULT_BACKEND, postMcp } from "../core/client.js";
+import { deepMerge } from "../core/merge.js";
+import { runTool } from "../core/tools.js";
+import { TOOL_DEFINITIONS } from "../core/tools.js";
+export const PACKAGE_VERSION = "0.1.0";
+function parseJsonInput(raw) {
+    if (raw == null || raw.trim() === "")
+        return {};
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("@")) {
+        const path = trimmed.slice(1);
+        const buf = readFileSync(path, "utf8");
+        return JSON.parse(buf);
+    }
+    return JSON.parse(trimmed);
+}
+function mergeBodies(flagBody, jsonInputRaw) {
+    const extra = parseJsonInput(jsonInputRaw);
+    if (Object.keys(extra).length === 0)
+        return flagBody;
+    return deepMerge(flagBody, extra);
+}
+function stderrProgress(msg) {
+    console.error(`[testchimp] ${msg}`);
+}
+export function buildCliProgram() {
+    const program = new Command();
+    program.name("testchimp").description("TestChimp CLI — call project MCP HTTP APIs").version(PACKAGE_VERSION);
+    program
+        .command("mcp")
+        .description("Start the TestChimp MCP server (stdio transport)")
+        .action(async () => {
+        const { runMcpServer } = await import("../mcp/server.js");
+        await runMcpServer();
+    });
+    function jsonInputOption() {
+        return new Option("--json-input <json>", "Advanced: JSON object or @path; merged over flags (JSON wins on conflicts)");
+    }
+    program
+        .command("get-requirement-coverage")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-requirement-coverage").description)
+        .addOption(jsonInputOption())
+        .option("--release <s>")
+        .option("--environment <s>")
+        .option("--branch-name <s>")
+        .option("--file-paths <csv>", "comma-separated paths under platform tests root")
+        .option("--folder-path <path>", "folder under tests root, slash-separated")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.release)
+            body.release = opts.release;
+        if (opts.environment)
+            body.environment = opts.environment;
+        if (opts.branchName)
+            body.branchName = opts.branchName;
+        const scope = {};
+        if (opts.filePaths)
+            scope.filePaths = String(opts.filePaths).split(",").map((s) => s.trim()).filter(Boolean);
+        if (opts.folderPath)
+            scope.folderPath = opts.folderPath;
+        if (Object.keys(scope).length)
+            body.scope = scope;
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-requirement-coverage", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-execution-history")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-execution-history").description)
+        .addOption(jsonInputOption())
+        .option("--release <s>")
+        .option("--environment <s>")
+        .option("--branch-name <s>")
+        .option("--file-paths <csv>")
+        .option("--folder-path <path>")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.release)
+            body.release = opts.release;
+        if (opts.environment)
+            body.environment = opts.environment;
+        if (opts.branchName)
+            body.branchName = opts.branchName;
+        const scope = {};
+        if (opts.filePaths)
+            scope.filePaths = String(opts.filePaths).split(",").map((s) => s.trim()).filter(Boolean);
+        if (opts.folderPath)
+            scope.folderPath = opts.folderPath;
+        if (Object.keys(scope).length)
+            body.scope = scope;
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-execution-history", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("create-user-story")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-user-story").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--platform-file-path <path>")
+        .requiredOption("--title <title>")
+        .action(async (opts) => {
+        const body = { platformFilePath: opts.platformFilePath, title: opts.title };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("create-user-story", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("create-test-scenario")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-test-scenario").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--platform-file-path <path>")
+        .requiredOption("--title <title>")
+        .requiredOption("--user-story-ordinal-id <n>")
+        .action(async (opts) => {
+        const body = {
+            platformFilePath: opts.platformFilePath,
+            title: opts.title,
+            userStoryOrdinalId: Number(opts.userStoryOrdinalId),
+        };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("create-test-scenario", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("update-user-story")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-user-story").description)
+        .addOption(jsonInputOption())
+        .option("--content <markdown>", "full markdown including frontmatter")
+        .option("--content-file <path>", "read markdown from file")
+        .action(async (opts) => {
+        let content = opts.content;
+        if (opts.contentFile)
+            content = await readFile(String(opts.contentFile), "utf8");
+        if (!content)
+            throw new Error("Provide --content or --content-file (or full body via --json-input)");
+        const body = { content };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("update-user-story", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("update-test-scenario")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-test-scenario").description)
+        .addOption(jsonInputOption())
+        .option("--content <markdown>")
+        .option("--content-file <path>")
+        .action(async (opts) => {
+        let content = opts.content;
+        if (opts.contentFile)
+            content = await readFile(String(opts.contentFile), "utf8");
+        if (!content)
+            throw new Error("Provide --content or --content-file (or full body via --json-input)");
+        const body = { content };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("update-test-scenario", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-eaas-config")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-eaas-config").description)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-eaas-config", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-branch-specific-endpoint-config")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-branch-specific-endpoint-config").description)
+        .addOption(jsonInputOption())
+        .option("--branch-name <s>")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.branchName)
+            body.branchName = opts.branchName;
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-branch-specific-endpoint-config", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("provision-ephemeral-environment-and-wait")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "provision-ephemeral-environment-and-wait").description)
+        .addOption(jsonInputOption())
+        .option("--branch-name <s>")
+        .option("--poll-interval-seconds <n>")
+        .option("--max-wait-minutes <n>")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.branchName)
+            body.branchName = opts.branchName;
+        if (opts.pollIntervalSeconds != null)
+            body.pollIntervalSeconds = Number(opts.pollIntervalSeconds);
+        if (opts.maxWaitMinutes != null)
+            body.maxWaitMinutes = Number(opts.maxWaitMinutes);
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("provision-ephemeral-environment-and-wait", merged, {
+            postMcp,
+            onProgress: stderrProgress,
+        });
+        console.log(out);
+    });
+    program
+        .command("provision-ephemeral-environment")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "provision-ephemeral-environment").description)
+        .addOption(jsonInputOption())
+        .option("--branch-name <s>")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.branchName)
+            body.branchName = opts.branchName;
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("provision-ephemeral-environment", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-ephemeral-environment-status")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-ephemeral-environment-status").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--bns-environment-id <id>")
+        .action(async (opts) => {
+        const body = { bnsEnvironmentId: opts.bnsEnvironmentId };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-ephemeral-environment-status", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("destroy-ephemeral-environment")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "destroy-ephemeral-environment").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--bns-environment-id <id>")
+        .action(async (opts) => {
+        const body = { bnsEnvironmentId: opts.bnsEnvironmentId };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("destroy-ephemeral-environment", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("list-bunnyshell-environment-events")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-bunnyshell-environment-events").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--bns-environment-id <id>")
+        .option("--event-type <s>")
+        .option("--event-status <s>")
+        .option("--page <n>")
+        .action(async (opts) => {
+        const body = { bnsEnvironmentId: opts.bnsEnvironmentId };
+        if (opts.eventType)
+            body.eventType = opts.eventType;
+        if (opts.eventStatus)
+            body.eventStatus = opts.eventStatus;
+        if (opts.page != null)
+            body.page = Number(opts.page);
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("list-bunnyshell-environment-events", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("list-bunnyshell-workflow-jobs")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-bunnyshell-workflow-jobs").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--bns-environment-id <id>")
+        .option("--page <n>")
+        .action(async (opts) => {
+        const body = { bnsEnvironmentId: opts.bnsEnvironmentId };
+        if (opts.page != null)
+            body.page = Number(opts.page);
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("list-bunnyshell-workflow-jobs", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-bunnyshell-workflow-job-logs")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-bunnyshell-workflow-job-logs").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--bns-environment-id <id>")
+        .requiredOption("--workflow-job-id <id>")
+        .action(async (opts) => {
+        const body = { bnsEnvironmentId: opts.bnsEnvironmentId, workflowJobId: opts.workflowJobId };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-bunnyshell-workflow-job-logs", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("list-rum-environments")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "list-rum-environments").description)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("list-rum-environments", merged, { postMcp });
+        console.log(out);
+    });
+    const truecoverageHelp = "Prefer --json-input with full request JSON (proto-shaped). Flags are optional shortcuts where listed.";
+    program
+        .command("get-truecoverage-events")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-events").description + " " + truecoverageHelp)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-truecoverage-events", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-truecoverage-event-details")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-event-details").description + " " + truecoverageHelp)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-truecoverage-event-details", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-truecoverage-child-event-tree")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-child-event-tree").description + " " + truecoverageHelp)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-truecoverage-child-event-tree", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-truecoverage-event-transition")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-event-transition").description + " " + truecoverageHelp)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-truecoverage-event-transition", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-truecoverage-event-time-series")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-event-time-series").description + " " + truecoverageHelp)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-truecoverage-event-time-series", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-truecoverage-session-metadata-keys")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-session-metadata-keys").description)
+        .addOption(jsonInputOption())
+        .action(async (opts) => {
+        const merged = mergeBodies({}, opts.jsonInput);
+        const out = await runTool("get-truecoverage-session-metadata-keys", merged, { postMcp });
+        console.log(out);
+    });
+    program
+        .command("get-truecoverage-event-metadata-keys")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-truecoverage-event-metadata-keys").description)
+        .addOption(jsonInputOption())
+        .requiredOption("--event-title <title>")
+        .action(async (opts) => {
+        const body = { eventTitle: opts.eventTitle };
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-truecoverage-event-metadata-keys", merged, { postMcp });
+        console.log(out);
+    });
+    program.on("--help", () => {
+        /* default */
+    });
+    program.addHelpText("after", `\nEnvironment:\n  TESTCHIMP_API_KEY          required\n  TESTCHIMP_BACKEND_URL      optional (default ${DEFAULT_BACKEND})\n\nOutput:\n  Response JSON on stdout.\n  provision-ephemeral-environment-and-wait progress on stderr.\n\nAdvanced:\n  --json-input merges a JSON object over flags (JSON wins on key conflicts). Use @file.json to read from disk.\n`);
+    return program;
+}

package/dist/core/client.d.ts

@@ -0,0 +1,6 @@
+/** HTTP client for TestChimp MCP proxy APIs. */
+export declare const DEFAULT_BACKEND = "https://featureservice.testchimp.io";
+export declare function getBackendUrl(): string;
+export declare function requireApiKey(): string;
+export declare function postMcp(path: string, body: unknown): Promise<string>;
+export type PostMcpFn = (path: string, body: unknown) => Promise<string>;

package/dist/core/client.js

@@ -0,0 +1,32 @@
+/** HTTP client for TestChimp MCP proxy APIs. */
+export const DEFAULT_BACKEND = "https://featureservice.testchimp.io";
+export function getBackendUrl() {
+    const raw = process.env.TESTCHIMP_BACKEND_URL?.trim();
+    if (!raw)
+        return DEFAULT_BACKEND;
+    return raw.replace(/\/$/, "");
+}
+export function requireApiKey() {
+    const k = process.env.TESTCHIMP_API_KEY?.trim();
+    if (!k) {
+        throw new Error("TESTCHIMP_API_KEY is required. Set it in your project MCP config env (e.g. Cursor .cursor/mcp.json), then export it in the shell for CLI, or rely on the IDE for MCP.");
+    }
+    return k;
+}
+export async function postMcp(path, body) {
+    const apiKey = requireApiKey();
+    const url = `${getBackendUrl()}${path}`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "TestChimp-Api-Key": apiKey,
+        },
+        body: JSON.stringify(body ?? {}),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`TestChimp API ${res.status} ${res.statusText}: ${text}`);
+    }
+    return text;
+}

package/dist/core/ephemeralWait.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Poll TestChimp MCP EaaS endpoints until BunnyShell reports deployed + component URLs,
+ * or a terminal failure / timeout.
+ */
+export interface ProvisionWaitArgs {
+    branchName?: string;
+    pollIntervalSeconds?: number;
+    maxWaitMinutes?: number;
+}
+export type ProgressLog = (message: string) => void | Promise<void>;
+export declare function runProvisionEphemeralEnvironmentAndWait(postMcp: (path: string, body: unknown) => Promise<string>, log: ProgressLog | undefined, args: ProvisionWaitArgs): Promise<string>;

package/dist/core/ephemeralWait.js

@@ -0,0 +1,194 @@
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function clamp(n, min, max) {
+    return Math.min(max, Math.max(min, n));
+}
+function pickStr(obj, ...keys) {
+    for (const k of keys) {
+        const v = obj[k];
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    }
+    return "";
+}
+function parseJsonObject(text) {
+    try {
+        const v = JSON.parse(text);
+        return v !== null && typeof v === "object" && !Array.isArray(v)
+            ? v
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function componentUrlsNonEmpty(componentUrlsJson) {
+    const t = componentUrlsJson.trim();
+    if (!t)
+        return false;
+    try {
+        const v = JSON.parse(t);
+        if (v === null || typeof v !== "object" || Array.isArray(v))
+            return false;
+        return Object.keys(v).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function isTerminalDeployFailure(aggregateStatus, operationStatus, clusterStatus) {
+    const ag = aggregateStatus.toLowerCase().trim();
+    if (ag === "deployed")
+        return false;
+    const op = operationStatus.toLowerCase();
+    const cl = clusterStatus.toLowerCase();
+    if (op.includes("deploying") || op.includes("in_progress") || op.includes("in progress")) {
+        return false;
+    }
+    const bad = /\b(fail|failed|failure|error|deleted)\b/;
+    if (bad.test(op) || bad.test(cl) || bad.test(ag))
+        return true;
+    return false;
+}
+function lastStatusSnapshot(obj) {
+    return {
+        status: pickStr(obj, "status", "Status"),
+        operationStatus: pickStr(obj, "operationStatus", "operation_status"),
+        clusterStatus: pickStr(obj, "clusterStatus", "cluster_status"),
+        environmentType: pickStr(obj, "environmentType", "environment_type"),
+        dashboardUrl: pickStr(obj, "dashboardUrl", "dashboard_url"),
+    };
+}
+export async function runProvisionEphemeralEnvironmentAndWait(postMcp, log, args) {
+    const pollIntervalSec = clamp(Math.round(args.pollIntervalSeconds ?? 60), 30, 120);
+    const maxWaitMin = clamp(Math.round(args.maxWaitMinutes ?? 25), 5, 45);
+    const deadline = Date.now() + maxWaitMin * 60 * 1000;
+    const intervalMs = pollIntervalSec * 1000;
+    const provisionBody = {};
+    if (args.branchName != null && args.branchName.trim() !== "") {
+        provisionBody.branchName = args.branchName.trim();
+    }
+    let bnsEnvironmentId = "";
+    let branch = "";
+    let provisionRaw = "";
+    try {
+        provisionRaw = await postMcp("/api/mcp/provision_ephemeral_environment", provisionBody);
+    }
+    catch (e) {
+        const errMsg = e instanceof Error ? e.message : String(e);
+        return JSON.stringify({
+            outcome: "failed",
+            failure_phase: "provision",
+            message: `Could not start ephemeral environment (create/deploy trigger failed). ${errMsg}`,
+            bns_environment_id: "",
+            branch: "",
+            component_urls_json: "",
+            last_status: {},
+        });
+    }
+    const prov = parseJsonObject(provisionRaw);
+    bnsEnvironmentId = pickStr(prov, "bnsEnvironmentId", "bns_environment_id");
+    branch = pickStr(prov, "branch", "branch_name");
+    if (!bnsEnvironmentId) {
+        return JSON.stringify({
+            outcome: "failed",
+            failure_phase: "provision",
+            message: "Provision response did not include bns_environment_id. Check BunnyShell + GitHub integration and project EaaS settings.",
+            bns_environment_id: "",
+            branch,
+            component_urls_json: "",
+            last_status: prov,
+        });
+    }
+    await Promise.resolve(log?.(`Ephemeral env provision started (bns=${bnsEnvironmentId}, branch=${branch || "?"}). Polling up to ${maxWaitMin} min, every ${pollIntervalSec}s.`));
+    let pollIndex = 0;
+    let lastSnapshot = {};
+    let lastComponentUrlsJson = "";
+    let lastDashboardUrl = "";
+    while (Date.now() < deadline) {
+        pollIndex += 1;
+        let statusRaw;
+        try {
+            statusRaw = await postMcp("/api/mcp/get_ephemeral_environment_status", {
+                bnsEnvironmentId,
+            });
+        }
+        catch (e) {
+            const errMsg = e instanceof Error ? e.message : String(e);
+            return JSON.stringify({
+                outcome: "failed",
+                failure_phase: "deploy",
+                message: `Status check failed while waiting for deployment: ${errMsg}`,
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                component_urls_json: "",
+                last_status: lastSnapshot,
+            });
+        }
+        const st = parseJsonObject(statusRaw);
+        lastSnapshot = lastStatusSnapshot(st);
+        const aggregateStatus = pickStr(st, "status", "Status");
+        const operationStatus = pickStr(st, "operationStatus", "operation_status");
+        const clusterStatus = pickStr(st, "clusterStatus", "cluster_status");
+        const componentUrlsJson = pickStr(st, "componentUrlsJson", "component_urls_json");
+        const dashboardUrl = pickStr(st, "dashboardUrl", "dashboard_url");
+        lastComponentUrlsJson = componentUrlsJson;
+        lastDashboardUrl = dashboardUrl;
+        await Promise.resolve(log?.(`Still waiting for ephemeral environment (poll ${pollIndex}): status=${aggregateStatus} op=${operationStatus} cluster=${clusterStatus} bns=${bnsEnvironmentId}`));
+        const deployed = aggregateStatus.toLowerCase() === "deployed";
+        const urlsOk = componentUrlsNonEmpty(componentUrlsJson);
+        if (deployed && urlsOk) {
+            return JSON.stringify({
+                outcome: "success",
+                message: "Ephemeral environment is deployed and component URLs are available.",
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                dashboard_url: dashboardUrl,
+                component_urls_json: componentUrlsJson,
+                ready_for_seeding: true,
+                last_status: lastSnapshot,
+            });
+        }
+        if (deployed && !urlsOk) {
+            return JSON.stringify({
+                outcome: "success",
+                message: "Environment reports deployed but component URL map is empty or missing; check BunnyShell definition or dashboard.",
+                warnings: ["component_urls_json_empty_or_unparsed"],
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                dashboard_url: dashboardUrl,
+                component_urls_json: componentUrlsJson,
+                ready_for_seeding: false,
+                last_status: lastSnapshot,
+            });
+        }
+        if (isTerminalDeployFailure(aggregateStatus, operationStatus, clusterStatus)) {
+            return JSON.stringify({
+                outcome: "failed",
+                failure_phase: "deploy",
+                message: `BunnyShell deployment did not succeed (status=${aggregateStatus}, operation=${operationStatus}, cluster=${clusterStatus}).`,
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                dashboard_url: dashboardUrl,
+                component_urls_json: componentUrlsJson,
+                last_status: lastSnapshot,
+            });
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        const sleepMs = Math.min(intervalMs, remainingMs);
+        await sleep(sleepMs);
+    }
+    return JSON.stringify({
+        outcome: "timeout",
+        failure_phase: "wait",
+        message: `Timed out after ${maxWaitMin} minutes waiting for ephemeral environment ${bnsEnvironmentId} to become ready.`,
+        bns_environment_id: bnsEnvironmentId,
+        branch,
+        dashboard_url: lastDashboardUrl,
+        component_urls_json: lastComponentUrlsJson,
+        last_status: lastSnapshot,
+    });
+}

package/dist/core/merge.d.ts

@@ -0,0 +1,2 @@
+/** Deep-merge plain objects; values from `override` win on conflicts. Arrays and primitives replace entirely. */
+export declare function deepMerge(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;

package/dist/core/merge.js

@@ -0,0 +1,13 @@
+/** Deep-merge plain objects; values from `override` win on conflicts. Arrays and primitives replace entirely. */
+export function deepMerge(base, override) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+        if (v !== null && typeof v === "object" && !Array.isArray(v) && out[k] !== null && typeof out[k] === "object" && !Array.isArray(out[k])) {
+            out[k] = deepMerge(out[k], v);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}

package/dist/core/normalize.d.ts

@@ -0,0 +1,7 @@
+export declare function normalizeScope(scope: {
+    filePaths?: string[];
+    folderPath?: string[] | string;
+}): {
+    filePaths?: string[];
+    folderPath?: string[];
+};

package/dist/core/normalize.js

@@ -0,0 +1,18 @@
+export function normalizeScope(scope) {
+    let folderPath;
+    if (Array.isArray(scope.folderPath)) {
+        folderPath = scope.folderPath;
+    }
+    else if (typeof scope.folderPath === "string" && scope.folderPath.trim() !== "") {
+        folderPath = scope.folderPath
+            .split("/")
+            .map((seg) => seg.trim())
+            .filter(Boolean);
+    }
+    const out = {};
+    if (scope.filePaths?.length)
+        out.filePaths = scope.filePaths;
+    if (folderPath)
+        out.folderPath = folderPath;
+    return out;
+}