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

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

@@ -0,0 +1,54 @@
+/**
+ * Supabase session operations for the CLI: refresh an expired access token
+ * and sign-out (best-effort revocation on the Supabase side).
+ *
+ * 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.
+ */
+import { createClient } from '@supabase/supabase-js';
+function client(supabaseUrl, supabaseAnonKey) {
+    return createClient(supabaseUrl, supabaseAnonKey, {
+        auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+    });
+}
+export const CliAuthGateway = {
+    async refresh(supabaseUrl, supabaseAnonKey, session) {
+        const sb = client(supabaseUrl, supabaseAnonKey);
+        const { data, error } = await sb.auth.refreshSession({
+            refresh_token: session.refresh_token,
+        });
+        if (error || !data.session || !data.user) {
+            throw new Error(`Failed to refresh session: ${error?.message ?? 'no session returned'}. ` +
+                `Run \`dcd login\` again.`);
+        }
+        const s = data.session;
+        const u = data.user;
+        if (!s.expires_at)
+            throw new Error('Refreshed session is missing expires_at');
+        return {
+            access_token: s.access_token,
+            refresh_token: s.refresh_token,
+            expires_at: s.expires_at,
+            user_email: u.email ?? session.user_email,
+            user_id: u.id,
+        };
+    },
+    async signOut(supabaseUrl, supabaseAnonKey, session) {
+        // `scope: 'local'` clears this client's SDK state only — no server call,
+        // no revocation. supabase-js defaults to `scope: 'global'`, which revokes
+        // EVERY session for the user (browser, mobile, other CLIs), so
+        // `dcd logout` would kick the user out of the web app. We don't want
+        // that — logging out locally should be local.
+        const sb = client(supabaseUrl, supabaseAnonKey);
+        try {
+            await sb.auth.setSession({
+                access_token: session.access_token,
+                refresh_token: session.refresh_token,
+            });
+            await sb.auth.signOut({ scope: 'local' });
+        }
+        catch {
+            // Best effort — the local config will be wiped regardless.
+        }
+    },
+};

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,25 +1,25 @@
+import { type DcdEnvName } from '../config/environments.js';
+/** Disk-backed upload descriptor — see UploadSource in src/methods.ts. */
+export interface ResumableUploadSource {
+    contentType: string;
+    diskPath: string;
+    name: string;
+    size: number;
+}
 export declare class SupabaseGateway {
-    private static SB;
-    static getSupabaseKeys(env: 'dev' | 'prod'): {
-        SUPABASE_PUBLIC_KEY: string;
-        SUPABASE_URL: string;
-    } | {
-        SUPABASE_PUBLIC_KEY: string;
-        SUPABASE_URL: string;
-    };
     /**
      * Upload to Supabase using resumable uploads (TUS protocol)
      * Uploads to staging location (uploads/{id}/) using anon key
      * File is later moved to final location by API after finalization
      * @param env - Environment (dev or prod)
      * @param path - Staging storage path (uploads/{id}/file.ext)
-     * @param file - File to upload
+     * @param source - Upload source descriptor; the file is streamed from disk
      * @param debug - Enable debug logging
      * @param onProgress - Optional callback for upload progress (bytesUploaded, bytesTotal)
      * @returns Promise that resolves when upload completes
      */
-    static uploadResumable(env: 'dev' | 'prod', path: string, file: File, debug?: boolean, onProgress?: (bytesUploaded: number, bytesTotal: number) => void): Promise<void>;
-    static uploadToSignedUrl(env: 'dev' | 'prod', path: string, token: string, file: File, debug?: boolean): Promise<void>;
+    static uploadResumable(env: DcdEnvName, path: string, source: ResumableUploadSource, debug?: boolean, onProgress?: (bytesUploaded: number, bytesTotal: number) => void): Promise<void>;
+    static uploadToSignedUrl(env: DcdEnvName, path: string, token: string, file: File, debug?: boolean): Promise<void>;
     /**
      * Logs network error details for debugging
      * @param error - Error object to analyze for network-related issues

package/dist/gateways/supabase-gateway.js

@@ -1,62 +1,35 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SupabaseGateway = void 0;
-const supabase_js_1 = require("@supabase/supabase-js");
-const tus = require("tus-js-client");
-class SupabaseGateway {
-    static SB = {
-        dev: {
-            SUPABASE_PUBLIC_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxibXNvd2VodGp3bnFsdXJwZW1iIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MDkyMTg0ODcsImV4cCI6MjAyNDc5NDQ4N30.zeLTMAuZ_WwYvGdeP0kdvL_Zrs-RQee5APPyxmWq7qQ',
-            SUPABASE_URL: 'https://lbmsowehtjwnqlurpemb.supabase.co',
-        },
-        prod: {
-            SUPABASE_PUBLIC_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InBneWRucGhiaW1ldGluc2dma2JvIiwicm9sZSI6ImFub24iLCJpYXQiOjE3MDc1OTQzNDYsImV4cCI6MjAyMzE3MDM0Nn0.hAYOMFxxwX1exkQkY9xyQJGC_GhGnyogkj2N-kBkMI8',
-            SUPABASE_URL: 'https://cloud.devicecloud.dev',
-        },
-    };
-    static getSupabaseKeys(env) {
-        return this.SB[env];
-    }
+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
      * File is later moved to final location by API after finalization
      * @param env - Environment (dev or prod)
      * @param path - Staging storage path (uploads/{id}/file.ext)
-     * @param file - File to upload
+     * @param source - Upload source descriptor; the file is streamed from disk
      * @param debug - Enable debug logging
      * @param onProgress - Optional callback for upload progress (bytesUploaded, bytesTotal)
      * @returns Promise that resolves when upload completes
      */
-    static async uploadResumable(env, path, file, debug = false, onProgress) {
-        const { SUPABASE_PUBLIC_KEY, SUPABASE_URL } = this.getSupabaseKeys(env);
-        // Extract project ID from Supabase URL for the storage endpoint
-        // Format: https://project-id.supabase.co or https://cloud.devicecloud.dev (custom domain)
-        let projectId;
-        if (SUPABASE_URL.includes('.supabase.co')) {
-            projectId = SUPABASE_URL.replace('https://', '').split('.')[0];
-        }
-        else {
-            // For custom domains like cloud.devicecloud.dev, we need the project ref
-            // This is the dev environment project ref
-            projectId = env === 'dev' ? 'lbmsowehtjwnqlurpemb' : 'pgydnphbimetinsgfkbo';
-        }
-        const storageUrl = `https://${projectId}.storage.supabase.co`;
+    static async uploadResumable(env, path, source, debug = false, onProgress) {
+        const { anonKey: SUPABASE_PUBLIC_KEY, projectRef } = ENVIRONMENTS[env].supabase;
+        const storageUrl = `https://${projectRef}.storage.supabase.co`;
         if (debug) {
             console.log(`[DEBUG] Resumable upload starting...`);
             console.log(`[DEBUG] Storage URL: ${storageUrl}`);
             console.log(`[DEBUG] Upload path: ${path}`);
-            console.log(`[DEBUG] File name: ${file.name}`);
-            console.log(`[DEBUG] File size: ${(file.size / 1024 / 1024).toFixed(2)} MB`);
-        }
-        // Convert File to Buffer for Node.js tus-js-client
-        // In Node.js environment, tus-js-client expects Buffer or Readable stream, not File
-        const fileBuffer = Buffer.from(await file.arrayBuffer());
-        if (debug) {
-            console.log(`[DEBUG] Converted File to Buffer (${fileBuffer.length} bytes)`);
+            console.log(`[DEBUG] File name: ${source.name}`);
+            console.log(`[DEBUG] File size: ${(source.size / 1024 / 1024).toFixed(2)} MB`);
+            console.log(`[DEBUG] Streaming from disk: ${source.diskPath}`);
         }
         return new Promise((resolve, reject) => {
-            const upload = new tus.Upload(fileBuffer, {
+            // 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(createReadStream(source.diskPath), {
+                uploadSize: source.size,
                 // TUS endpoint for Supabase Storage
                 endpoint: `${storageUrl}/storage/v1/upload/resumable`,
                 // Retry configuration - will retry 5 times with increasing delays
@@ -71,7 +44,7 @@ class SupabaseGateway {
                 metadata: {
                     bucketName: 'organizations',
                     objectName: path,
-                    contentType: file.type || 'application/octet-stream',
+                    contentType: source.contentType || 'application/octet-stream',
                     cacheControl: '3600',
                 },
                 // Chunk size must be 6MB for Supabase
@@ -120,7 +93,7 @@ class SupabaseGateway {
         });
     }
     static async uploadToSignedUrl(env, path, token, file, debug = false) {
-        const { SUPABASE_PUBLIC_KEY, SUPABASE_URL } = this.getSupabaseKeys(env);
+        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}`);
@@ -129,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);
@@ -155,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 });
         }
     }
     /**
@@ -211,4 +184,3 @@ class SupabaseGateway {
         }
     }
 }
-exports.SupabaseGateway = SupabaseGateway;

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { run } from '@oclif/core';
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -1,4 +1,98 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-var core_1 = require("@oclif/core");
-Object.defineProperty(exports, "run", { enumerable: true, get: function () { return core_1.run; } });
+#!/usr/bin/env node
+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: getCliVersion(),
+        description: 'devicecloud.dev CLI — a drop-in replacement for `maestro cloud`',
+    },
+    subCommands: {
+        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),
+// so its returned promise never rejects — failure telemetry hooked onto it
+// would be dead code, CliError.exitCode would be ignored, and raw stack
+// traces would be printed for usage errors. This replicates runMain's
+// help/version/usage behaviour with those three problems fixed. Telemetry
+// configure is deferred to `resolveAuth` (only authenticated commands ship
+// telemetry — see telemetry.service.ts); unauthenticated invocations buffer
+// in memory and drop on exit, which is the desired behaviour.
+async function resolveValue(input) {
+    return typeof input === 'function'
+        ? input()
+        : input;
+}
+// Mirrors citty's internal (unexported) resolveSubCommand so usage errors can
+// show the help of the subcommand that failed rather than the root command.
+async function resolveSubCommand(cmd, rawArgs, parent) {
+    const subCommands = await resolveValue(cmd.subCommands);
+    if (subCommands && Object.keys(subCommands).length > 0) {
+        const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith('-'));
+        const subCommandName = rawArgs[subCommandArgIndex];
+        const subCommand = await resolveValue(subCommands[subCommandName]);
+        if (subCommand) {
+            return resolveSubCommand(subCommand, rawArgs.slice(subCommandArgIndex + 1), cmd);
+        }
+    }
+    return [cmd, parent];
+}
+async function run() {
+    const rawArgs = process.argv.slice(2);
+    telemetry.recordCommandStart();
+    try {
+        if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+            await showUsage(...(await resolveSubCommand(main, rawArgs)));
+        }
+        else if (rawArgs.length === 1 && rawArgs[0] === '--version') {
+            logger.log(getCliVersion());
+        }
+        else {
+            await runCommand(main, { rawArgs });
+        }
+        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 showUsage(...(await resolveSubCommand(main, rawArgs)));
+        }
+        const exitCode = error instanceof CliError ? error.exitCode : 1;
+        // logger.error prints the message, records failure telemetry, flushes
+        // synchronously, and exits with the given code.
+        logger.error(error instanceof Error ? error : String(error), {
+            exit: exitCode,
+        });
+    }
+}
+void run();

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;

package/dist/mcp/server.js

@@ -0,0 +1,27 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getCliVersion } from '../utils/cli.js';
+import { isReadOnly } from './context.js';
+import { registerDownloadArtifacts } from './tools/download-artifacts.js';
+import { registerGetStatus } from './tools/get-status.js';
+import { registerListDevices } from './tools/list-devices.js';
+import { registerListRuns } from './tools/list-runs.js';
+import { registerRunCloudTest } from './tools/run-cloud-test.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 function createServer() {
+    const server = new McpServer({
+        name: 'devicecloud',
+        version: getCliVersion(),
+    });
+    registerListDevices(server);
+    registerListRuns(server);
+    registerGetStatus(server);
+    registerDownloadArtifacts(server);
+    if (!isReadOnly()) {
+        registerRunCloudTest(server);
+    }
+    return server;
+}

package/dist/mcp/tools/download-artifacts.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Download a completed run's artifacts (zip) and/or a formatted report to local
+ * disk. This reads cloud state and writes files locally — it does not change
+ * anything cloud-side, so it stays available in read-only mode.
+ *
+ * The underlying service swallows download failures into `warnLogger` rather
+ * than throwing (a missing-artifacts 404 isn't fatal), so we collect those
+ * warnings and return them — an empty `warnings` array means success.
+ */
+export declare function registerDownloadArtifacts(server: McpServer): void;