@testchimp/cli 0.1.0

package/dist/core/schemas.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+export declare const scopeSchema: z.ZodOptional<z.ZodObject<{
+    filePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    folderPath: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+}, z.core.$strip>>;
+export declare const listCoverageInput: z.ZodObject<{
+    release: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodObject<{
+        filePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        folderPath: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+    }, z.core.$strip>>;
+    includeNonCoveredUserStories: z.ZodOptional<z.ZodBoolean>;
+    includeNonCoveredTestScenarios: z.ZodOptional<z.ZodBoolean>;
+    branchName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const listExecutionInput: z.ZodObject<{
+    release: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodObject<{
+        filePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        folderPath: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+    }, z.core.$strip>>;
+    branchName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const createUserStoryInput: z.ZodObject<{
+    platformFilePath: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+export declare const createTestScenarioInput: z.ZodObject<{
+    platformFilePath: z.ZodString;
+    title: z.ZodString;
+    userStoryOrdinalId: z.ZodCoercedNumber<unknown>;
+}, z.core.$strip>;
+export declare const updatePlanMarkdownInput: z.ZodObject<{
+    content: z.ZodString;
+}, z.core.$strip>;
+export declare const emptyInput: z.ZodObject<{}, z.core.$strip>;
+export declare const getBranchSpecificEndpointConfigInput: z.ZodObject<{
+    branchName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const truecoverageJsonInput: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const eventMetadataKeysInput: z.ZodObject<{
+    eventTitle: z.ZodString;
+}, z.core.$strip>;
+export declare const provisionEphemeralInput: z.ZodObject<{
+    branchName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const bnsEnvironmentIdInput: z.ZodObject<{
+    bnsEnvironmentId: z.ZodString;
+}, z.core.$strip>;
+export declare const provisionEphemeralWaitInput: z.ZodObject<{
+    branchName: z.ZodOptional<z.ZodString>;
+    pollIntervalSeconds: z.ZodOptional<z.ZodNumber>;
+    maxWaitMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const listBunnyshellEnvironmentEventsInput: z.ZodObject<{
+    bnsEnvironmentId: z.ZodString;
+    eventType: z.ZodOptional<z.ZodString>;
+    eventStatus: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const listBunnyshellWorkflowJobsInput: z.ZodObject<{
+    bnsEnvironmentId: z.ZodString;
+    page: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const getBunnyshellWorkflowJobLogsInput: z.ZodObject<{
+    bnsEnvironmentId: z.ZodString;
+    workflowJobId: z.ZodString;
+}, z.core.$strip>;

package/dist/core/schemas.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+export const scopeSchema = z
+    .object({
+    filePaths: z.array(z.string()).optional(),
+    folderPath: z.union([z.array(z.string()), z.string()]).optional(),
+})
+    .optional();
+export const listCoverageInput = z.object({
+    release: z.string().optional(),
+    environment: z.string().optional(),
+    scope: scopeSchema,
+    includeNonCoveredUserStories: z.boolean().optional(),
+    includeNonCoveredTestScenarios: z.boolean().optional(),
+    branchName: z.string().optional(),
+});
+export const listExecutionInput = z.object({
+    release: z.string().optional(),
+    environment: z.string().optional(),
+    scope: scopeSchema,
+    branchName: z.string().optional(),
+});
+export const createUserStoryInput = z.object({
+    platformFilePath: z.string().min(1),
+    title: z.string().min(1),
+});
+export const createTestScenarioInput = z.object({
+    platformFilePath: z.string().min(1),
+    title: z.string().min(1),
+    userStoryOrdinalId: z.coerce.number().int().positive(),
+});
+export const updatePlanMarkdownInput = z.object({
+    content: z.string().min(1),
+});
+export const emptyInput = z.object({});
+export const getBranchSpecificEndpointConfigInput = z.object({
+    branchName: z.string().optional(),
+});
+export const truecoverageJsonInput = z.record(z.string(), z.unknown());
+export const eventMetadataKeysInput = z.object({
+    eventTitle: z.string().min(1),
+});
+export const provisionEphemeralInput = z.object({
+    branchName: z.string().optional(),
+});
+export const bnsEnvironmentIdInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+});
+export const provisionEphemeralWaitInput = z.object({
+    branchName: z.string().optional(),
+    pollIntervalSeconds: z.number().optional(),
+    maxWaitMinutes: z.number().optional(),
+});
+export const listBunnyshellEnvironmentEventsInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+    eventType: z.string().optional(),
+    eventStatus: z.string().optional(),
+    page: z.number().int().positive().optional(),
+});
+export const listBunnyshellWorkflowJobsInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+    page: z.number().int().positive().optional(),
+});
+export const getBunnyshellWorkflowJobLogsInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+    workflowJobId: z.string().min(1),
+});

package/dist/core/tools.d.ts

@@ -0,0 +1,16 @@
+import { type ZodTypeAny } from "zod";
+import type { PostMcpFn } from "./client.js";
+import { type ProgressLog } from "./ephemeralWait.js";
+export interface ToolContext {
+    postMcp: PostMcpFn;
+    onProgress?: ProgressLog;
+}
+export interface ToolDefinition {
+    kebab: string;
+    description: string;
+    inputSchema: ZodTypeAny;
+    execute: (args: unknown, ctx: ToolContext) => Promise<string>;
+}
+export declare const TOOL_DEFINITIONS: ToolDefinition[];
+export declare function getToolDefinition(kebab: string): ToolDefinition | undefined;
+export declare function runTool(kebab: string, rawArgs: unknown, ctx: ToolContext): Promise<string>;

package/dist/core/tools.js

@@ -0,0 +1,270 @@
+import { normalizeScope } from "./normalize.js";
+import { runProvisionEphemeralEnvironmentAndWait } from "./ephemeralWait.js";
+import * as S from "./schemas.js";
+function listCoverageBody(args) {
+    const body = {};
+    if (args.release != null)
+        body.release = args.release;
+    if (args.environment != null)
+        body.environment = args.environment;
+    if (args.scope != null)
+        body.scope = normalizeScope(args.scope);
+    if (args.includeNonCoveredUserStories != null)
+        body.includeNonCoveredUserStories = args.includeNonCoveredUserStories;
+    if (args.includeNonCoveredTestScenarios != null) {
+        body.includeNonCoveredTestScenarios = args.includeNonCoveredTestScenarios;
+    }
+    if (args.branchName != null && args.branchName.trim() !== "")
+        body.branchName = args.branchName.trim();
+    return body;
+}
+function listExecutionBody(args) {
+    const body = {};
+    if (args.release != null)
+        body.release = args.release;
+    if (args.environment != null)
+        body.environment = args.environment;
+    if (args.scope != null)
+        body.scope = normalizeScope(args.scope);
+    if (args.branchName != null && args.branchName.trim() !== "")
+        body.branchName = args.branchName.trim();
+    return body;
+}
+export const TOOL_DEFINITIONS = [
+    {
+        kebab: "get-requirement-coverage",
+        description: "Fetch requirement (scenario) coverage under an optional platform-rooted folder scope (tests/... or plans/...). " +
+            "Use branchName (Git branch) and scope.filePaths (paths under platform tests root) rather than internal ids.",
+        inputSchema: S.listCoverageInput,
+        execute: async (args, { postMcp }) => {
+            const json = await postMcp("/api/mcp/list_requirement_coverage", listCoverageBody(args));
+            return json;
+        },
+    },
+    {
+        kebab: "get-execution-history",
+        description: "Fetch SmartTest execution history for an optional platform-rooted folder scope. " +
+            "Use branchName and scope.filePaths as for coverage.",
+        inputSchema: S.listExecutionInput,
+        execute: async (args, { postMcp }) => {
+            const json = await postMcp("/api/mcp/list_execution_history", listExecutionBody(args));
+            return json;
+        },
+    },
+    {
+        kebab: "create-user-story",
+        description: "Create a user story on the TestChimp project and its plan file stub. " +
+            "Always call this before writing a new story markdown file; use the returned ordinalId as US-<ordinalId> in frontmatter. " +
+            "platformFilePath must be under plans/stories/ and end with .md.",
+        inputSchema: S.createUserStoryInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/create_user_story", {
+                platformFilePath: a.platformFilePath,
+                title: a.title,
+            });
+        },
+    },
+    {
+        kebab: "create-test-scenario",
+        description: "Create a test scenario linked to a user story. platformFilePath must be under plans/scenarios/ and end with .md. " +
+            "userStoryOrdinalId is the numeric part of the parent US-<n> id.",
+        inputSchema: S.createTestScenarioInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/create_test_scenario", {
+                platformFilePath: a.platformFilePath,
+                title: a.title,
+                userStoryOrdinalId: a.userStoryOrdinalId,
+            });
+        },
+    },
+    {
+        kebab: "update-user-story",
+        description: "Sync a user story markdown file to the platform after local edits. " +
+            "Parses frontmatter (id: US-..., title, priority, status) and updates the linked support file and entity.",
+        inputSchema: S.updatePlanMarkdownInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/update_user_story", { content: a.content });
+        },
+    },
+    {
+        kebab: "update-test-scenario",
+        description: "Sync a test scenario markdown file to the platform after local edits. " +
+            "Parses frontmatter (id: TS-..., story: US-..., title, priority, status) and updates linking if story changes.",
+        inputSchema: S.updatePlanMarkdownInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/update_test_scenario", { content: a.content });
+        },
+    },
+    {
+        kebab: "get-eaas-config",
+        description: "Return the project's BunnyShell (Environment-as-a-Service) settings. Secrets are never returned.",
+        inputSchema: S.emptyInput,
+        execute: async (_args, { postMcp }) => postMcp("/api/mcp/get_eaas_config", {}),
+    },
+    {
+        kebab: "get-branch-specific-endpoint-config",
+        description: "Resolve BASE_URL for a Git branch from TestChimp Branch Management (URL template and per-branch overrides).",
+        inputSchema: S.getBranchSpecificEndpointConfigInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.branchName != null && a.branchName.trim() !== "")
+                body.branchName = a.branchName.trim();
+            return postMcp("/api/mcp/get_branch_specific_endpoint_config", body);
+        },
+    },
+    {
+        kebab: "provision-ephemeral-environment-and-wait",
+        description: "Provision a BunnyShell ephemeral environment, then poll until deployed and component URLs are available. " +
+            "Progress is logged to stderr (CLI) or MCP logging when supported.",
+        inputSchema: S.provisionEphemeralWaitInput,
+        execute: async (args, { postMcp, onProgress }) => {
+            const a = args;
+            return runProvisionEphemeralEnvironmentAndWait(postMcp, onProgress, {
+                branchName: a.branchName,
+                pollIntervalSeconds: a.pollIntervalSeconds,
+                maxWaitMinutes: a.maxWaitMinutes,
+            });
+        },
+    },
+    {
+        kebab: "provision-ephemeral-environment",
+        description: "Create a BunnyShell ephemeral environment (create + deploy trigger only). Prefer provision-ephemeral-environment-and-wait for normal flows.",
+        inputSchema: S.provisionEphemeralInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.branchName != null && a.branchName.trim() !== "")
+                body.branchName = a.branchName.trim();
+            return postMcp("/api/mcp/provision_ephemeral_environment", body);
+        },
+    },
+    {
+        kebab: "get-ephemeral-environment-status",
+        description: "Poll BunnyShell for environment status and component_urls_json.",
+        inputSchema: S.bnsEnvironmentIdInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/get_ephemeral_environment_status", { bnsEnvironmentId: a.bnsEnvironmentId });
+        },
+    },
+    {
+        kebab: "destroy-ephemeral-environment",
+        description: "Delete a BunnyShell environment created for this project.",
+        inputSchema: S.bnsEnvironmentIdInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/destroy_ephemeral_environment", { bnsEnvironmentId: a.bnsEnvironmentId });
+        },
+    },
+    {
+        kebab: "list-bunnyshell-environment-events",
+        description: "Troubleshooting: list BunnyShell platform events for an environment.",
+        inputSchema: S.listBunnyshellEnvironmentEventsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = { bnsEnvironmentId: a.bnsEnvironmentId };
+            if (a.eventType != null && a.eventType.trim() !== "")
+                body.eventType = a.eventType.trim();
+            if (a.eventStatus != null && a.eventStatus.trim() !== "")
+                body.eventStatus = a.eventStatus.trim();
+            if (a.page != null)
+                body.page = a.page;
+            return postMcp("/api/mcp/list_bunnyshell_environment_events", body);
+        },
+    },
+    {
+        kebab: "list-bunnyshell-workflow-jobs",
+        description: "Troubleshooting: list BunnyShell workflow jobs for an environment.",
+        inputSchema: S.listBunnyshellWorkflowJobsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = { bnsEnvironmentId: a.bnsEnvironmentId };
+            if (a.page != null)
+                body.page = a.page;
+            return postMcp("/api/mcp/list_bunnyshell_workflow_jobs", body);
+        },
+    },
+    {
+        kebab: "get-bunnyshell-workflow-job-logs",
+        description: "Troubleshooting: fetch logs for a BunnyShell workflow job.",
+        inputSchema: S.getBunnyshellWorkflowJobLogsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/get_bunnyshell_workflow_job_logs", {
+                bnsEnvironmentId: a.bnsEnvironmentId,
+                workflowJobId: a.workflowJobId,
+            });
+        },
+    },
+    {
+        kebab: "list-rum-environments",
+        description: "List distinct RUM environment tags for TrueCoverage scoping.",
+        inputSchema: S.emptyInput,
+        execute: async (_args, { postMcp }) => postMcp("/api/mcp/list_rum_environments", {}),
+    },
+    {
+        kebab: "get-truecoverage-events",
+        description: "TrueCoverage event funnel summaries (ListEventsRequest JSON: baseExecutionScope, comparisonExecutionScope).",
+        inputSchema: S.truecoverageJsonInput,
+        execute: async (args, { postMcp }) => postMcp("/api/mcp/truecoverage_list_events", args ?? {}),
+    },
+    {
+        kebab: "get-truecoverage-event-details",
+        description: "TrueCoverage drill-down for one event title (GetEventDetailsRequest JSON).",
+        inputSchema: S.truecoverageJsonInput,
+        execute: async (args, { postMcp }) => postMcp("/api/mcp/truecoverage_event_details", args ?? {}),
+    },
+    {
+        kebab: "get-truecoverage-child-event-tree",
+        description: "TrueCoverage next-event tree for an event (ListChildEventTreeRequest JSON).",
+        inputSchema: S.truecoverageJsonInput,
+        execute: async (args, { postMcp }) => postMcp("/api/mcp/truecoverage_list_child_event_tree", args ?? {}),
+    },
+    {
+        kebab: "get-truecoverage-event-transition",
+        description: "TrueCoverage detailed transition summary between events (GetDetailedEventTransitionSummaryRequest JSON).",
+        inputSchema: S.truecoverageJsonInput,
+        execute: async (args, { postMcp }) => postMcp("/api/mcp/truecoverage_detailed_event_transition", args ?? {}),
+    },
+    {
+        kebab: "get-truecoverage-event-time-series",
+        description: "TrueCoverage time series for sessions or metrics (EventTimeSeriesRequest JSON).",
+        inputSchema: S.truecoverageJsonInput,
+        execute: async (args, { postMcp }) => postMcp("/api/mcp/truecoverage_event_time_series", args ?? {}),
+    },
+    {
+        kebab: "get-truecoverage-session-metadata-keys",
+        description: "List session-level metadata keys observed for TrueCoverage.",
+        inputSchema: S.emptyInput,
+        execute: async (_args, { postMcp }) => postMcp("/api/mcp/truecoverage_session_metadata_keys", {}),
+    },
+    {
+        kebab: "get-truecoverage-event-metadata-keys",
+        description: "List metadata keys for a given event title.",
+        inputSchema: S.eventMetadataKeysInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/truecoverage_event_metadata_keys", { eventTitle: a.eventTitle });
+        },
+    },
+];
+const TOOL_BY_KEBAB = new Map(TOOL_DEFINITIONS.map((t) => [t.kebab, t]));
+export function getToolDefinition(kebab) {
+    return TOOL_BY_KEBAB.get(kebab);
+}
+export async function runTool(kebab, rawArgs, ctx) {
+    const def = TOOL_BY_KEBAB.get(kebab);
+    if (!def)
+        throw new Error(`Unknown tool: ${kebab}`);
+    const raw = rawArgs === undefined || rawArgs === null ? {} : rawArgs;
+    const parsed = def.inputSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid input for ${kebab}: ${parsed.error.message}`);
+    }
+    return def.execute(parsed.data, ctx);
+}

package/dist/ephemeralProvisionWait.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Poll TestChimp MCP EaaS endpoints until BunnyShell reports deployed + component URLs,
+ * or a terminal failure / timeout. See plan: provision_ephemeral_environment_and_wait.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface ProvisionWaitArgs {
+    branchName?: string;
+    pollIntervalSeconds?: number;
+    maxWaitMinutes?: number;
+}
+export declare function runProvisionEphemeralEnvironmentAndWait(postMcp: (path: string, body: unknown) => Promise<string>, server: McpServer, args: ProvisionWaitArgs): Promise<string>;

package/dist/ephemeralProvisionWait.js

@@ -0,0 +1,206 @@
+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;
+    }
+}
+/** True if BNS / aggregate status indicates we should stop polling with failure (deploy phase). */
+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"),
+    };
+}
+async function logInfo(server, message) {
+    try {
+        await server.sendLoggingMessage({
+            level: "info",
+            data: message,
+        });
+    }
+    catch {
+        // Client may not support logging; ignore.
+    }
+}
+export async function runProvisionEphemeralEnvironmentAndWait(postMcp, server, 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 logInfo(server, `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 logInfo(server, `Ephemeral env 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/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};