donobu 5.23.0 → 5.25.0

package/dist/apis/SuitesApi.d.ts

@@ -0,0 +1,36 @@
+import type { Request, Response } from 'express';
+import type { SuitesManager } from '../managers/SuitesManager';
+import type { TestsManager } from '../managers/TestsManager';
+/**
+ * API controller for managing suites.
+ */
+export declare class SuitesApi {
+    private readonly suitesManager;
+    private readonly testsManager;
+    constructor(suitesManager: SuitesManager, testsManager: TestsManager);
+    /**
+     * GET /api/suites — list suites with optional filtering and pagination.
+     */
+    getSuites(req: Request, res: Response): Promise<void>;
+    /**
+     * POST /api/suites — create a new suite.
+     */
+    createSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * GET /api/suites/:suiteId — get a suite by ID.
+     */
+    getSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * PUT /api/suites/:suiteId — update an existing suite.
+     */
+    updateSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * DELETE /api/suites/:suiteId — delete a suite (tests are orphaned).
+     */
+    deleteSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * GET /api/suites/:suiteId/tests — list tests in a suite.
+     */
+    getSuiteTests(req: Request, res: Response): Promise<void>;
+}
+//# sourceMappingURL=SuitesApi.d.ts.map

package/dist/apis/SuitesApi.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SuitesApi = void 0;
+const CreateSuite_1 = require("../models/CreateSuite");
+const SuiteMetadata_1 = require("../models/SuiteMetadata");
+/**
+ * API controller for managing suites.
+ */
+class SuitesApi {
+    constructor(suitesManager, testsManager) {
+        this.suitesManager = suitesManager;
+        this.testsManager = testsManager;
+    }
+    /**
+     * GET /api/suites — list suites with optional filtering and pagination.
+     */
+    async getSuites(req, res) {
+        const query = SuiteMetadata_1.SuitesQuerySchema.parse(req.query);
+        const result = await this.suitesManager.getSuites(query);
+        res.json({ suites: result.items, nextPageToken: result.nextPageToken });
+    }
+    /**
+     * POST /api/suites — create a new suite.
+     */
+    async createSuite(req, res) {
+        const params = CreateSuite_1.CreateSuiteSchema.parse(req.body);
+        const suite = await this.suitesManager.createSuite(params);
+        res.json(suite);
+    }
+    /**
+     * GET /api/suites/:suiteId — get a suite by ID.
+     */
+    async getSuite(req, res) {
+        const suiteId = String(req.params.suiteId);
+        const suite = await this.suitesManager.getSuiteById(suiteId);
+        res.json(suite);
+    }
+    /**
+     * PUT /api/suites/:suiteId — update an existing suite.
+     */
+    async updateSuite(req, res) {
+        const suiteId = String(req.params.suiteId);
+        const suiteMetadata = SuiteMetadata_1.SuiteMetadataSchema.parse({
+            ...req.body,
+            id: suiteId,
+        });
+        await this.suitesManager.updateSuite(suiteMetadata);
+        res.json(suiteMetadata);
+    }
+    /**
+     * DELETE /api/suites/:suiteId — delete a suite (tests are orphaned).
+     */
+    async deleteSuite(req, res) {
+        const suiteId = String(req.params.suiteId);
+        await this.suitesManager.deleteSuite(suiteId);
+        res.status(200).json({ deleted: true });
+    }
+    /**
+     * GET /api/suites/:suiteId/tests — list tests in a suite.
+     */
+    async getSuiteTests(req, res) {
+        const suiteId = String(req.params.suiteId);
+        const result = await this.testsManager.getTests({ suiteId });
+        res.json({ tests: result.items, nextPageToken: result.nextPageToken });
+    }
+}
+exports.SuitesApi = SuitesApi;
+//# sourceMappingURL=SuitesApi.js.map

package/dist/apis/TestsApi.d.ts

@@ -0,0 +1,40 @@
+import type { Request, Response } from 'express';
+import type { DonobuFlowsManager } from '../managers/DonobuFlowsManager';
+import type { TestsManager } from '../managers/TestsManager';
+/**
+ * API controller for managing tests.
+ */
+export declare class TestsApi {
+    private readonly testsManager;
+    private readonly flowsManager;
+    constructor(testsManager: TestsManager, flowsManager: DonobuFlowsManager);
+    /**
+     * GET /api/tests — list tests with optional filtering and pagination.
+     */
+    getTests(req: Request, res: Response): Promise<void>;
+    /**
+     * POST /api/tests — create a new test.
+     */
+    createTest(req: Request, res: Response): Promise<void>;
+    /**
+     * GET /api/tests/:testId — get a test by ID.
+     */
+    getTest(req: Request, res: Response): Promise<void>;
+    /**
+     * PUT /api/tests/:testId — update an existing test.
+     */
+    updateTest(req: Request, res: Response): Promise<void>;
+    /**
+     * DELETE /api/tests/:testId — delete a test and all its flows.
+     */
+    deleteTest(req: Request, res: Response): Promise<void>;
+    /**
+     * GET /api/tests/:testId/flows — list flows for a test.
+     */
+    getTestFlows(req: Request, res: Response): Promise<void>;
+    /**
+     * POST /api/tests/:testId/run — execute a test (create a new flow from it).
+     */
+    runTest(req: Request, res: Response): Promise<void>;
+}
+//# sourceMappingURL=TestsApi.d.ts.map

package/dist/apis/TestsApi.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestsApi = void 0;
+const CreateTest_1 = require("../models/CreateTest");
+const TestMetadata_1 = require("../models/TestMetadata");
+/**
+ * API controller for managing tests.
+ */
+class TestsApi {
+    constructor(testsManager, flowsManager) {
+        this.testsManager = testsManager;
+        this.flowsManager = flowsManager;
+    }
+    /**
+     * GET /api/tests — list tests with optional filtering and pagination.
+     */
+    async getTests(req, res) {
+        const query = TestMetadata_1.TestsQuerySchema.parse(req.query);
+        const result = await this.testsManager.getTests(query);
+        res.json({ tests: result.items, nextPageToken: result.nextPageToken });
+    }
+    /**
+     * POST /api/tests — create a new test.
+     */
+    async createTest(req, res) {
+        const params = CreateTest_1.CreateTestSchema.parse(req.body);
+        const test = await this.testsManager.createTest(params);
+        res.json(test);
+    }
+    /**
+     * GET /api/tests/:testId — get a test by ID.
+     */
+    async getTest(req, res) {
+        const testId = String(req.params.testId);
+        const test = await this.testsManager.getTestById(testId);
+        res.json(test);
+    }
+    /**
+     * PUT /api/tests/:testId — update an existing test.
+     */
+    async updateTest(req, res) {
+        const testId = String(req.params.testId);
+        const testMetadata = TestMetadata_1.TestMetadataSchema.parse({
+            ...req.body,
+            id: testId,
+        });
+        await this.testsManager.updateTest(testMetadata);
+        res.json(testMetadata);
+    }
+    /**
+     * DELETE /api/tests/:testId — delete a test and all its flows.
+     */
+    async deleteTest(req, res) {
+        const testId = String(req.params.testId);
+        await this.testsManager.deleteTest(testId);
+        res.status(200).json({ deleted: true });
+    }
+    /**
+     * GET /api/tests/:testId/flows — list flows for a test.
+     */
+    async getTestFlows(req, res) {
+        const testId = String(req.params.testId);
+        const flows = await this.flowsManager.getFlows({ testId });
+        res.json({ flows: flows.items, nextPageToken: flows.nextPageToken });
+    }
+    /**
+     * POST /api/tests/:testId/run — execute a test (create a new flow from it).
+     */
+    async runTest(req, res) {
+        const testId = String(req.params.testId);
+        const newFlowConfig = await this.testsManager.getNewFlowFromTest(testId);
+        const flowHandle = await this.flowsManager.createFlow(newFlowConfig);
+        // After starting an autonomous run, switch the test to deterministic
+        // so subsequent runs replay the recorded actions.
+        if (newFlowConfig.initialRunMode === 'AUTONOMOUS') {
+            const test = await this.testsManager.getTestById(testId);
+            await this.testsManager.updateTest({
+                ...test,
+                nextRunMode: 'DETERMINISTIC',
+            });
+        }
+        res.json(flowHandle.donobuFlow.metadata);
+    }
+}
+exports.TestsApi = TestsApi;
+//# sourceMappingURL=TestsApi.js.map

package/dist/assets/openapi-schema.yaml

@@ -1496,6 +1496,7 @@ components:
         to restore when starting a flow. Exactly one variant should be provided:
         - `id` — Reference a flow by its ID and restore its persisted browser state.
         - `name` — Reference a flow by its name and restore its persisted browser state.
+        - `testId` — Reference a test by its ID and restore browser state from the most recent successful flow belonging to that test.
         - `json` — Provide the browser state inline as a JSON object.
       oneOf:
         - type: 'object'
@@ -1526,6 +1527,20 @@ components:
             value:
               type: 'string'
               description: 'The name of the flow whose browser state should be restored.'
+        - type: 'object'
+          description: 'Reference a test by ID to restore browser state from its most recent successful flow.'
+          required:
+            - 'type'
+            - 'value'
+          properties:
+            type:
+              type: 'string'
+              enum:
+                - 'testId'
+              description: 'Indicates the value is a test ID.'
+            value:
+              type: 'string'
+              description: 'A test ID. The browser state will be restored from the most recent successful flow belonging to this test.'
         - type: 'object'
           description: 'Provide browser state inline as a JSON object.'
           required:

package/dist/cli/install-donobu-plugin.d.ts

@@ -2,5 +2,24 @@
 export declare function getPluginName(): Promise<string>;
 export declare function buildPlugin(): Promise<void>;
 export declare function installPlugin(): Promise<void>;
+type ReleaseSpec = {
+    /** Plugin name as it appears on the tarball asset and as the install dir. */
+    name: string;
+    /** Pinned version, or `undefined` to resolve the latest. */
+    version: string | undefined;
+};
+/**
+ * Parses `name`, `name@version`, `@scope/name`, or `@scope/name@version`.
+ * The last `@` after the first character (if any) separates name and version.
+ */
+export declare function parseReleaseSpec(spec: string): ReleaseSpec;
+export declare function installFromRelease(spec: ReleaseSpec, apiKey: string, into: string | undefined): Promise<void>;
+type ParsedArgs = {
+    fromRelease: string | undefined;
+    apiKey: string | undefined;
+    into: string | undefined;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function main(): Promise<void>;
+export {};
 //# sourceMappingURL=install-donobu-plugin.d.ts.map

package/dist/cli/install-donobu-plugin.js

@@ -4,46 +4,57 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPluginName = getPluginName;
 exports.buildPlugin = buildPlugin;
 exports.installPlugin = installPlugin;
+exports.parseReleaseSpec = parseReleaseSpec;
+exports.installFromRelease = installFromRelease;
+exports.parseArgs = parseArgs;
 exports.main = main;
 /**
  * @fileoverview Donobu Plugin Installation CLI
  *
- * A command-line utility for building and installing Donobu plugins into the local Donobu Studio environment.
- * This script automates the process of compiling a plugin and copying it to the appropriate plugins directory
- * where Donobu Studio can discover and load it.
+ * A command-line utility for installing Donobu plugins into the local Donobu
+ * Studio environment. Two modes:
  *
- * @usage
- * Run this command from within a Donobu plugin directory (must contain package.json and src/ directory):
+ *   1. **Local build-and-copy** (default): run from a plugin source directory
+ *      with `package.json` and `src/`. Builds via `npm run build` and copies
+ *      `dist/` into Donobu's plugins directory.
+ *
+ *   2. **Release fetch** (`--from-release`): downloads a pre-built first-party
+ *      plugin bundle from the Donobu API (which checks the customer's
+ *      account entitlement before serving bytes from the private release
+ *      registry), verifies the sha256, and extracts it into Donobu's plugins
+ *      directory. No local project required.
  *
+ * @usage
  * ```bash
+ * # Local mode
  * npm exec install-donobu-plugin
- * ```
  *
- * @process
- * 1. Validates that the current directory is a valid plugin directory.
- * 2. Determines the plugin name from package.json, git repository, or username.
- * 3. Runs `npm run build` to compile the plugin.
- * 4. Copies the built plugin to the Donobu plugin directory (OS-variant).
- * 5. Provides instructions to restart Donobu Studio to see the new tools.
+ * # Release mode (latest)
+ * DONOBU_API_KEY=DB_… npx install-donobu-plugin \
+ *   --from-release @donobu/donobu-mobile
  *
- * @requirements
- * - Must be run from a directory containing package.json.
- * - Must be run from a directory containing src/ directory.
- * - The project must have a working `npm run build` script.
- * - Write permissions to the Donobu Studio plugins directory.
- *
- * @output
- * - Plugin compiled and installed to Donobu Studio plugins directory.
- * - Console output with installation progress and final location.
+ * # Release mode (pinned version)
+ * DONOBU_API_KEY=DB_… npx install-donobu-plugin \
+ *   --from-release @donobu/donobu-mobile@1.0.0
+ * ```
  */
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const promises_1 = require("fs/promises");
+const os_1 = require("os");
 const path_1 = require("path");
+const promises_2 = require("stream/promises");
 const util_1 = require("util");
 const Logger_1 = require("../utils/Logger");
 const MiscUtils_1 = require("../utils/MiscUtils");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
+/**
+ * Default Donobu API base URL. Matches the default in `envVars.ts` so that a
+ * customer with a production `DONOBU_API_KEY` needs no extra configuration
+ * to install plugins. Override for staging via `DONOBU_API_BASE_URL`.
+ */
+const DEFAULT_DONOBU_API_BASE_URL = 'https://donobu-prd-api-service-73193699649.us-central1.run.app';
 async function getPluginName() {
     try {
         // First, try to read the plugin name from package.json
@@ -95,9 +106,262 @@ async function installPlugin() {
     Logger_1.appLogger.info(`Plugin installed successfully to: ${thisPluginDir}`);
     Logger_1.appLogger.info('Restart Donobu to load the plugin.');
 }
+/**
+ * Parses `name`, `name@version`, `@scope/name`, or `@scope/name@version`.
+ * The last `@` after the first character (if any) separates name and version.
+ */
+function parseReleaseSpec(spec) {
+    if (!spec) {
+        throw new Error('--from-release requires a plugin name');
+    }
+    const atIdx = spec.lastIndexOf('@');
+    if (atIdx > 0) {
+        return { name: spec.slice(0, atIdx), version: spec.slice(atIdx + 1) };
+    }
+    return { name: spec, version: undefined };
+}
+function getDonobuApiBaseUrl() {
+    return (process.env.DONOBU_API_BASE_URL?.replace(/\/$/, '') ??
+        DEFAULT_DONOBU_API_BASE_URL);
+}
+function getDonobuApiKey(explicit) {
+    const key = explicit ?? process.env.DONOBU_API_KEY;
+    if (!key) {
+        throw new Error('Missing DONOBU_API_KEY. Pass --api-key <key>, set DONOBU_API_KEY in ' +
+            'your environment, or retrieve a key at https://donobu.com/account/keys.');
+    }
+    return key;
+}
+/**
+ * Surface donobu-api JSON error bodies (`{ error, message }`) in the CLI's
+ * error output, so customers see the server's description instead of a bare
+ * HTTP status code.
+ */
+async function extractApiErrorMessage(res) {
+    try {
+        const body = (await res.clone().json());
+        if (body.message) {
+            return body.message;
+        }
+        if (body.error) {
+            return body.error;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return `${res.status} ${res.statusText}`;
+}
+async function fetchReleaseMetadata(baseUrl, apiKey, spec) {
+    const params = new URLSearchParams({
+        name: spec.name,
+        version: spec.version ?? 'latest',
+    });
+    const url = `${baseUrl}/v1/plugins/release?${params.toString()}`;
+    const res = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+            'User-Agent': 'install-donobu-plugin',
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to resolve ${spec.name}@${spec.version ?? 'latest'}: ` +
+            (await extractApiErrorMessage(res)));
+    }
+    return (await res.json());
+}
+async function downloadTarball(baseUrl, apiKey, name, version, destPath) {
+    const params = new URLSearchParams({ name, version });
+    const url = `${baseUrl}/v1/plugins/release/tarball?${params.toString()}`;
+    const res = await fetch(url, {
+        headers: {
+            Accept: 'application/octet-stream',
+            Authorization: `Bearer ${apiKey}`,
+            'User-Agent': 'install-donobu-plugin',
+        },
+    });
+    if (!res.ok || !res.body) {
+        throw new Error(`Failed to download ${name}@${version}: ` +
+            (await extractApiErrorMessage(res)));
+    }
+    await (0, promises_2.pipeline)(res.body, (0, fs_1.createWriteStream)(destPath));
+}
+async function fetchEntitlementsEnvelope(baseUrl, apiKey) {
+    const res = await fetch(`${baseUrl}/v1/entitlements`, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+            'User-Agent': 'install-donobu-plugin',
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch entitlements: ` + (await extractApiErrorMessage(res)));
+    }
+    // Persist the exact JSON bytes the server sent. Reserializing would risk
+    // reordering keys in a way that invalidates the signature downstream.
+    const raw = await res.text();
+    return { raw, envelope: JSON.parse(raw) };
+}
+async function sha256OfFile(path) {
+    const hash = (0, crypto_1.createHash)('sha256');
+    const buf = await (0, promises_1.readFile)(path);
+    hash.update(buf);
+    return hash.digest('hex');
+}
+async function extractTarball(tarballPath, destDir) {
+    await (0, promises_1.mkdir)(destDir, { recursive: true });
+    // `tar` handles both gzip and xz transparently with `-xf`. `-C` sets the
+    // extraction root. Expect the tarball to contain the flat plugin payload
+    // (index.mjs, package.json, etc.) at its root — not nested under dist/.
+    await execAsync(`tar -xf "${tarballPath}" -C "${destDir}"`);
+}
+/**
+ * Filename for the signed entitlement envelope when colocated with a
+ * plugin's extracted bundle. Matches the constant in the plugin's
+ * entitlement-check code; changing one without the other breaks license
+ * discovery.
+ */
+const LICENSE_FILENAME = '.donobu-license.json';
+/**
+ * Resolve the parent directory into which the plugin's own dir will be
+ * placed. Without `--into`, we use the default `<app-data>/plugins/`
+ * location the Donobu Studio plugin loader scans. With `--into`, we
+ * honor the caller's path (useful for code-based test setups that want
+ * the plugin discoverable inside their own `node_modules/@donobu/`).
+ */
+function resolveInstallParentDir(into) {
+    if (into) {
+        return (0, path_1.resolve)(into);
+    }
+    return (0, path_1.join)(MiscUtils_1.MiscUtils.baseWorkingDirectory(), 'plugins');
+}
+async function installFromRelease(spec, apiKey, into) {
+    const baseUrl = getDonobuApiBaseUrl();
+    Logger_1.appLogger.info(`Resolving ${spec.name}@${spec.version ?? 'latest'} from ${baseUrl}...`);
+    const { name, version, manifest } = await fetchReleaseMetadata(baseUrl, apiKey, spec);
+    if (manifest.name !== name || manifest.version !== version) {
+        throw new Error(`Manifest mismatch: expected ${name}@${version}, got ${manifest.name}@${manifest.version}.`);
+    }
+    // Fetch the signed entitlement envelope before the tarball download so we
+    // fail fast if the server would not recognize the grant anyway. The
+    // metadata call above already gates on entitlement, but this also catches
+    // races (e.g. revocation between the two calls) and gives us the signed
+    // payload gated plugins require at load time.
+    Logger_1.appLogger.info('Fetching signed entitlement envelope...');
+    const { raw: envelopeJson, envelope } = await fetchEntitlementsEnvelope(baseUrl, apiKey);
+    if (!envelope.payload.entitlements[name]) {
+        throw new Error(`Entitlement envelope does not contain a grant for ${name}. ` +
+            `The grant may have been revoked during install; try again.`);
+    }
+    const workDir = await (0, promises_1.mkdtemp)((0, path_1.join)((0, os_1.tmpdir)(), 'donobu-plugin-'));
+    try {
+        const tarPath = (0, path_1.join)(workDir, manifest.tarball);
+        Logger_1.appLogger.info(`Downloading ${manifest.tarball}...`);
+        await downloadTarball(baseUrl, apiKey, name, version, tarPath);
+        const actualSha = await sha256OfFile(tarPath);
+        if (actualSha.toLowerCase() !== manifest.sha256.toLowerCase()) {
+            throw new Error(`Checksum mismatch for ${manifest.tarball} — refusing to install. ` +
+                `Expected ${manifest.sha256}, got ${actualSha}.`);
+        }
+        // Extract into a staging dir inside workDir first, then atomically swap
+        // into the final plugins location to avoid half-written plugin state.
+        // License file goes inside the staging dir before the swap so the
+        // post-rename plugin dir always has both bundle + license present at
+        // the same instant — no half-installed window.
+        const stageDir = (0, path_1.join)(workDir, 'stage');
+        await extractTarball(tarPath, stageDir);
+        await (0, promises_1.writeFile)((0, path_1.join)(stageDir, LICENSE_FILENAME), envelopeJson + '\n', 'utf8');
+        const parentDir = resolveInstallParentDir(into);
+        const destDir = (0, path_1.join)(parentDir, name);
+        await (0, promises_1.mkdir)(parentDir, { recursive: true });
+        // For scoped names like @donobu/donobu-mobile, ensure the @scope parent exists.
+        await (0, promises_1.mkdir)((0, path_1.join)(destDir, '..'), { recursive: true });
+        await (0, promises_1.rm)(destDir, { recursive: true, force: true });
+        await (0, promises_1.rename)(stageDir, destDir);
+        const grantExpiresAt = envelope.payload.entitlements[name].expiresAt;
+        const expiryDescription = grantExpiresAt === null ? 'perpetual (never expires)' : grantExpiresAt;
+        Logger_1.appLogger.info(`Installed ${name}@${version} to ${destDir} ` +
+            `(license colocated, entitlement ${expiryDescription}). ` +
+            `Restart Donobu to load the plugin.`);
+        // Soft-warn when the customer is installing very close to the grant's
+        // expiry — catches the "I installed today but it already stopped working"
+        // footgun.
+        if (grantExpiresAt !== null) {
+            const daysUntilExpiry = Math.floor((new Date(grantExpiresAt).getTime() - Date.now()) / 86_400_000);
+            if (daysUntilExpiry >= 0 && daysUntilExpiry < 7) {
+                Logger_1.appLogger.warn(`Your entitlement expires in ${daysUntilExpiry} day(s) ` +
+                    `(${grantExpiresAt}). Contact support@donobu.com to renew before relying on this install.`);
+            }
+        }
+    }
+    finally {
+        await (0, promises_1.rm)(workDir, { recursive: true, force: true });
+    }
+}
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let fromRelease;
+    let apiKey;
+    let into;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--from-release' && i + 1 < args.length) {
+            fromRelease = args[++i];
+        }
+        else if (a.startsWith('--from-release=')) {
+            fromRelease = a.slice('--from-release='.length);
+        }
+        else if (a === '--api-key' && i + 1 < args.length) {
+            apiKey = args[++i];
+        }
+        else if (a.startsWith('--api-key=')) {
+            apiKey = a.slice('--api-key='.length);
+        }
+        else if (a === '--into' && i + 1 < args.length) {
+            into = args[++i];
+        }
+        else if (a.startsWith('--into=')) {
+            into = a.slice('--into='.length);
+        }
+        else if (a === '--help' || a === '-h') {
+            printUsage();
+            process.exit(0);
+        }
+    }
+    return { fromRelease, apiKey, into };
+}
+function printUsage() {
+    console.log([
+        'Usage:',
+        '  install-donobu-plugin                         # build & install from current dir',
+        '  install-donobu-plugin --from-release <name>[@<version>] [--api-key <key>] [--into <dir>]',
+        '',
+        'Release-mode options:',
+        '  --from-release <name>[@<version>]  Install a pre-built Donobu plugin.',
+        '                                     Omit @version to install the latest.',
+        '  --api-key <key>                    Donobu API key (or set DONOBU_API_KEY).',
+        '                                     Your account entitlement gates access.',
+        '  --into <dir>                       Install the plugin under <dir>/<name>/',
+        '                                     instead of the Donobu Studio plugins',
+        '                                     directory. Useful for code-based test',
+        '                                     setups — pass `./node_modules` to make',
+        '                                     the plugin importable from your project.',
+        '',
+        'Examples:',
+        '  install-donobu-plugin --from-release @donobu/donobu-mobile',
+        '  install-donobu-plugin --from-release @donobu/donobu-mobile@1.0.0',
+        '  install-donobu-plugin --from-release @donobu/donobu-mobile --into ./node_modules',
+    ].join('\n'));
+}
 async function main() {
+    const { fromRelease, apiKey, into } = parseArgs(process.argv);
     try {
-        // Check if we're in a plugin directory
+        if (fromRelease) {
+            await installFromRelease(parseReleaseSpec(fromRelease), getDonobuApiKey(apiKey), into);
+            return;
+        }
+        // Local build-and-copy mode — must be run from a plugin source directory.
         try {
             await (0, promises_1.access)('package.json', fs_1.constants.F_OK);
             await (0, promises_1.access)('src', fs_1.constants.F_OK);

package/dist/esm/apis/SuitesApi.d.ts

@@ -0,0 +1,36 @@
+import type { Request, Response } from 'express';
+import type { SuitesManager } from '../managers/SuitesManager';
+import type { TestsManager } from '../managers/TestsManager';
+/**
+ * API controller for managing suites.
+ */
+export declare class SuitesApi {
+    private readonly suitesManager;
+    private readonly testsManager;
+    constructor(suitesManager: SuitesManager, testsManager: TestsManager);
+    /**
+     * GET /api/suites — list suites with optional filtering and pagination.
+     */
+    getSuites(req: Request, res: Response): Promise<void>;
+    /**
+     * POST /api/suites — create a new suite.
+     */
+    createSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * GET /api/suites/:suiteId — get a suite by ID.
+     */
+    getSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * PUT /api/suites/:suiteId — update an existing suite.
+     */
+    updateSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * DELETE /api/suites/:suiteId — delete a suite (tests are orphaned).
+     */
+    deleteSuite(req: Request, res: Response): Promise<void>;
+    /**
+     * GET /api/suites/:suiteId/tests — list tests in a suite.
+     */
+    getSuiteTests(req: Request, res: Response): Promise<void>;
+}
+//# sourceMappingURL=SuitesApi.d.ts.map