@devicecloud.dev/dcd 5.0.0-beta.0 → 5.0.0-beta.1

package/dist/gateways/api-gateway.js

@@ -1,16 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiGateway = exports.ApiError = void 0;
-const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
-const path = require("node:path");
-const node_stream_1 = require("node:stream");
-const promises_1 = require("node:stream/promises");
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 /**
  * Error thrown for non-OK API responses, carrying the HTTP status so callers
  * can branch on auth failures etc. without string matching.
  */
-class ApiError extends Error {
+export class ApiError extends Error {
     status;
     constructor(message, status) {
         super(message);
@@ -18,7 +15,6 @@ class ApiError extends Error {
         this.status = status;
     }
 }
-exports.ApiError = ApiError;
 /**
  * Parses a successful response body as JSON, wrapping parse failures in a
  * descriptive error (a 200 with an HTML body otherwise surfaces as a bare
@@ -29,10 +25,10 @@ async function parseJsonResponse(res, operation) {
         return (await res.json());
     }
     catch (error) {
-        throw new Error(`${operation}: API returned an invalid JSON response (${error instanceof Error ? error.message : String(error)})`);
+        throw new Error(`${operation}: API returned an invalid JSON response (${error instanceof Error ? error.message : String(error)})`, { cause: error });
     }
 }
-exports.ApiGateway = {
+export const ApiGateway = {
     /**
      * Enhances generic "fetch failed" errors with more specific diagnostic information
      * @param error - The original TypeError from fetch
@@ -131,17 +127,17 @@ exports.ApiGateway = {
             throw new Error(`${operation}: server response contained no body to download`);
         }
         // Handle tilde expansion for home directory
-        const expandedPath = destinationPath.replace(/^~(?=$|\/|\\)/, (0, node_os_1.homedir)());
+        const expandedPath = destinationPath.replace(/^~(?=$|\/|\\)/, homedir());
         // Create directory structure if it doesn't exist
         const directory = path.dirname(expandedPath);
         if (directory !== '.') {
-            (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+            mkdirSync(directory, { recursive: true });
         }
         // Use 'w' flag to overwrite existing files instead of failing.
         // pipeline (unlike .pipe) propagates source-stream errors, so a
         // mid-download network failure rejects instead of hanging forever.
-        const fileStream = (0, node_fs_1.createWriteStream)(expandedPath, { flags: 'w' });
-        await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(res.body), fileStream);
+        const fileStream = createWriteStream(expandedPath, { flags: 'w' });
+        await pipeline(Readable.fromWeb(res.body), fileStream);
     },
     async checkForExistingUpload(baseUrl, auth, sha) {
         try {
@@ -364,6 +360,64 @@ exports.ApiGateway = {
             throw error;
         }
     },
+    /**
+     * Requests a storage URL for a client-direct flow zip upload. Mirrors
+     * `getBinaryUploadUrl` (same response shape) but stages the zip under
+     * `<orgId>/tests/` instead of the app-binary path. A 404 here means the API
+     * predates the client-direct flow path — callers fall back to `uploadFlow`.
+     */
+    async getFlowUploadUrl(baseUrl, auth, fileSize) {
+        try {
+            const res = await fetch(`${baseUrl}/uploads/getFlowUploadUrl`, {
+                body: JSON.stringify({ fileSize, useTus: true }),
+                headers: {
+                    'content-type': 'application/json',
+                    ...auth.headers,
+                },
+                method: 'POST',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to get flow upload URL');
+            }
+            // Same response shape as getBinaryUploadUrl: { id, tempPath, finalPath, path, b2?, token? }.
+            return await parseJsonResponse(res, 'Failed to get flow upload URL');
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, `${baseUrl}/uploads/getFlowUploadUrl`);
+            }
+            throw error;
+        }
+    },
+    /**
+     * Submits a flow test that references an already-uploaded zip (JSON body, no
+     * multipart). The response is identical to the legacy `POST /uploads/flow`.
+     * A 404 means the API predates this endpoint — callers fall back to
+     * `uploadFlow`.
+     */
+    async submitFlowTest(baseUrl, auth, body) {
+        try {
+            const res = await fetch(`${baseUrl}/uploads/submitFlowTest`, {
+                body: JSON.stringify(body),
+                headers: {
+                    'content-type': 'application/json',
+                    ...auth.headers,
+                },
+                method: 'POST',
+            });
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to submit test flows');
+            }
+            // Identical response to the legacy multipart POST /uploads/flow.
+            return await parseJsonResponse(res, 'Failed to submit test flows');
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, `${baseUrl}/uploads/submitFlowTest`);
+            }
+            throw error;
+        }
+    },
     /**
      * Generic report download method that handles both junit and allure reports
      * @param baseUrl - API base URL

package/dist/gateways/cli-auth-gateway.d.ts

@@ -1,4 +1,4 @@
-import type { StoredSession } from '../utils/config-store';
+import type { StoredSession } from '../utils/config-store.js';
 export interface RefreshedSession {
     access_token: string;
     refresh_token: string;

package/dist/gateways/cli-auth-gateway.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliAuthGateway = void 0;
 /**
  * Supabase session operations for the CLI: refresh an expired access token
  * and sign-out (best-effort revocation on the Supabase side).
@@ -8,13 +5,13 @@ exports.CliAuthGateway = void 0;
  * Does not talk to the dcd API — the dcd-side session exchange lives in the
  * login command's loopback flow, where the frontend POSTs ciphertext back.
  */
-const supabase_js_1 = require("@supabase/supabase-js");
+import { createClient } from '@supabase/supabase-js';
 function client(supabaseUrl, supabaseAnonKey) {
-    return (0, supabase_js_1.createClient)(supabaseUrl, supabaseAnonKey, {
+    return createClient(supabaseUrl, supabaseAnonKey, {
         auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
     });
 }
-exports.CliAuthGateway = {
+export const CliAuthGateway = {
     async refresh(supabaseUrl, supabaseAnonKey, session) {
         const sb = client(supabaseUrl, supabaseAnonKey);
         const { data, error } = await sb.auth.refreshSession({

package/dist/gateways/realtime-gateway.d.ts

@@ -0,0 +1,32 @@
+import { type DcdEnvName } from '../config/environments.js';
+export interface RealtimeResultsSubscription {
+    /**
+     * Whether the channel is currently subscribed and receiving pushes. False
+     * until the socket subscribes, and again if it errors/closes — the backstop
+     * poll always covers the gap.
+     */
+    isConnected(): boolean;
+    /** Tear down the channel and close the socket. Best-effort, never throws. */
+    unsubscribe(): Promise<void>;
+}
+export interface RealtimeSubscribeOptions {
+    /** Supabase JWT (AuthContext.accessToken) — authorises the socket for RLS. */
+    accessToken: string;
+    debug?: boolean;
+    env: DcdEnvName;
+    /** Stderr-safe logger; stdout is reserved by some callers (MCP). */
+    log?: (message: string) => void;
+    /** Fired when a result row for this upload changes. */
+    onChange: () => void;
+    /** Fired whenever the connection state flips (subscribed ↔ disconnected). */
+    onConnectionChange?: (connected: boolean) => void;
+    orgId: string;
+    uploadId: string;
+}
+export declare class RealtimeResultsGateway {
+    /**
+     * Open a realtime subscription to `results` changes for the given upload.
+     * Construction never throws — on any failure the caller simply keeps polling.
+     */
+    static subscribe(options: RealtimeSubscribeOptions): RealtimeResultsSubscription;
+}

package/dist/gateways/realtime-gateway.js

@@ -0,0 +1,103 @@
+/**
+ * Supabase Realtime subscription to test-result status changes.
+ *
+ * This is a *latency optimisation* layered on top of HTTP polling, not a
+ * replacement for it. A logged-in (bearer) user's JWT authorises a
+ * `postgres_changes` subscription on the `results` table (RLS scopes rows to
+ * the user's org via `app_metadata.org_ids`). Each relevant change fires
+ * `onChange`, which the polling loop uses to fetch immediately instead of
+ * waiting out the full backstop interval.
+ *
+ * We deliberately only read the `new` row's `test_upload_id` — Postgres always
+ * ships the full new tuple on INSERT/UPDATE regardless of REPLICA IDENTITY, so
+ * no DB change is required. Mirrors the frontend pattern in
+ * dcd/frontend/app/stores/Results.store.ts.
+ */
+import { createClient, REALTIME_SUBSCRIBE_STATES, } from '@supabase/supabase-js';
+import { ENVIRONMENTS } from '../config/environments.js';
+export class RealtimeResultsGateway {
+    /**
+     * Open a realtime subscription to `results` changes for the given upload.
+     * Construction never throws — on any failure the caller simply keeps polling.
+     */
+    static subscribe(options) {
+        const { accessToken, debug, env, log, onChange, onConnectionChange, orgId, uploadId } = options;
+        const dbg = (message) => {
+            if (debug && log)
+                log(`[DEBUG] [realtime] ${message}`);
+        };
+        let connected = false;
+        const setConnected = (next) => {
+            if (next === connected)
+                return;
+            connected = next;
+            onConnectionChange?.(next);
+        };
+        let client;
+        try {
+            const { url, anonKey } = ENVIRONMENTS[env].supabase;
+            client = createClient(url, anonKey, {
+                // Match SupabaseClientGateway / the frontend; no session persistence —
+                // we set the token explicitly below.
+                auth: { autoRefreshToken: false, persistSession: false },
+                realtime: { params: { eventsPerSecond: 10 } },
+            });
+            // Attach the user's JWT to the socket so RLS is enforced on the channel.
+            client.realtime.setAuth(accessToken);
+            const channel = client
+                .channel(`results-cli-${uploadId}`)
+                .on(
+            // The typings don't cover the postgres_changes overload cleanly.
+            'postgres_changes', {
+                event: '*',
+                schema: 'public',
+                table: 'results',
+                filter: `org_id=eq.${orgId}`,
+            }, (payload) => {
+                if (payload.new?.test_upload_id === uploadId) {
+                    dbg(`change for upload ${uploadId}`);
+                    onChange();
+                }
+            })
+                .subscribe((status) => {
+                if (status === REALTIME_SUBSCRIBE_STATES.SUBSCRIBED) {
+                    dbg('subscribed');
+                    setConnected(true);
+                }
+                else if (status === REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR ||
+                    status === REALTIME_SUBSCRIBE_STATES.TIMED_OUT ||
+                    status === REALTIME_SUBSCRIBE_STATES.CLOSED) {
+                    // Don't try to recover — the backstop poll covers us. Surface in
+                    // debug so a network-blocked websocket is diagnosable.
+                    dbg(`channel ${status}; relying on backstop poll`);
+                    setConnected(false);
+                }
+            });
+            const activeClient = client;
+            return {
+                isConnected: () => connected,
+                async unsubscribe() {
+                    setConnected(false);
+                    try {
+                        await activeClient.removeChannel(channel);
+                        await activeClient.realtime.disconnect();
+                    }
+                    catch {
+                        /* best effort — process is exiting anyway */
+                    }
+                },
+            };
+        }
+        catch (error) {
+            dbg(`failed to subscribe: ${error instanceof Error ? error.message : String(error)}`);
+            // Best-effort cleanup of a half-built client, then degrade to polling.
+            try {
+                client?.realtime.disconnect();
+            }
+            catch {
+                /* ignore */
+            }
+            return { isConnected: () => false, async unsubscribe() { } };
+        }
+    }
+}

package/dist/gateways/supabase-gateway.d.ts

@@ -1,4 +1,4 @@
-import { type DcdEnvName } from '../config/environments';
+import { type DcdEnvName } from '../config/environments.js';
 /** Disk-backed upload descriptor — see UploadSource in src/methods.ts. */
 export interface ResumableUploadSource {
     contentType: string;

package/dist/gateways/supabase-gateway.js

@@ -1,11 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SupabaseGateway = void 0;
-const node_fs_1 = require("node:fs");
-const supabase_js_1 = require("@supabase/supabase-js");
-const tus = require("tus-js-client");
-const environments_1 = require("../config/environments");
-class SupabaseGateway {
+import { createReadStream } from 'node:fs';
+import { createClient } from '@supabase/supabase-js';
+import * as tus from 'tus-js-client';
+import { ENVIRONMENTS } from '../config/environments.js';
+export class SupabaseGateway {
     /**
      * Upload to Supabase using resumable uploads (TUS protocol)
      * Uploads to staging location (uploads/{id}/) using anon key
@@ -18,7 +15,7 @@ class SupabaseGateway {
      * @returns Promise that resolves when upload completes
      */
     static async uploadResumable(env, path, source, debug = false, onProgress) {
-        const { anonKey: SUPABASE_PUBLIC_KEY, projectRef } = environments_1.ENVIRONMENTS[env].supabase;
+        const { anonKey: SUPABASE_PUBLIC_KEY, projectRef } = ENVIRONMENTS[env].supabase;
         const storageUrl = `https://${projectRef}.storage.supabase.co`;
         if (debug) {
             console.log(`[DEBUG] Resumable upload starting...`);
@@ -31,7 +28,7 @@ class SupabaseGateway {
         return new Promise((resolve, reject) => {
             // Stream from disk — tus only buffers one chunk at a time. uploadSize
             // is required because a stream's length can't be derived.
-            const upload = new tus.Upload((0, node_fs_1.createReadStream)(source.diskPath), {
+            const upload = new tus.Upload(createReadStream(source.diskPath), {
                 uploadSize: source.size,
                 // TUS endpoint for Supabase Storage
                 endpoint: `${storageUrl}/storage/v1/upload/resumable`,
@@ -96,7 +93,7 @@ class SupabaseGateway {
         });
     }
     static async uploadToSignedUrl(env, path, token, file, debug = false) {
-        const { url: SUPABASE_URL, anonKey: SUPABASE_PUBLIC_KEY } = environments_1.ENVIRONMENTS[env].supabase;
+        const { url: SUPABASE_URL, anonKey: SUPABASE_PUBLIC_KEY } = ENVIRONMENTS[env].supabase;
         if (debug) {
             console.log(`[DEBUG] Supabase upload starting...`);
             console.log(`[DEBUG] Supabase URL: ${SUPABASE_URL}`);
@@ -105,7 +102,7 @@ class SupabaseGateway {
             console.log(`[DEBUG] File type: ${file.type}`);
         }
         try {
-            const supabase = (0, supabase_js_1.createClient)(SUPABASE_URL, SUPABASE_PUBLIC_KEY);
+            const supabase = createClient(SUPABASE_URL, SUPABASE_PUBLIC_KEY);
             const uploadToUrl = await supabase.storage
                 .from('organizations')
                 .uploadToSignedUrl(path, token, file);
@@ -131,7 +128,7 @@ class SupabaseGateway {
             }
             // Re-throw with additional context
             const errorMsg = error instanceof Error ? error.message : String(error);
-            throw new Error(`Supabase upload error: ${errorMsg}`);
+            throw new Error(`Supabase upload error: ${errorMsg}`, { cause: error });
         }
     }
     /**
@@ -187,4 +184,3 @@ class SupabaseGateway {
         }
     }
 }
-exports.SupabaseGateway = SupabaseGateway;

package/dist/index.js

@@ -1,38 +1,41 @@
 #!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const citty_1 = require("citty");
-const artifacts_1 = require("./commands/artifacts");
-const cloud_1 = require("./commands/cloud");
-const list_1 = require("./commands/list");
-const live_1 = require("./commands/live");
-const login_1 = require("./commands/login");
-const logout_1 = require("./commands/logout");
-const status_1 = require("./commands/status");
-const switch_org_1 = require("./commands/switch-org");
-const upgrade_1 = require("./commands/upgrade");
-const upload_1 = require("./commands/upload");
-const whoami_1 = require("./commands/whoami");
-const telemetry_service_1 = require("./services/telemetry.service");
-const cli_1 = require("./utils/cli");
-const main = (0, citty_1.defineCommand)({
+import { updateSettings } from '@clack/prompts';
+import { defineCommand, runCommand, showUsage } from 'citty';
+import { artifactsCommand } from './commands/artifacts.js';
+import { cloudCommand } from './commands/cloud.js';
+import { listCommand } from './commands/list.js';
+import { liveCommand } from './commands/live.js';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { statusCommand } from './commands/status.js';
+import { switchOrgCommand } from './commands/switch-org.js';
+import { upgradeCommand } from './commands/upgrade.js';
+import { uploadCommand } from './commands/upload.js';
+import { whoamiCommand } from './commands/whoami.js';
+import { telemetry } from './services/telemetry.service.js';
+import { CliError, getCliVersion, logger } from './utils/cli.js';
+// @clack/prompts ships the US spelling ("Canceled") for its built-in
+// spinner/prompt cancellation message; align it with the British spelling
+// ("Cancelled") used everywhere else in the CLI.
+updateSettings({ messages: { cancel: 'Cancelled' } });
+const main = defineCommand({
     meta: {
         name: 'dcd',
-        version: (0, cli_1.getCliVersion)(),
+        version: getCliVersion(),
         description: 'devicecloud.dev CLI — a drop-in replacement for `maestro cloud`',
     },
     subCommands: {
-        cloud: cloud_1.cloudCommand,
-        upload: upload_1.uploadCommand,
-        list: list_1.listCommand,
-        status: status_1.statusCommand,
-        artifacts: artifacts_1.artifactsCommand,
-        live: live_1.liveCommand,
-        login: login_1.loginCommand,
-        logout: logout_1.logoutCommand,
-        whoami: whoami_1.whoamiCommand,
-        'switch-org': switch_org_1.switchOrgCommand,
-        upgrade: upgrade_1.upgradeCommand,
+        cloud: cloudCommand,
+        upload: uploadCommand,
+        list: listCommand,
+        status: statusCommand,
+        artifacts: artifactsCommand,
+        live: liveCommand,
+        login: loginCommand,
+        logout: logoutCommand,
+        whoami: whoamiCommand,
+        'switch-org': switchOrgCommand,
+        upgrade: upgradeCommand,
     },
 });
 // citty's runMain catches every error internally and calls process.exit(1),
@@ -64,30 +67,30 @@ async function resolveSubCommand(cmd, rawArgs, parent) {
 }
 async function run() {
     const rawArgs = process.argv.slice(2);
-    telemetry_service_1.telemetry.recordCommandStart();
+    telemetry.recordCommandStart();
     try {
         if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
-            await (0, citty_1.showUsage)(...(await resolveSubCommand(main, rawArgs)));
+            await showUsage(...(await resolveSubCommand(main, rawArgs)));
         }
         else if (rawArgs.length === 1 && rawArgs[0] === '--version') {
-            cli_1.logger.log((0, cli_1.getCliVersion)());
+            logger.log(getCliVersion());
         }
         else {
-            await (0, citty_1.runCommand)(main, { rawArgs });
+            await runCommand(main, { rawArgs });
         }
-        telemetry_service_1.telemetry.recordCommandSuccess();
-        await telemetry_service_1.telemetry.flush();
+        telemetry.recordCommandSuccess();
+        await telemetry.flush();
     }
     catch (error) {
         // citty throws CLIError (by name — the class isn't exported) for usage
         // problems like unknown commands or missing required args.
         if (error instanceof Error && error.name === 'CLIError') {
-            await (0, citty_1.showUsage)(...(await resolveSubCommand(main, rawArgs)));
+            await showUsage(...(await resolveSubCommand(main, rawArgs)));
         }
-        const exitCode = error instanceof cli_1.CliError ? error.exitCode : 1;
+        const exitCode = error instanceof CliError ? error.exitCode : 1;
         // logger.error prints the message, records failure telemetry, flushes
         // synchronously, and exits with the given code.
-        cli_1.logger.error(error instanceof Error ? error : String(error), {
+        logger.error(error instanceof Error ? error : String(error), {
             exit: exitCode,
         });
     }

package/dist/mcp/context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-process MCP context: a single resolved AuthContext + API URL, plus the
+ * stderr logger every tool must use.
+ *
+ * stdio transport reserves **stdout** for the JSON-RPC frame stream — anything
+ * a tool prints there corrupts the protocol. Tools therefore call the services
+ * with `logStderr` (never the `utils/cli` `logger`, which writes to stdout and
+ * can `process.exit`).
+ */
+import type { AuthContext } from '../types/domain/auth.types.js';
+/** Write a line to stderr. Safe under stdio transport; stdout is reserved. */
+export declare function logStderr(message: string): void;
+export interface McpContext {
+    apiUrl: string;
+    auth: AuthContext;
+}
+/**
+ * Resolve auth + API URL once per process, lazily on first tool invocation.
+ *
+ * Lazy so `initialize` / `tools/list` succeed before the user has supplied a
+ * credential (clients enumerate tools on connect), and so an auth failure
+ * surfaces as a tool error rather than crashing the server at boot.
+ *
+ * Precedence matches the CLI: `DEVICE_CLOUD_API_KEY` env > stored `dcd login`
+ * session. The API URL honors `DCD_API_URL` (handy for pointing the server at
+ * dev/staging), then the logged-in env, then the prod default.
+ */
+export declare function getContext(): Promise<McpContext>;
+/**
+ * Read-only mode hides the only state-changing / billable tool
+ * (`dcd_run_cloud_test`). Recommended for autonomous or untrusted agents.
+ */
+export declare function isReadOnly(): boolean;

package/dist/mcp/context.js

@@ -0,0 +1,33 @@
+import { resolveAuth } from '../utils/auth.js';
+import { resolveApiUrl } from '../utils/config-store.js';
+/** Write a line to stderr. Safe under stdio transport; stdout is reserved. */
+export function logStderr(message) {
+    process.stderr.write(`${message}\n`);
+}
+let cached = null;
+/**
+ * Resolve auth + API URL once per process, lazily on first tool invocation.
+ *
+ * Lazy so `initialize` / `tools/list` succeed before the user has supplied a
+ * credential (clients enumerate tools on connect), and so an auth failure
+ * surfaces as a tool error rather than crashing the server at boot.
+ *
+ * Precedence matches the CLI: `DEVICE_CLOUD_API_KEY` env > stored `dcd login`
+ * session. The API URL honors `DCD_API_URL` (handy for pointing the server at
+ * dev/staging), then the logged-in env, then the prod default.
+ */
+export async function getContext() {
+    if (cached)
+        return cached;
+    const auth = await resolveAuth({ apiKeyFlag: undefined });
+    const apiUrl = resolveApiUrl(process.env.DCD_API_URL);
+    cached = { apiUrl, auth };
+    return cached;
+}
+/**
+ * Read-only mode hides the only state-changing / billable tool
+ * (`dcd_run_cloud_test`). Recommended for autonomous or untrusted agents.
+ */
+export function isReadOnly() {
+    return (process.env.DCD_MCP_READONLY === '1' || process.argv.includes('--read-only'));
+}

package/dist/mcp/helpers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared tool plumbing: structured results and a wrapper that records
+ * telemetry and converts any thrown error into an `isError` tool result (so a
+ * single failing tool never tears down the long-lived server).
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** A tool result whose text payload is pretty-printed JSON. */
+export declare function jsonResult(data: unknown): CallToolResult;
+/** An error tool result the model can read and react to. */
+export declare function errorResult(message: string): CallToolResult;
+/**
+ * Wrap a tool handler: emit start/success/failure telemetry, flush it
+ * (fire-and-forget — the process outlives the call), and translate thrown
+ * errors into an `isError` result instead of rejecting.
+ */
+export declare function runTool(name: string, fn: () => Promise<CallToolResult>): Promise<CallToolResult>;

package/dist/mcp/helpers.js

@@ -0,0 +1,34 @@
+import { telemetry } from '../services/telemetry.service.js';
+/** A tool result whose text payload is pretty-printed JSON. */
+export function jsonResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** An error tool result the model can read and react to. */
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+/**
+ * Wrap a tool handler: emit start/success/failure telemetry, flush it
+ * (fire-and-forget — the process outlives the call), and translate thrown
+ * errors into an `isError` result instead of rejecting.
+ */
+export async function runTool(name, fn) {
+    const start = Date.now();
+    telemetry.recordMcpToolStart(name);
+    try {
+        const result = await fn();
+        telemetry.recordMcpToolSuccess(name, Date.now() - start);
+        void telemetry.flush();
+        return result;
+    }
+    catch (error) {
+        telemetry.recordMcpToolFailure(name, error, Date.now() - start);
+        void telemetry.flush();
+        return errorResult(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/mcp/index.d.ts

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

package/dist/mcp/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * devicecloud.dev MCP server (stdio transport).
+ *
+ * Exposes the CLI's service layer to MCP clients (Claude, Cursor, …) as tools.
+ * Auth is inherited from the CLI: `DEVICE_CLOUD_API_KEY` env or a stored
+ * `dcd login` session (see src/mcp/context.ts). All diagnostics go to stderr —
+ * stdout carries only JSON-RPC frames.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { telemetry } from '../services/telemetry.service.js';
+import { isReadOnly, logStderr } from './context.js';
+import { createServer } from './server.js';
+async function main() {
+    telemetry.setCommand('mcp');
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logStderr(`devicecloud.dev MCP server running on stdio${isReadOnly() ? ' (read-only)' : ''}`);
+}
+main().catch((error) => {
+    logStderr(`Fatal: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Build the devicecloud.dev MCP server with its tool set registered. Read-only
+ * tools are always present; the billable `dcd_run_cloud_test` is omitted in
+ * read-only mode (`DCD_MCP_READONLY=1` or `--read-only`).
+ */
+export declare function createServer(): McpServer;