donobu 5.24.0 → 5.25.0

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/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/esm/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/managers/PluginLoader.d.ts

@@ -36,8 +36,9 @@ export type PluginDependencies = {
  *    the primary discovery path for SDK users who `npm install` plugins
  *    alongside the `donobu` package.
  *
- * When a plugin is found in both sources, the app-data copy takes
- * precedence (allowing local overrides during development).
+ * When a plugin is found in both sources, the node_modules copy wins —
+ * an explicit project-level dependency should override global Studio
+ * state so tests run against the version the project declares.
  */
 export declare class PluginLoader {
     private readonly pluginsPath;
@@ -54,17 +55,42 @@ export declare class PluginLoader {
      * `node_modules`. All plugin types are collected and returned.
      */
     loadAllPlugins(): Promise<LoadedPlugins>;
+    /**
+     * Determine which file PluginLoader should dynamic-import for a plugin
+     * living at `pkgDir`, using a three-tier cascade:
+     *
+     *   1. `exports["./plugin"].import` — preferred for dual-use packages
+     *      (those that also expose an SDK surface on the default entry).
+     *      Points at a bundle built from plugin hooks only, with no
+     *      value-level `donobu` imports, so it loads cleanly even from the
+     *      app-data plugins dir where no sibling `donobu` module exists.
+     *      Example: `@donobu/donobu-mobile`.
+     *   2. `exports.import` — the old flat shape used by plugin-only
+     *      packages (no SDK surface, no value-level `donobu` imports).
+     *      Examples: `tools-captcha`, `tools-mfa`, `donobu-aws`,
+     *      `donobu-google`.
+     *   3. `<pkgDir>/index.mjs` — convention fallback for hand-dropped
+     *      plugins that ship no `package.json` at all.
+     *
+     * `requirePackageJson` toggles whether the caller demands a
+     * package.json with `"donobu-plugin": true` at the package root
+     * (node_modules discovery) or is happy with any directory that has an
+     * `index.mjs` (app-data discovery — supports hand-dropped legacy
+     * plugins).
+     */
+    private resolvePlugin;
     /**
      * Scan the app-data plugins directory for standalone plugin bundles.
-     * Each plugin is a directory containing an `index.mjs` entry point.
-     * Scoped packages (`@scope/name`) are supported one level deep.
+     * Each plugin is a directory containing a `package.json` with
+     * `"donobu-plugin": true`. Scoped packages (`@scope/name`) are supported
+     * one level deep.
      */
     private discoverDirectoryPlugins;
     /**
      * Scan `node_modules/@donobu/` for npm-installed packages that declare
-     * `"donobu-plugin": true` in their `package.json`. The ESM entry point
-     * is resolved from the package's `exports.import` field, falling back
-     * to `dist/index.mjs`.
+     * `"donobu-plugin": true` in their `package.json`. Delegates the actual
+     * entry-point resolution to `resolvePlugin` so app-data and
+     * node_modules installs follow the same rules.
      */
     private discoverNodeModulesPlugins;
 }

package/dist/esm/managers/PluginLoader.js

@@ -78,6 +78,32 @@ function findNodeModulesDonobuScope() {
     }
     return undefined;
 }
+/**
+ * Resolve the file PluginLoader should dynamic-import for a plugin at
+ * `pkgDir`, given its (possibly undefined) `package.json` `exports`
+ * field. Three-tier cascade — see PluginLoader.resolvePlugin for the
+ * semantic rationale for each tier.
+ */
+function resolvePluginEntryPath(pkgDir, exportsField) {
+    if (exportsField && typeof exportsField === 'object') {
+        const exp = exportsField;
+        // 1. Subpath export: exports["./plugin"].import
+        const subpath = exp['./plugin'];
+        if (subpath && typeof subpath === 'object') {
+            const subpathImport = subpath.import;
+            if (typeof subpathImport === 'string') {
+                return node_path_1.default.resolve(pkgDir, subpathImport);
+            }
+        }
+        // 2. Flat export: exports.import
+        const flatImport = exp.import;
+        if (typeof flatImport === 'string') {
+            return node_path_1.default.resolve(pkgDir, flatImport);
+        }
+    }
+    // 3. Convention fallback.
+    return node_path_1.default.join(pkgDir, 'index.mjs');
+}
 /**
  * Loads Donobu plugins from two sources:
  *
@@ -91,8 +117,9 @@ function findNodeModulesDonobuScope() {
  *    the primary discovery path for SDK users who `npm install` plugins
  *    alongside the `donobu` package.
  *
- * When a plugin is found in both sources, the app-data copy takes
- * precedence (allowing local overrides during development).
+ * When a plugin is found in both sources, the node_modules copy wins —
+ * an explicit project-level dependency should override global Studio
+ * state so tests run against the version the project declares.
  */
 class PluginLoader {
     constructor(pluginsPath, pluginDependencies, nodeModulesScopePath) {
@@ -116,10 +143,15 @@ class PluginLoader {
     async loadAllPlugins() {
         const dirPlugins = await this.discoverDirectoryPlugins();
         const nmPlugins = await this.discoverNodeModulesPlugins();
-        // Deduplicate: app-data plugins take precedence over node_modules.
-        const seen = new Set(dirPlugins.map((p) => p.name));
-        const allPlugins = [...dirPlugins];
-        for (const p of nmPlugins) {
+        // Deduplicate: node_modules plugins take precedence over app-data.
+        // A project that explicitly depends on a plugin version (via the
+        // install CLI's `--into ./node_modules` or a regular npm install)
+        // should get that version, not whatever global Studio state
+        // happens to carry. App-data is the fallback for plugins the project
+        // hasn't declared.
+        const seen = new Set(nmPlugins.map((p) => p.name));
+        const allPlugins = [...nmPlugins];
+        for (const p of dirPlugins) {
             if (!seen.has(p.name)) {
                 allPlugins.push(p);
                 seen.add(p.name);
@@ -188,12 +220,59 @@ class PluginLoader {
         };
     }
     // ---------------------------------------------------------------------------
+    // Plugin resolution
+    // ---------------------------------------------------------------------------
+    /**
+     * Determine which file PluginLoader should dynamic-import for a plugin
+     * living at `pkgDir`, using a three-tier cascade:
+     *
+     *   1. `exports["./plugin"].import` — preferred for dual-use packages
+     *      (those that also expose an SDK surface on the default entry).
+     *      Points at a bundle built from plugin hooks only, with no
+     *      value-level `donobu` imports, so it loads cleanly even from the
+     *      app-data plugins dir where no sibling `donobu` module exists.
+     *      Example: `@donobu/donobu-mobile`.
+     *   2. `exports.import` — the old flat shape used by plugin-only
+     *      packages (no SDK surface, no value-level `donobu` imports).
+     *      Examples: `tools-captcha`, `tools-mfa`, `donobu-aws`,
+     *      `donobu-google`.
+     *   3. `<pkgDir>/index.mjs` — convention fallback for hand-dropped
+     *      plugins that ship no `package.json` at all.
+     *
+     * `requirePackageJson` toggles whether the caller demands a
+     * package.json with `"donobu-plugin": true` at the package root
+     * (node_modules discovery) or is happy with any directory that has an
+     * `index.mjs` (app-data discovery — supports hand-dropped legacy
+     * plugins).
+     */
+    async resolvePlugin(pkgDir, requirePackageJson) {
+        let pkgJson = null;
+        try {
+            const raw = await promises_1.default.readFile(node_path_1.default.join(pkgDir, 'package.json'), 'utf-8');
+            pkgJson = JSON.parse(raw);
+        }
+        catch {
+            if (requirePackageJson) {
+                return null;
+            }
+            // No package.json is fine for the app-data path; the dir is
+            // treated as a bare `index.mjs` plugin drop (legacy pattern).
+        }
+        if (requirePackageJson && !pkgJson?.['donobu-plugin']) {
+            return null;
+        }
+        const entryPoint = resolvePluginEntryPath(pkgDir, pkgJson?.exports);
+        const name = pkgJson?.name ?? node_path_1.default.basename(pkgDir);
+        return { name, entryPoint };
+    }
+    // ---------------------------------------------------------------------------
     // Discovery: app-data plugins directory
     // ---------------------------------------------------------------------------
     /**
      * Scan the app-data plugins directory for standalone plugin bundles.
-     * Each plugin is a directory containing an `index.mjs` entry point.
-     * Scoped packages (`@scope/name`) are supported one level deep.
+     * Each plugin is a directory containing a `package.json` with
+     * `"donobu-plugin": true`. Scoped packages (`@scope/name`) are supported
+     * one level deep.
      */
     async discoverDirectoryPlugins() {
         Logger_1.appLogger.info(`Scanning "${this.pluginsPath}" for plugins...`);
@@ -207,17 +286,16 @@ class PluginLoader {
         const plugins = [];
         for (const entry of dirEntries.filter((d) => d.isDirectory())) {
             if (entry.name.startsWith('@')) {
-                // Scoped packages: scan one level deeper.
                 try {
                     const scopeDir = node_path_1.default.join(this.pluginsPath, entry.name);
                     const scopeEntries = await promises_1.default.readdir(scopeDir, {
                         withFileTypes: true,
                     });
                     for (const sub of scopeEntries.filter((d) => d.isDirectory())) {
-                        plugins.push({
-                            name: `${entry.name}/${sub.name}`,
-                            entryPoint: node_path_1.default.join(scopeDir, sub.name, 'index.mjs'),
-                        });
+                        const resolved = await this.resolvePlugin(node_path_1.default.join(scopeDir, sub.name), false);
+                        if (resolved) {
+                            plugins.push(resolved);
+                        }
                     }
                 }
                 catch {
@@ -225,10 +303,10 @@ class PluginLoader {
                 }
             }
             else {
-                plugins.push({
-                    name: entry.name,
-                    entryPoint: node_path_1.default.join(this.pluginsPath, entry.name, 'index.mjs'),
-                });
+                const resolved = await this.resolvePlugin(node_path_1.default.join(this.pluginsPath, entry.name), false);
+                if (resolved) {
+                    plugins.push(resolved);
+                }
             }
         }
         return plugins;
@@ -238,9 +316,9 @@ class PluginLoader {
     // ---------------------------------------------------------------------------
     /**
      * Scan `node_modules/@donobu/` for npm-installed packages that declare
-     * `"donobu-plugin": true` in their `package.json`. The ESM entry point
-     * is resolved from the package's `exports.import` field, falling back
-     * to `dist/index.mjs`.
+     * `"donobu-plugin": true` in their `package.json`. Delegates the actual
+     * entry-point resolution to `resolvePlugin` so app-data and
+     * node_modules installs follow the same rules.
      */
     async discoverNodeModulesPlugins() {
         if (!this.nodeModulesScopePath) {
@@ -258,23 +336,10 @@ class PluginLoader {
         const plugins = [];
         for (const entry of entries.filter((d) => d.isDirectory())) {
             const pkgDir = node_path_1.default.join(this.nodeModulesScopePath, entry.name);
-            try {
-                const pkgJsonRaw = await promises_1.default.readFile(node_path_1.default.join(pkgDir, 'package.json'), 'utf-8');
-                const pkgJson = JSON.parse(pkgJsonRaw);
-                if (!pkgJson['donobu-plugin']) {
-                    continue;
-                }
-                // Resolve ESM entry point from package.json exports or default.
-                const esmRelative = pkgJson.exports?.import ?? 'dist/index.mjs';
-                const entryPoint = node_path_1.default.resolve(pkgDir, esmRelative);
-                plugins.push({
-                    name: pkgJson.name ?? `@donobu/${entry.name}`,
-                    entryPoint,
-                });
-                Logger_1.appLogger.info(`Found npm plugin "${pkgJson.name ?? entry.name}" at ${pkgDir}`);
-            }
-            catch {
-                // No package.json or unreadable — skip.
+            const resolved = await this.resolvePlugin(pkgDir, true);
+            if (resolved) {
+                plugins.push(resolved);
+                Logger_1.appLogger.info(`Found npm plugin "${resolved.name}" at ${pkgDir}`);
             }
         }
         return plugins;

package/dist/managers/PluginLoader.d.ts

@@ -36,8 +36,9 @@ export type PluginDependencies = {
  *    the primary discovery path for SDK users who `npm install` plugins
  *    alongside the `donobu` package.
  *
- * When a plugin is found in both sources, the app-data copy takes
- * precedence (allowing local overrides during development).
+ * When a plugin is found in both sources, the node_modules copy wins —
+ * an explicit project-level dependency should override global Studio
+ * state so tests run against the version the project declares.
  */
 export declare class PluginLoader {
     private readonly pluginsPath;
@@ -54,17 +55,42 @@ export declare class PluginLoader {
      * `node_modules`. All plugin types are collected and returned.
      */
     loadAllPlugins(): Promise<LoadedPlugins>;
+    /**
+     * Determine which file PluginLoader should dynamic-import for a plugin
+     * living at `pkgDir`, using a three-tier cascade:
+     *
+     *   1. `exports["./plugin"].import` — preferred for dual-use packages
+     *      (those that also expose an SDK surface on the default entry).
+     *      Points at a bundle built from plugin hooks only, with no
+     *      value-level `donobu` imports, so it loads cleanly even from the
+     *      app-data plugins dir where no sibling `donobu` module exists.
+     *      Example: `@donobu/donobu-mobile`.
+     *   2. `exports.import` — the old flat shape used by plugin-only
+     *      packages (no SDK surface, no value-level `donobu` imports).
+     *      Examples: `tools-captcha`, `tools-mfa`, `donobu-aws`,
+     *      `donobu-google`.
+     *   3. `<pkgDir>/index.mjs` — convention fallback for hand-dropped
+     *      plugins that ship no `package.json` at all.
+     *
+     * `requirePackageJson` toggles whether the caller demands a
+     * package.json with `"donobu-plugin": true` at the package root
+     * (node_modules discovery) or is happy with any directory that has an
+     * `index.mjs` (app-data discovery — supports hand-dropped legacy
+     * plugins).
+     */
+    private resolvePlugin;
     /**
      * Scan the app-data plugins directory for standalone plugin bundles.
-     * Each plugin is a directory containing an `index.mjs` entry point.
-     * Scoped packages (`@scope/name`) are supported one level deep.
+     * Each plugin is a directory containing a `package.json` with
+     * `"donobu-plugin": true`. Scoped packages (`@scope/name`) are supported
+     * one level deep.
      */
     private discoverDirectoryPlugins;
     /**
      * Scan `node_modules/@donobu/` for npm-installed packages that declare
-     * `"donobu-plugin": true` in their `package.json`. The ESM entry point
-     * is resolved from the package's `exports.import` field, falling back
-     * to `dist/index.mjs`.
+     * `"donobu-plugin": true` in their `package.json`. Delegates the actual
+     * entry-point resolution to `resolvePlugin` so app-data and
+     * node_modules installs follow the same rules.
      */
     private discoverNodeModulesPlugins;
 }

package/dist/managers/PluginLoader.js

@@ -78,6 +78,32 @@ function findNodeModulesDonobuScope() {
     }
     return undefined;
 }
+/**
+ * Resolve the file PluginLoader should dynamic-import for a plugin at
+ * `pkgDir`, given its (possibly undefined) `package.json` `exports`
+ * field. Three-tier cascade — see PluginLoader.resolvePlugin for the
+ * semantic rationale for each tier.
+ */
+function resolvePluginEntryPath(pkgDir, exportsField) {
+    if (exportsField && typeof exportsField === 'object') {
+        const exp = exportsField;
+        // 1. Subpath export: exports["./plugin"].import
+        const subpath = exp['./plugin'];
+        if (subpath && typeof subpath === 'object') {
+            const subpathImport = subpath.import;
+            if (typeof subpathImport === 'string') {
+                return node_path_1.default.resolve(pkgDir, subpathImport);
+            }
+        }
+        // 2. Flat export: exports.import
+        const flatImport = exp.import;
+        if (typeof flatImport === 'string') {
+            return node_path_1.default.resolve(pkgDir, flatImport);
+        }
+    }
+    // 3. Convention fallback.
+    return node_path_1.default.join(pkgDir, 'index.mjs');
+}
 /**
  * Loads Donobu plugins from two sources:
  *
@@ -91,8 +117,9 @@ function findNodeModulesDonobuScope() {
  *    the primary discovery path for SDK users who `npm install` plugins
  *    alongside the `donobu` package.
  *
- * When a plugin is found in both sources, the app-data copy takes
- * precedence (allowing local overrides during development).
+ * When a plugin is found in both sources, the node_modules copy wins —
+ * an explicit project-level dependency should override global Studio
+ * state so tests run against the version the project declares.
  */
 class PluginLoader {
     constructor(pluginsPath, pluginDependencies, nodeModulesScopePath) {
@@ -116,10 +143,15 @@ class PluginLoader {
     async loadAllPlugins() {
         const dirPlugins = await this.discoverDirectoryPlugins();
         const nmPlugins = await this.discoverNodeModulesPlugins();
-        // Deduplicate: app-data plugins take precedence over node_modules.
-        const seen = new Set(dirPlugins.map((p) => p.name));
-        const allPlugins = [...dirPlugins];
-        for (const p of nmPlugins) {
+        // Deduplicate: node_modules plugins take precedence over app-data.
+        // A project that explicitly depends on a plugin version (via the
+        // install CLI's `--into ./node_modules` or a regular npm install)
+        // should get that version, not whatever global Studio state
+        // happens to carry. App-data is the fallback for plugins the project
+        // hasn't declared.
+        const seen = new Set(nmPlugins.map((p) => p.name));
+        const allPlugins = [...nmPlugins];
+        for (const p of dirPlugins) {
             if (!seen.has(p.name)) {
                 allPlugins.push(p);
                 seen.add(p.name);
@@ -188,12 +220,59 @@ class PluginLoader {
         };
     }
     // ---------------------------------------------------------------------------
+    // Plugin resolution
+    // ---------------------------------------------------------------------------
+    /**
+     * Determine which file PluginLoader should dynamic-import for a plugin
+     * living at `pkgDir`, using a three-tier cascade:
+     *
+     *   1. `exports["./plugin"].import` — preferred for dual-use packages
+     *      (those that also expose an SDK surface on the default entry).
+     *      Points at a bundle built from plugin hooks only, with no
+     *      value-level `donobu` imports, so it loads cleanly even from the
+     *      app-data plugins dir where no sibling `donobu` module exists.
+     *      Example: `@donobu/donobu-mobile`.
+     *   2. `exports.import` — the old flat shape used by plugin-only
+     *      packages (no SDK surface, no value-level `donobu` imports).
+     *      Examples: `tools-captcha`, `tools-mfa`, `donobu-aws`,
+     *      `donobu-google`.
+     *   3. `<pkgDir>/index.mjs` — convention fallback for hand-dropped
+     *      plugins that ship no `package.json` at all.
+     *
+     * `requirePackageJson` toggles whether the caller demands a
+     * package.json with `"donobu-plugin": true` at the package root
+     * (node_modules discovery) or is happy with any directory that has an
+     * `index.mjs` (app-data discovery — supports hand-dropped legacy
+     * plugins).
+     */
+    async resolvePlugin(pkgDir, requirePackageJson) {
+        let pkgJson = null;
+        try {
+            const raw = await promises_1.default.readFile(node_path_1.default.join(pkgDir, 'package.json'), 'utf-8');
+            pkgJson = JSON.parse(raw);
+        }
+        catch {
+            if (requirePackageJson) {
+                return null;
+            }
+            // No package.json is fine for the app-data path; the dir is
+            // treated as a bare `index.mjs` plugin drop (legacy pattern).
+        }
+        if (requirePackageJson && !pkgJson?.['donobu-plugin']) {
+            return null;
+        }
+        const entryPoint = resolvePluginEntryPath(pkgDir, pkgJson?.exports);
+        const name = pkgJson?.name ?? node_path_1.default.basename(pkgDir);
+        return { name, entryPoint };
+    }
+    // ---------------------------------------------------------------------------
     // Discovery: app-data plugins directory
     // ---------------------------------------------------------------------------
     /**
      * Scan the app-data plugins directory for standalone plugin bundles.
-     * Each plugin is a directory containing an `index.mjs` entry point.
-     * Scoped packages (`@scope/name`) are supported one level deep.
+     * Each plugin is a directory containing a `package.json` with
+     * `"donobu-plugin": true`. Scoped packages (`@scope/name`) are supported
+     * one level deep.
      */
     async discoverDirectoryPlugins() {
         Logger_1.appLogger.info(`Scanning "${this.pluginsPath}" for plugins...`);
@@ -207,17 +286,16 @@ class PluginLoader {
         const plugins = [];
         for (const entry of dirEntries.filter((d) => d.isDirectory())) {
             if (entry.name.startsWith('@')) {
-                // Scoped packages: scan one level deeper.
                 try {
                     const scopeDir = node_path_1.default.join(this.pluginsPath, entry.name);
                     const scopeEntries = await promises_1.default.readdir(scopeDir, {
                         withFileTypes: true,
                     });
                     for (const sub of scopeEntries.filter((d) => d.isDirectory())) {
-                        plugins.push({
-                            name: `${entry.name}/${sub.name}`,
-                            entryPoint: node_path_1.default.join(scopeDir, sub.name, 'index.mjs'),
-                        });
+                        const resolved = await this.resolvePlugin(node_path_1.default.join(scopeDir, sub.name), false);
+                        if (resolved) {
+                            plugins.push(resolved);
+                        }
                     }
                 }
                 catch {
@@ -225,10 +303,10 @@ class PluginLoader {
                 }
             }
             else {
-                plugins.push({
-                    name: entry.name,
-                    entryPoint: node_path_1.default.join(this.pluginsPath, entry.name, 'index.mjs'),
-                });
+                const resolved = await this.resolvePlugin(node_path_1.default.join(this.pluginsPath, entry.name), false);
+                if (resolved) {
+                    plugins.push(resolved);
+                }
             }
         }
         return plugins;
@@ -238,9 +316,9 @@ class PluginLoader {
     // ---------------------------------------------------------------------------
     /**
      * Scan `node_modules/@donobu/` for npm-installed packages that declare
-     * `"donobu-plugin": true` in their `package.json`. The ESM entry point
-     * is resolved from the package's `exports.import` field, falling back
-     * to `dist/index.mjs`.
+     * `"donobu-plugin": true` in their `package.json`. Delegates the actual
+     * entry-point resolution to `resolvePlugin` so app-data and
+     * node_modules installs follow the same rules.
      */
     async discoverNodeModulesPlugins() {
         if (!this.nodeModulesScopePath) {
@@ -258,23 +336,10 @@ class PluginLoader {
         const plugins = [];
         for (const entry of entries.filter((d) => d.isDirectory())) {
             const pkgDir = node_path_1.default.join(this.nodeModulesScopePath, entry.name);
-            try {
-                const pkgJsonRaw = await promises_1.default.readFile(node_path_1.default.join(pkgDir, 'package.json'), 'utf-8');
-                const pkgJson = JSON.parse(pkgJsonRaw);
-                if (!pkgJson['donobu-plugin']) {
-                    continue;
-                }
-                // Resolve ESM entry point from package.json exports or default.
-                const esmRelative = pkgJson.exports?.import ?? 'dist/index.mjs';
-                const entryPoint = node_path_1.default.resolve(pkgDir, esmRelative);
-                plugins.push({
-                    name: pkgJson.name ?? `@donobu/${entry.name}`,
-                    entryPoint,
-                });
-                Logger_1.appLogger.info(`Found npm plugin "${pkgJson.name ?? entry.name}" at ${pkgDir}`);
-            }
-            catch {
-                // No package.json or unreadable — skip.
+            const resolved = await this.resolvePlugin(pkgDir, true);
+            if (resolved) {
+                plugins.push(resolved);
+                Logger_1.appLogger.info(`Found npm plugin "${resolved.name}" at ${pkgDir}`);
             }
         }
         return plugins;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",