@sovovs/bycli 2.0.0 → 2.1.0

package/dist/src/execution.js

@@ -16,7 +16,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getUserClisDir } from './config-paths.js';
 import { executePipeline } from './pipeline/index.js';
-import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
+import { adapterLoadError, ArgumentError, CliError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { resolveProfileContextId } from './browser/profile.js';
@@ -26,13 +26,33 @@ import { isElectronApp } from './electron-apps.js';
 import { probeCDP, resolveElectronEndpoint } from './launcher.js';
 import { ObservationSession, exportObservationSession } from './observation/index.js';
 import { resolveAdapterSourcePath } from './adapter-source.js';
+import { canonicalizeManifestArgSchema, ManifestSchemaError } from './manifest-schema.js';
+import { capturedRegistryValues, closeRegistryTransaction, createRegistryTransaction, finalizeRegistryTransaction, resetRegistryTransactionStateForTests, rollbackRegistryTransaction, runRegistryTransaction, transactionGroupsForKey, } from './registry-transaction.js';
 const _loadedModules = new Map();
-/** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
-const _moduleMtimes = new Map();
-/** User adapter dir with a trailing separator, so `startsWith` can't match a sibling
- * like `clis-foo`. Resolved per-call (config-paths.ts rationale) — no import-time freeze. */
-function userClisPrefix() {
-    return getUserClisDir() + path.sep;
+/** Independent cache-busting generation; retained when an import promise is discarded. */
+const _moduleImportGenerations = new Map();
+let _registrationImportTail = Promise.resolve();
+let _registrationImportsPoisoned = false;
+let _fingerprintReadCount = 0;
+const DEFAULT_ADAPTER_IMPORT_TIMEOUT_MS = 30_000;
+function adapterImportTimeoutMs() {
+    const configured = Number(process.env.BYCLI_ADAPTER_IMPORT_TIMEOUT_MS);
+    return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_ADAPTER_IMPORT_TIMEOUT_MS;
+}
+function poisonedImportError() {
+    return adapterLoadError('Adapter registration imports are unavailable because a previous import timed out.', 'Restart byCLI before retrying; the timed-out module may still complete and register stale commands in this process.');
+}
+/** Internal test-only reset. Never use this to recover a production process. */
+export function _resetLazyModuleStateForTests() {
+    _loadedModules.clear();
+    _moduleImportGenerations.clear();
+    _registrationImportTail = Promise.resolve();
+    _registrationImportsPoisoned = false;
+    _fingerprintReadCount = 0;
+    resetRegistryTransactionStateForTests();
+}
+export function _getLazyModuleFingerprintReadCountForTests() {
+    return _fingerprintReadCount;
 }
 function normalizeTraceMode(raw) {
     if (raw === undefined || raw === null || raw === '' || raw === 'off')
@@ -86,41 +106,19 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
 async function runCommand(cmd, page, kwargs, debug) {
     const internal = cmd;
     if (internal._lazy && internal._modulePath) {
-        const modulePath = internal._modulePath;
-        // Hot-reload: if a user adapter's file has changed on disk, invalidate cache
-        const isUserAdapter = modulePath.startsWith(userClisPrefix());
-        if (isUserAdapter && _loadedModules.has(modulePath)) {
-            try {
-                const stat = fs.statSync(modulePath);
-                const prevMtime = _moduleMtimes.get(modulePath);
-                if (prevMtime !== undefined && stat.mtimeMs !== prevMtime) {
-                    _loadedModules.delete(modulePath);
-                    _moduleMtimes.delete(modulePath);
-                }
-            }
-            catch { /* file may have been deleted; let import below handle it */ }
-        }
-        if (!_loadedModules.has(modulePath)) {
-            const url = pathToFileURL(modulePath).href;
-            const importUrl = _moduleMtimes.has(modulePath) ? `${url}?t=${Date.now()}` : url;
-            const loadPromise = import(importUrl).then(() => {
-                try {
-                    _moduleMtimes.set(modulePath, fs.statSync(modulePath).mtimeMs);
-                }
-                catch { }
-            }, (err) => {
-                _loadedModules.delete(modulePath);
-                throw adapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
-            });
-            _loadedModules.set(modulePath, loadPromise);
-        }
-        await _loadedModules.get(modulePath);
-        const updated = getRegistry().get(fullName(cmd));
-        if (updated?.func) {
+        const loadedEntry = await loadLazyModule(internal);
+        // Use the command registered by this import generation. A newer file
+        // generation may already be queued/current, but an execution that began
+        // on the older generation is allowed to finish with its own command.
+        const updated = loadedEntry?.registeredCommands.get(fullName(cmd));
+        if (loadedEntry && updated?.func) {
+            finalizeCommandRegistration(loadedEntry, fullName(cmd));
             return runCommandFunc(updated, page, kwargs, debug);
         }
-        if (updated?.pipeline)
+        if (loadedEntry && updated?.pipeline) {
+            finalizeCommandRegistration(loadedEntry, fullName(cmd));
             return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+        }
     }
     if (cmd.func)
         return runCommandFunc(cmd, page, kwargs, debug);
@@ -128,14 +126,212 @@ async function runCommand(cmd, page, kwargs, debug) {
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
     throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
 }
+function moduleFingerprint(modulePath) {
+    try {
+        _fingerprintReadCount += 1;
+        return crypto.createHash('sha256').update(fs.readFileSync(modulePath)).digest('hex');
+    }
+    catch {
+        return undefined;
+    }
+}
+function isHotReloadableModule(modulePath) {
+    const prefix = getUserClisDir() + path.sep;
+    return modulePath.startsWith(prefix);
+}
+function refreshCapturedCommands(entry) {
+    entry.registeredCommands = capturedRegistryValues(entry.transaction);
+}
+function rollbackImport(entry) {
+    rollbackRegistryTransaction(entry.transaction, getRegistry());
+}
+function rollbackCommandRegistration(entry, key) {
+    const groups = transactionGroupsForKey(entry.transaction, key);
+    rollbackRegistryTransaction(entry.transaction, getRegistry(), groups);
+}
+function finalizeCommandRegistration(entry, key) {
+    const groups = transactionGroupsForKey(entry.transaction, key);
+    finalizeRegistryTransaction(entry.transaction, getRegistry(), groups);
+}
+async function performRegistrationImport(entry, importUrl, modulePath) {
+    if (_registrationImportsPoisoned)
+        throw poisonedImportError();
+    const settlement = runRegistryTransaction(entry.transaction, () => import(importUrl)).then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+    let timeoutId;
+    const timeout = new Promise((resolve) => {
+        timeoutId = setTimeout(() => resolve({ timeout: true }), adapterImportTimeoutMs());
+    });
+    const outcome = await Promise.race([settlement, timeout]);
+    if ('timeout' in outcome) {
+        _registrationImportsPoisoned = true;
+        closeRegistryTransaction(entry.transaction);
+        rollbackImport(entry);
+        void settlement.then(() => {
+            refreshCapturedCommands(entry);
+            rollbackImport(entry);
+        });
+        throw adapterLoadError(`Adapter module ${modulePath} registration timed out after ${adapterImportTimeoutMs()}ms.`, 'Restart byCLI before retrying; ESM evaluation cannot be cancelled safely.');
+    }
+    if (timeoutId)
+        clearTimeout(timeoutId);
+    refreshCapturedCommands(entry);
+    if (!outcome.ok) {
+        rollbackImport(entry);
+        throw adapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(outcome.error)}`, 'Check that the adapter file exists and has no syntax errors.');
+    }
+}
+function scheduleRegistrationImport(entry, importUrl, modulePath) {
+    const scheduled = _registrationImportTail.then(() => performRegistrationImport(entry, importUrl, modulePath), () => performRegistrationImport(entry, importUrl, modulePath));
+    _registrationImportTail = scheduled.then(() => undefined, () => undefined);
+    return scheduled;
+}
+async function loadLazyModule(internal) {
+    const modulePath = internal._modulePath;
+    if (!internal._lazy || !modulePath)
+        return;
+    let entry = _loadedModules.get(modulePath);
+    if (entry) {
+        if (!entry.hotReloadable) {
+            await entry.promise;
+            return entry;
+        }
+        const currentFingerprint = moduleFingerprint(modulePath);
+        if (entry.fingerprint === currentFingerprint) {
+            await entry.promise;
+            return entry;
+        }
+        if (_registrationImportsPoisoned)
+            throw poisonedImportError();
+        invalidateLazyModule(modulePath, entry);
+        entry = undefined;
+    }
+    if (_registrationImportsPoisoned)
+        throw poisonedImportError();
+    if (!entry) {
+        const hotReloadable = isHotReloadableModule(modulePath);
+        const fingerprint = hotReloadable ? moduleFingerprint(modulePath) : undefined;
+        const url = pathToFileURL(modulePath).href;
+        const generation = _moduleImportGenerations.get(modulePath) ?? 0;
+        const importUrl = generation === 0 ? url : `${url}?v=${generation}`;
+        const createdEntry = {
+            promise: Promise.resolve(),
+            fingerprint,
+            generation,
+            registeredCommands: new Map(),
+            transaction: createRegistryTransaction(),
+            hotReloadable,
+        };
+        createdEntry.promise = scheduleRegistrationImport(createdEntry, importUrl, modulePath).catch((error) => {
+            invalidateLazyModule(modulePath, createdEntry);
+            throw error;
+        });
+        _loadedModules.set(modulePath, createdEntry);
+        entry = createdEntry;
+    }
+    await entry.promise;
+    return entry;
+}
+function invalidateLazyModule(modulePath, expectedEntry) {
+    if (!modulePath)
+        return;
+    const currentEntry = _loadedModules.get(modulePath);
+    if (!currentEntry || (expectedEntry && currentEntry !== expectedEntry))
+        return;
+    if (currentEntry.transaction.active) {
+        void currentEntry.promise.then(() => finalizeRegistryTransaction(currentEntry.transaction, getRegistry()), () => finalizeRegistryTransaction(currentEntry.transaction, getRegistry()));
+    }
+    else {
+        finalizeRegistryTransaction(currentEntry.transaction, getRegistry());
+    }
+    _loadedModules.delete(modulePath);
+    _moduleImportGenerations.set(modulePath, Math.max(_moduleImportGenerations.get(modulePath) ?? 0, currentEntry.generation) + 1);
+}
+function assertMatchingArgSchema(placeholder, hydrated, loadedEntry) {
+    const key = fullName(placeholder);
+    try {
+        const manifestSchema = canonicalizeManifestArgSchema(placeholder.args, `Manifest command ${key}`);
+        const moduleSchema = canonicalizeManifestArgSchema(hydrated.args, `Hydrated command ${key}`);
+        if (manifestSchema === moduleSchema)
+            return;
+    }
+    catch (error) {
+        if (loadedEntry)
+            rollbackCommandRegistration(loadedEntry, key);
+        invalidateLazyModule(placeholder._modulePath, loadedEntry);
+        if (!(error instanceof ManifestSchemaError))
+            throw error;
+        throw new CommandExecutionError(`Conditional adapter ${key} has an unsafe argument schema: ${error.message}`, 'Use only JSON-safe defaults and string choices, then rebuild the CLI manifest.');
+    }
+    if (loadedEntry)
+        rollbackCommandRegistration(loadedEntry, key);
+    invalidateLazyModule(placeholder._modulePath, loadedEntry);
+    throw new CommandExecutionError(`Conditional adapter ${key} argument schema does not match its manifest`, 'Rebuild the CLI manifest so defaults, coercion, and validation use the adapter module schema.');
+}
+async function hydrateConditionalCommand(cmd) {
+    const internal = cmd;
+    const key = fullName(cmd);
+    if (cmd.browser !== 'conditional') {
+        throw new CommandExecutionError(`Conditional adapter placeholder ${key} has invalid browser metadata`, 'Rebuild the CLI manifest with the current byCLI version.');
+    }
+    const placeholderResolver = cmd.requiresBrowser;
+    let loadedEntry;
+    try {
+        loadedEntry = await loadLazyModule(internal);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CommandExecutionError(`Failed to hydrate conditional adapter ${key}: ${getErrorMessage(error)}`, 'Rebuild or reinstall the adapter so its manifest and module are both available.');
+    }
+    const hydrated = loadedEntry?.registeredCommands.get(key);
+    const invalidReplacement = !hydrated
+        || hydrated === cmd
+        || fullName(hydrated) !== key
+        || hydrated.browser !== 'conditional';
+    if (invalidReplacement) {
+        if (loadedEntry)
+            rollbackCommandRegistration(loadedEntry, key);
+        invalidateLazyModule(internal._modulePath, loadedEntry);
+        throw new CommandExecutionError(`Conditional adapter ${key} did not register a valid hydrated conditional command`, 'Ensure the module registers the same site/name with a browser predicate and is rebuilt with the current byCLI version.');
+    }
+    const hydratedInternal = hydrated;
+    if (typeof hydrated.requiresBrowser !== 'function'
+        || hydrated.requiresBrowser === placeholderResolver
+        || hydratedInternal._hydrateBeforeBrowserRouting === true
+        || hydratedInternal._lazy === true
+        || hydratedInternal._modulePath !== undefined) {
+        if (loadedEntry)
+            rollbackCommandRegistration(loadedEntry, key);
+        invalidateLazyModule(internal._modulePath, loadedEntry);
+        throw new CommandExecutionError(`Conditional adapter ${key} did not register a valid hydrated conditional command`, 'Ensure the module registers the same site/name with a browser predicate and is rebuilt with the current byCLI version.');
+    }
+    assertMatchingArgSchema(cmd, hydrated, loadedEntry);
+    if (loadedEntry)
+        finalizeCommandRegistration(loadedEntry, key);
+    return hydrated;
+}
 function runCommandFunc(cmd, page, kwargs, debug) {
     if (cmd.browser === false)
         return cmd.func(kwargs, debug);
+    if (cmd.browser === 'conditional')
+        return cmd.func(page, kwargs, debug);
     if (!page) {
         throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
     }
     return cmd.func(page, kwargs, debug);
 }
+function resolveBrowserRequirement(cmd, kwargs) {
+    if (cmd.browser !== 'conditional')
+        return cmd.browser;
+    try {
+        return Boolean(cmd.requiresBrowser(kwargs));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CommandExecutionError(`Browser requirement evaluation failed for ${fullName(cmd)}: ${getErrorMessage(error)}`);
+    }
+}
 function resolvePreNav(cmd) {
     if (cmd.navigateBefore === false)
         return null;
@@ -177,16 +373,24 @@ async function shouldRunPreNav(cmd, page, siteSession, preNavUrl) {
     return !urlMatchesDomain(currentUrl, cmd.domain);
 }
 export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
-    let kwargs;
-    try {
-        kwargs = opts.prepared ? rawKwargs : prepareCommandArgs(cmd, rawKwargs);
-    }
-    catch (err) {
-        if (err instanceof ArgumentError)
-            throw err;
-        throw new ArgumentError(getErrorMessage(err));
+    const initialTraceCommand = cmd;
+    let kwargs = opts.prepared
+        ? rawKwargs
+        : prepareCommandArgsOrThrowArgumentError(cmd, rawKwargs);
+    if (cmd._hydrateBeforeBrowserRouting) {
+        cmd = await hydrateConditionalCommand(cmd);
+        // Manifest placeholders cannot serialize adapter validators. The matching
+        // schema above guarantees coercion/defaults stay valid; run only the real
+        // module validator here so custom validation has exactly one side effect.
+        try {
+            cmd.validateArgs?.(kwargs);
+        }
+        catch (error) {
+            if (error instanceof ArgumentError)
+                throw error;
+            throw new ArgumentError(getErrorMessage(error));
+        }
     }
-    const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
     const traceMode = normalizeTraceMode(opts.trace);
     const hookCtx = {
         command: fullName(cmd),
@@ -194,9 +398,12 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
         startedAt: Date.now(),
     };
     await emitHook('onBeforeExecute', hookCtx);
+    kwargs = hookCtx.args;
     let result;
     try {
-        if (shouldUseBrowserSession(cmd)) {
+        const resolvedBrowser = resolveBrowserRequirement(cmd, kwargs);
+        const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
+        if (shouldUseBrowserSession(cmd, resolvedBrowser)) {
             const electron = isElectronApp(cmd.site);
             let cdpEndpoint;
             if (electron) {
@@ -230,7 +437,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                             target: page.getActivePage?.(),
                             site: cmd.site,
                             command: fullName(cmd),
-                            adapterSourcePath: resolveAdapterSourcePath(internal),
+                            adapterSourcePath: resolveAdapterSourcePath(internal)
+                                ?? resolveAdapterSourcePath(initialTraceCommand),
                         },
                     });
                 if (observation) {
@@ -438,6 +646,17 @@ export function prepareCommandArgs(cmd, rawKwargs) {
     cmd.validateArgs?.(kwargs);
     return kwargs;
 }
+/** Prepare adapter arguments using the execution boundary's public error contract. */
+export function prepareCommandArgsOrThrowArgumentError(cmd, rawKwargs) {
+    try {
+        return prepareCommandArgs(cmd, rawKwargs);
+    }
+    catch (err) {
+        if (err instanceof ArgumentError)
+            throw err;
+        throw new ArgumentError(getErrorMessage(err));
+    }
+}
 /**
  * Runtime ceiling padding (seconds) added on top of the user's `--timeout`.
  * The adapter's polling loop typically uses the full user value; the padding

package/dist/src/help.js

@@ -1,5 +1,5 @@
 import yaml from 'js-yaml';
-import { fullName } from './registry.js';
+import { browserRequirementLabel, fullName, hasBrowserCapability } from './registry.js';
 import { formatCommandExample } from './serialization.js';
 const COMMON_OPTIONS = [
     {
@@ -363,12 +363,12 @@ function compactCommand(cmd) {
         usage: formatUsage(cmd),
         access: cmd.access,
         description: cmd.description,
-        browser: !!cmd.browser,
+        browser: cmd.browser,
         ...(cmd.domain ? { domain: cmd.domain } : {}),
         ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
         positionals: positionals(cmd).map(compactArg),
         command_options: commandOptions(cmd).map(compactArg),
-        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
+        ...(hasBrowserCapability(cmd) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         example: formatCommandExample(cmd),
         ...(cmd.siteSession ? { siteSession: cmd.siteSession } : {}),
         ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
@@ -416,7 +416,7 @@ export function siteHelpData(site, commands) {
         command_count: unique.length,
         commands: unique.map(cmd => compactCommand(cmd)),
         common_options: COMMON_OPTIONS.map(compactCommonOption),
-        ...(unique.some(cmd => cmd.browser) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
+        ...(unique.some(hasBrowserCapability) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         next: [
             `bycli ${site} <command> --help -f yaml`,
             `bycli ${site} <command> -f yaml`,
@@ -428,7 +428,7 @@ export function commandHelpData(cmd) {
         site: cmd.site,
         ...compactCommand(cmd),
         common_options: COMMON_OPTIONS.map(compactCommonOption),
-        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
+        ...(hasBrowserCapability(cmd) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
     };
 }
@@ -480,7 +480,7 @@ export function formatSiteHelpText(site, commands) {
         ...formatRows(unique.map(cmd => [formatCommandListTerm(cmd), formatSiteCommandDescription(cmd)])),
         '',
         formatCommonOptionsHelpText(),
-        ...(unique.some(cmd => cmd.browser) ? ['', formatBrowserCommonOptionsHelpText()] : []),
+        ...(unique.some(hasBrowserCapability) ? ['', formatBrowserCommonOptionsHelpText()] : []),
         '',
         `Agent tip: use 'bycli ${site} --help -f yaml' to get all command args/options in one structured response.`,
         '',
@@ -509,11 +509,11 @@ export function formatCommandHelpText(cmd) {
         lines.push('Command options:', ...formatRows(optionRows), '');
     }
     lines.push(formatCommonOptionsHelpText(), '');
-    if (cmd.browser)
+    if (hasBrowserCapability(cmd))
         lines.push(formatBrowserCommonOptionsHelpText(), '');
     const meta = [];
     meta.push(`Access: ${cmd.access}`);
-    meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
+    meta.push(`Browser: ${browserRequirementLabel(cmd)}`);
     if (cmd.domain)
         meta.push(`Domain: ${cmd.domain}`);
     if (cmd.defaultFormat)

package/dist/src/manifest-schema.d.ts

@@ -0,0 +1,9 @@
+import type { Arg } from './registry.js';
+export declare class ManifestSchemaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Canonical execution-relevant argument schema used by both manifest build and
+ * runtime hydration. Objects are key-order independent; arrays remain ordered.
+ */
+export declare function canonicalizeManifestArgSchema(args: readonly Arg[], context: string): string;

package/dist/src/manifest-schema.js

@@ -0,0 +1,162 @@
+export class ManifestSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ManifestSchemaError';
+    }
+}
+function fail(context, path, reason) {
+    throw new ManifestSchemaError(`${context} ${path}: ${reason}`);
+}
+function markSeen(value, context, path, seen) {
+    if (seen.has(value))
+        fail(context, path, 'cyclic or repeated/shared object identities cannot be represented faithfully in JSON');
+    seen.add(value);
+}
+function denseArrayValues(value, context, path) {
+    if (Object.getPrototypeOf(value) !== Array.prototype) {
+        fail(context, path, 'must be a standard JSON array (custom array instances are not supported)');
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        fail(context, path, 'symbol-keyed array properties cannot be represented in JSON');
+    }
+    const propertyNames = Object.getOwnPropertyNames(value);
+    const expectedNames = new Set(['length']);
+    for (let index = 0; index < value.length; index += 1)
+        expectedNames.add(String(index));
+    for (const propertyName of propertyNames) {
+        if (!expectedNames.has(propertyName)) {
+            fail(context, `${path}.${propertyName}`, 'extra array properties cannot be represented in JSON');
+        }
+    }
+    if (propertyNames.length !== expectedNames.size) {
+        fail(context, path, 'sparse arrays cannot be represented faithfully in JSON');
+    }
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
+    if (!lengthDescriptor
+        || !('value' in lengthDescriptor)
+        || lengthDescriptor.value !== value.length
+        || lengthDescriptor.enumerable
+        || lengthDescriptor.configurable
+        || !lengthDescriptor.writable) {
+        fail(context, `${path}.length`, 'non-standard array length descriptors cannot be represented faithfully in JSON');
+    }
+    const values = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor)
+            fail(context, `${path}[${index}]`, 'sparse arrays cannot be represented faithfully in JSON');
+        if (!('value' in descriptor)
+            || !descriptor.enumerable
+            || !descriptor.configurable
+            || !descriptor.writable) {
+            fail(context, `${path}[${index}]`, 'non-standard array item descriptors cannot be represented faithfully in JSON');
+        }
+        values.push(descriptor.value);
+    }
+    return values;
+}
+function canonicalJsonValue(value, context, path, seen) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `string:${JSON.stringify(value)}`;
+    if (typeof value === 'boolean')
+        return `boolean:${value}`;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            fail(context, path, 'must be a finite JSON number');
+        if (Object.is(value, -0))
+            fail(context, path, 'negative zero cannot be represented faithfully in JSON');
+        return `number:${String(value)}`;
+    }
+    if (value === undefined)
+        fail(context, path, 'explicit undefined cannot be represented in JSON');
+    if (typeof value === 'function')
+        fail(context, path, 'functions cannot be represented in JSON');
+    if (typeof value === 'symbol')
+        fail(context, path, 'symbols cannot be represented in JSON');
+    if (typeof value === 'bigint')
+        fail(context, path, 'bigints cannot be represented in JSON');
+    markSeen(value, context, path, seen);
+    {
+        if (Array.isArray(value)) {
+            const items = denseArrayValues(value, context, path)
+                .map((item, index) => canonicalJsonValue(item, context, `${path}[${index}]`, seen));
+            return `array:[${items.join(',')}]`;
+        }
+        if (Object.getPrototypeOf(value) !== Object.prototype) {
+            fail(context, path, 'must be a plain JSON object (Date and custom instances are not supported)');
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            fail(context, path, 'symbol-keyed properties cannot be represented in JSON');
+        }
+        const propertyNames = Object.getOwnPropertyNames(value);
+        const entries = [];
+        for (const key of propertyNames.sort()) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable
+                || !('value' in descriptor)
+                || !descriptor.configurable
+                || !descriptor.writable) {
+                fail(context, `${path}.${key}`, 'only enumerable data properties can be represented faithfully in JSON');
+            }
+            entries.push(`${JSON.stringify(key)}:${canonicalJsonValue(descriptor.value, context, `${path}.${key}`, seen)}`);
+        }
+        return `object:{${entries.join(',')}}`;
+    }
+}
+function optionalBoolean(value, context, path) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        fail(context, path, 'must be a boolean when present');
+    return value;
+}
+/**
+ * Canonical execution-relevant argument schema used by both manifest build and
+ * runtime hydration. Objects are key-order independent; arrays remain ordered.
+ */
+export function canonicalizeManifestArgSchema(args, context) {
+    if (!Array.isArray(args))
+        fail(context, 'args', 'must be a dense array');
+    const seen = new Set();
+    markSeen(args, context, 'args', seen);
+    const argValues = denseArrayValues(args, context, 'args');
+    return argValues.map((arg, index) => {
+        const argContext = `${context} argument "${String(arg.name)}"`;
+        if (typeof arg.name !== 'string' || arg.name.length === 0)
+            fail(argContext, 'name', 'must be a non-empty string');
+        if (arg.type !== undefined && typeof arg.type !== 'string')
+            fail(argContext, 'type', 'must be a string when present');
+        if (arg.help !== undefined && typeof arg.help !== 'string')
+            fail(argContext, 'help', 'must be a string when present');
+        const hasDefault = Object.prototype.hasOwnProperty.call(arg, 'default');
+        const defaultValue = hasDefault
+            ? canonicalJsonValue(arg.default, argContext, 'default', seen)
+            : 'missing';
+        const hasChoices = Object.prototype.hasOwnProperty.call(arg, 'choices');
+        let choices = 'missing';
+        if (hasChoices) {
+            if (!Array.isArray(arg.choices))
+                fail(argContext, 'choices', 'must be an array of strings when present');
+            markSeen(arg.choices, argContext, 'choices', seen);
+            choices = `array:[${denseArrayValues(arg.choices, argContext, 'choices').map((choice, choiceIndex) => {
+                if (typeof choice !== 'string') {
+                    fail(argContext, `choices[${choiceIndex}]`, 'choice values must be strings');
+                }
+                return `string:${JSON.stringify(choice)}`;
+            }).join(',')}]`;
+        }
+        return [
+            `arg:${index}`,
+            `name:${JSON.stringify(arg.name)}`,
+            `type:${JSON.stringify(arg.type ?? 'str')}`,
+            `default:${defaultValue}`,
+            `required:${optionalBoolean(arg.required, argContext, 'required')}`,
+            `valueRequired:${optionalBoolean(arg.valueRequired, argContext, 'valueRequired')}`,
+            `positional:${optionalBoolean(arg.positional, argContext, 'positional')}`,
+            `help:${JSON.stringify(arg.help ?? '')}`,
+            `choices:${choices}`,
+        ].join('|');
+    }).join('||');
+}

package/dist/src/manifest-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/manifest-types.d.ts

@@ -15,7 +15,7 @@ export interface ManifestEntry {
     example?: string;
     domain?: string;
     strategy: string;
-    browser: boolean;
+    browser: boolean | 'conditional';
     args: Array<{
         name: string;
         type?: string;