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

package/README.md

@@ -1,16 +1,29 @@
 # devicecloud.dev CLI
 
-
 ---
 
 One line swap out for Maestro Cloud
 
-Install:
+Install (no Node required):
+
+```sh-session
+$ curl -fsSL https://get.devicecloud.dev/install.sh | sh
+```
+
+On Windows:
+
+```powershell
+irm https://get.devicecloud.dev/install.ps1 | iex
+```
+
+Or via npm if you already have Node 22+:
 
 ```sh-session
 $ npm install -g @devicecloud.dev/dcd
 ```
 
+Upgrade later with `dcd upgrade` (binary install) or `npm install -g @devicecloud.dev/dcd@latest` (npm install).
+
 Use:
 
 ```sh-session
@@ -19,3 +32,63 @@ $ dcd cloud --apiKey <apiKey> <appFile> .myFlows/
 ```
 
 See full documentation: [Docs](https://docs.devicecloud.dev)
+
+
+## MCP server
+
+The same npm package ships an [MCP](https://modelcontextprotocol.io) server (`dcd-mcp` bin) so AI agents — Claude, Cursor, VS Code — can drive devicecloud.dev directly.
+
+Add it to your MCP client config:
+
+```jsonc
+{
+  "mcpServers": {
+    "devicecloud": {
+      "command": "npx",
+      "args": ["-y", "@devicecloud.dev/dcd", "dcd-mcp"],
+      "env": { "DEVICE_CLOUD_API_KEY": "<your-api-key>" }
+    }
+  }
+}
+```
+
+Auth is inherited from the CLI: set `DEVICE_CLOUD_API_KEY` as above, or run `dcd login` once and the server picks up the stored session. Point it at a non-prod environment with `DCD_API_URL`.
+
+**Tools**
+
+| Tool | What it does |
+| --- | --- |
+| `dcd_list_devices` | Discover available devices, OS versions, and Maestro versions |
+| `dcd_list_runs` | List recent test runs (filter by name/date, paginated) |
+| `dcd_get_status` | Get the status + per-test results of a run |
+| `dcd_download_artifacts` | Download a run's artifacts/report to disk |
+| `dcd_run_cloud_test` | Submit a flow to run on the cloud (**billable**) |
+
+**Read-only mode.** `dcd_run_cloud_test` consumes test minutes, so it is annotated as non-read-only/destructive (clients can prompt before calling it). To hide it entirely — recommended for autonomous or untrusted agents — pass `--read-only` in `args`, or set `DCD_MCP_READONLY=1` in `env`.
+
+By default `dcd_run_cloud_test` is async: it returns an `uploadId` immediately, which you poll with `dcd_get_status`. Pass `wait: true` (bounded by `waitTimeoutSeconds`) to block until completion, or `dryRun: true` to preview the flows without submitting.
+
+
+## Development
+
+Requires Node 22+ and [pnpm](https://pnpm.io). `pnpm install` builds the CLI and installs the git hooks automatically.
+
+```sh-session
+$ pnpm install        # install deps, build, set up git hooks
+$ pnpm dcd <args>     # run the CLI from source
+$ pnpm lint           # ESLint
+$ pnpm typecheck      # strict tsc, no emit
+$ pnpm test           # build + boot mock API + integration/unit tests
+```
+
+### Secret scanning
+
+A [gitleaks](https://github.com/gitleaks/gitleaks) scan runs in two places, both sharing the allowlist in `.gitleaks.toml`:
+
+- **pre-commit hook** (via husky) — scans your staged changes and blocks the commit if a secret is found. Install the binary so it can run; without it the hook skips with a warning:
+  ```sh-session
+  $ brew install gitleaks      # or see github.com/gitleaks/gitleaks#installing
+  ```
+- **CI** — the `secret-scan` job scans the full history on every push and pull request, and is the enforced backstop regardless of local setup.
+
+

package/dist/commands/artifacts.d.ts

@@ -1,18 +1,47 @@
-import { Command } from '@oclif/core';
-export default class Artifacts extends Command {
-    static description: string;
-    static examples: string[];
-    static flags: {
-        apiKey: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        apiUrl: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        debug: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
-        'upload-id': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'download-artifacts': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'artifacts-path': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        report: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'allure-path': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'html-path': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'junit-path': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
-    };
-    run(): Promise<void>;
-}
+export declare const artifactsCommand: import("citty").CommandDef<{
+    readonly debug: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Enable detailed debug logging for troubleshooting issues";
+    };
+    readonly 'upload-id': {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "UUID of the completed upload to download artifacts for";
+    };
+    readonly 'download-artifacts': {
+        readonly type: "string";
+        readonly description: "Download a zip containing the logs, screenshots and videos for this run (options: ALL, FAILED)";
+    };
+    readonly 'artifacts-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded artifacts (default: ./artifacts.zip). Requires --download-artifacts.";
+    };
+    readonly report: {
+        readonly type: "string";
+        readonly description: "Download a test report in the specified format (options: allure, html, html-detailed, junit)";
+    };
+    readonly 'allure-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded Allure report (default: ./report.html)";
+    };
+    readonly 'html-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded HTML report (default: ./report.html)";
+    };
+    readonly 'junit-path': {
+        readonly type: "string";
+        readonly description: "Custom file path for downloaded JUnit report (default: ./report.xml)";
+    };
+    readonly 'api-key': {
+        readonly type: "string";
+        readonly alias: ["apiKey"];
+        readonly description: "API key for devicecloud.dev (find this in the console UI). You can also set the DEVICE_CLOUD_API_KEY environment variable.";
+    };
+    readonly 'api-url': {
+        readonly type: "string";
+        readonly alias: ["apiURL", "apiUrl"];
+        readonly description: "API base URL (defaults to the URL stored by `dcd login`, else prod)";
+    };
+}>;
+export default artifactsCommand;

package/dist/commands/artifacts.js

@@ -1,93 +1,98 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const core_1 = require("@oclif/core");
-const constants_1 = require("../constants");
-const report_download_service_1 = require("../services/report-download.service");
-class Artifacts extends core_1.Command {
-    static description = 'Download artifacts or reports for a completed test run';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> --upload-id 123e4567-e89b-12d3-a456-426614174000 --download-artifacts FAILED',
-        '<%= config.bin %> <%= command.id %> --upload-id 123e4567-e89b-12d3-a456-426614174000 --download-artifacts ALL --artifacts-path ./my-artifacts.zip',
-        '<%= config.bin %> <%= command.id %> --upload-id 123e4567-e89b-12d3-a456-426614174000 --report junit',
-        '<%= config.bin %> <%= command.id %> --upload-id 123e4567-e89b-12d3-a456-426614174000 --report allure --allure-path ./report.html',
-    ];
-    static flags = {
-        apiKey: constants_1.flags.apiKey,
-        apiUrl: constants_1.flags.apiUrl,
-        debug: core_1.Flags.boolean({
+import { defineCommand } from 'citty';
+import { apiFlags } from '../config/flags/api.flags.js';
+import { ReportDownloadService } from '../services/report-download.service.js';
+import { resolveAuth } from '../utils/auth.js';
+import { CliError, logger, validateEnum } from '../utils/cli.js';
+import { resolveApiUrl } from '../utils/config-store.js';
+const DOWNLOAD_OPTIONS = ['ALL', 'FAILED'];
+const REPORT_OPTIONS = ['allure', 'html', 'html-detailed', 'junit'];
+export const artifactsCommand = defineCommand({
+    meta: {
+        name: 'artifacts',
+        description: 'Download artifacts or reports for a completed test run',
+    },
+    args: {
+        ...apiFlags,
+        debug: {
+            type: 'boolean',
             default: false,
             description: 'Enable detailed debug logging for troubleshooting issues',
-        }),
-        'upload-id': core_1.Flags.string({
-            description: 'UUID of the completed upload to download artifacts for',
+        },
+        'upload-id': {
+            type: 'string',
             required: true,
-        }),
-        'download-artifacts': core_1.Flags.string({
-            description: 'Download a zip containing the logs, screenshots and videos for this run. Options: ALL (everything), FAILED (failures only).',
-            exclusive: ['report'],
-            options: ['ALL', 'FAILED'],
-        }),
-        'artifacts-path': core_1.Flags.string({
-            dependsOn: ['download-artifacts'],
-            description: 'Custom file path for downloaded artifacts (default: ./artifacts.zip)',
-        }),
-        report: core_1.Flags.string({
-            description: 'Download a test report in the specified format.',
-            exclusive: ['download-artifacts'],
-            options: ['allure', 'html', 'html-detailed', 'junit'],
-        }),
-        'allure-path': core_1.Flags.string({
-            dependsOn: ['report'],
+            description: 'UUID of the completed upload to download artifacts for',
+        },
+        'download-artifacts': {
+            type: 'string',
+            description: 'Download a zip containing the logs, screenshots and videos for this run (options: ALL, FAILED)',
+        },
+        'artifacts-path': {
+            type: 'string',
+            description: 'Custom file path for downloaded artifacts (default: ./artifacts.zip). Requires --download-artifacts.',
+        },
+        report: {
+            type: 'string',
+            description: 'Download a test report in the specified format (options: allure, html, html-detailed, junit)',
+        },
+        'allure-path': {
+            type: 'string',
             description: 'Custom file path for downloaded Allure report (default: ./report.html)',
-        }),
-        'html-path': core_1.Flags.string({
-            dependsOn: ['report'],
+        },
+        'html-path': {
+            type: 'string',
             description: 'Custom file path for downloaded HTML report (default: ./report.html)',
-        }),
-        'junit-path': core_1.Flags.string({
-            dependsOn: ['report'],
+        },
+        'junit-path': {
+            type: 'string',
             description: 'Custom file path for downloaded JUnit report (default: ./report.xml)',
-        }),
-    };
-    async run() {
-        const { flags } = await this.parse(Artifacts);
-        const { apiKey: apiKeyFlag, apiUrl, debug, 'upload-id': uploadId, 'download-artifacts': downloadArtifacts, 'artifacts-path': artifactsPath, report, 'allure-path': allurePath, 'html-path': htmlPath, 'junit-path': junitPath, } = flags;
-        const apiKey = apiKeyFlag || process.env.DEVICE_CLOUD_API_KEY;
-        if (!apiKey) {
-            this.error('API key is required. Please provide it via --api-key flag or DEVICE_CLOUD_API_KEY environment variable.');
-            return;
+        },
+    },
+    async run({ args }) {
+        const apiKeyFlag = args['api-key'];
+        const apiUrl = resolveApiUrl(args['api-url']);
+        const debug = Boolean(args.debug);
+        const uploadId = args['upload-id'];
+        const downloadArtifacts = validateEnum(args['download-artifacts'], DOWNLOAD_OPTIONS, 'download-artifacts');
+        const artifactsPath = args['artifacts-path'];
+        const report = validateEnum(args.report, REPORT_OPTIONS, 'report');
+        const allurePath = args['allure-path'];
+        const htmlPath = args['html-path'];
+        const junitPath = args['junit-path'];
+        const auth = await resolveAuth({ apiKeyFlag });
+        if (downloadArtifacts && report) {
+            throw new CliError('--download-artifacts cannot also be provided when using --report (flags are mutually exclusive).');
         }
         if (!downloadArtifacts && !report) {
-            this.error('Either --download-artifacts or --report must be specified.');
-            return;
+            throw new CliError('Either --download-artifacts or --report must be specified.');
         }
-        const service = new report_download_service_1.ReportDownloadService();
+        const service = new ReportDownloadService();
         if (downloadArtifacts) {
             await service.downloadArtifacts({
-                apiKey,
+                auth,
                 apiUrl,
                 artifactsPath: artifactsPath ?? './artifacts.zip',
                 debug,
                 downloadType: downloadArtifacts,
-                logger: this.log.bind(this),
+                logger: (m) => logger.log(m),
                 uploadId,
-                warnLogger: this.warn.bind(this),
+                warnLogger: (m) => logger.warn(m),
             });
         }
         if (report) {
             await service.downloadReports({
                 allurePath,
-                apiKey,
+                auth,
                 apiUrl,
                 debug,
                 htmlPath,
                 junitPath,
-                logger: this.log.bind(this),
+                logger: (m) => logger.log(m),
                 reportType: report,
                 uploadId,
-                warnLogger: this.warn.bind(this),
+                warnLogger: (m) => logger.warn(m),
             });
         }
-    }
-}
-exports.default = Artifacts;
+    },
+});
+export default artifactsCommand;