@unbrained/pm-cli 2026.6.30 → 2026.7.1

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a323e13b-37e3-5ec6-bc21-1ab78e0b30b9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c04aa899-5cba-5907-be3e-4db7c63b7f13")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -72,33 +72,151 @@ function parseManifestEngines(value) {
     }
     return Object.keys(engines).length > 0 ? engines : undefined;
 }
-function parseManifest(raw) {
-    if (typeof raw !== "object" || raw === null) {
+/** Parse a required manifest string field, returning `null` when it is absent, non-string, or blank. */
+function parseRequiredManifestString(candidate, field) {
+    const value = candidate[field];
+    if (typeof value !== "string" || value.trim().length === 0) {
         return null;
     }
-    const candidate = raw;
-    if (typeof candidate.name !== "string" || candidate.name.trim().length === 0) {
+    return value.trim();
+}
+/** Parse an optional integer value (`undefined` when absent, `null` when present but not an integer). */
+function parseOptionalIntegerValue(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
         return null;
     }
-    if (typeof candidate.version !== "string" || candidate.version.trim().length === 0) {
+    return value;
+}
+/** Parse an optional boolean value (`undefined` when absent, `null` when present but not a boolean). */
+function parseOptionalBooleanValue(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
         return null;
     }
-    if (typeof candidate.entry !== "string" || candidate.entry.trim().length === 0) {
+    return value;
+}
+/** Parse the optional integer `priority`, defaulting to {@link DEFAULT_EXTENSION_PRIORITY} when absent and rejecting (`null`) a non-integer. */
+function parseManifestPriority(candidate) {
+    const value = parseOptionalIntegerValue(candidate.priority);
+    return value === undefined ? DEFAULT_EXTENSION_PRIORITY : value;
+}
+/** Parse the optional `sandbox_profile`, rejecting (`null`) any value that does not round-trip through {@link normalizePolicySandboxProfile}. */
+function parseManifestSandboxProfile(candidate) {
+    const value = candidate.sandbox_profile;
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
         return null;
     }
-    let priority = DEFAULT_EXTENSION_PRIORITY;
-    if ("priority" in candidate && candidate.priority !== undefined && candidate.priority !== null) {
-        if (typeof candidate.priority !== "number" || !Number.isInteger(candidate.priority)) {
-            return null;
-        }
-        priority = candidate.priority;
+    const normalizedProfile = normalizePolicySandboxProfile(value);
+    if (normalizedProfile !== value.trim().toLowerCase()) {
+        return null;
     }
-    let manifestVersion;
-    if ("manifest_version" in candidate && candidate.manifest_version !== undefined && candidate.manifest_version !== null) {
-        if (typeof candidate.manifest_version !== "number" || !Number.isInteger(candidate.manifest_version)) {
-            return null;
-        }
-        manifestVersion = candidate.manifest_version;
+    return normalizedProfile;
+}
+/** Return the trimmed string when `value` is a non-blank string, otherwise `undefined`. */
+function optionalTrimmedString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+/** Parse the optional `provenance` record (`undefined` absent, `null` malformed), keeping only the present trimmed string fields and a boolean `verified`. */
+function parseManifestProvenance(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const provenanceRecord = asRecordLoose(value);
+    if (!provenanceRecord) {
+        return null;
+    }
+    const source = optionalTrimmedString(provenanceRecord.source);
+    const signature = optionalTrimmedString(provenanceRecord.signature);
+    const attestation = optionalTrimmedString(provenanceRecord.attestation);
+    const verified = provenanceRecord.verified === undefined || provenanceRecord.verified === null
+        ? undefined
+        : typeof provenanceRecord.verified === "boolean"
+            ? provenanceRecord.verified
+            : null;
+    if (verified === null) {
+        return null;
+    }
+    return {
+        ...(source ? { source } : {}),
+        ...(signature ? { signature } : {}),
+        ...(attestation ? { attestation } : {}),
+        ...(typeof verified === "boolean" ? { verified } : {}),
+    };
+}
+/** Parse the optional `permissions` record (`undefined` absent, `null` malformed), keeping only the boolean grants that are present. */
+function parseManifestPermissions(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const permissionsRecord = asRecordLoose(value);
+    if (!permissionsRecord) {
+        return null;
+    }
+    const fsRead = parseOptionalBooleanValue(permissionsRecord.fs_read);
+    const fsWrite = parseOptionalBooleanValue(permissionsRecord.fs_write);
+    const network = parseOptionalBooleanValue(permissionsRecord.network);
+    const envRead = parseOptionalBooleanValue(permissionsRecord.env_read);
+    const envWrite = parseOptionalBooleanValue(permissionsRecord.env_write);
+    const processSpawn = parseOptionalBooleanValue(permissionsRecord.process_spawn);
+    if ([fsRead, fsWrite, network, envRead, envWrite, processSpawn].includes(null)) {
+        return null;
+    }
+    return {
+        ...(typeof fsRead === "boolean" ? { fs_read: fsRead } : {}),
+        ...(typeof fsWrite === "boolean" ? { fs_write: fsWrite } : {}),
+        ...(typeof network === "boolean" ? { network } : {}),
+        ...(typeof envRead === "boolean" ? { env_read: envRead } : {}),
+        ...(typeof envWrite === "boolean" ? { env_write: envWrite } : {}),
+        ...(typeof processSpawn === "boolean" ? { process_spawn: processSpawn } : {}),
+    };
+}
+/** Parse the optional `capabilities` array, normalizing legacy aliases; returns empty lists when absent and `null` when the field is not a string array. */
+function parseManifestCapabilities(value) {
+    if (value === undefined || value === null) {
+        return { capabilities: [], legacy_aliases: [] };
+    }
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        return null;
+    }
+    const normalizedCapabilities = normalizeManifestCapabilities(value);
+    return { capabilities: normalizedCapabilities.capabilities, legacy_aliases: normalizedCapabilities.legacy_aliases };
+}
+/** Parse the optional `activation` block, returning the de-duplicated sorted `commands` set, `undefined` when no command activation is declared, and `null` when the block is malformed. */
+function parseManifestActivation(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const activationRecord = asRecordLoose(value);
+    if (!activationRecord) {
+        return null;
+    }
+    const rawCommands = activationRecord.commands;
+    if (rawCommands === undefined || rawCommands === null) {
+        return undefined;
+    }
+    if (!Array.isArray(rawCommands) || rawCommands.some((entry) => typeof entry !== "string")) {
+        return null;
+    }
+    const commands = [
+        ...new Set(rawCommands
+            .map((entry) => normalizeCommandName(entry))
+            .filter((entry) => entry.length > 0)),
+    ].sort((left, right) => left.localeCompare(right));
+    return commands.length > 0 ? { commands } : undefined;
+}
+/** Parse every optional manifest metadata field, returning `null` as soon as any one is malformed. */
+function parseManifestMetadata(candidate) {
+    const manifestVersion = parseOptionalIntegerValue(candidate.manifest_version);
+    if (manifestVersion === null) {
+        return null;
     }
     const pmMinVersion = parseOptionalManifestString(candidate, "pm_min_version");
     if (pmMinVersion === null) {
@@ -112,136 +230,85 @@ function parseManifest(raw) {
     if (engines === null) {
         return null;
     }
-    let trusted;
-    if ("trusted" in candidate && candidate.trusted !== undefined && candidate.trusted !== null) {
-        if (typeof candidate.trusted !== "boolean") {
-            return null;
-        }
-        trusted = candidate.trusted;
+    const trusted = parseOptionalBooleanValue(candidate.trusted);
+    if (trusted === null) {
+        return null;
     }
-    let sandboxProfile;
-    if ("sandbox_profile" in candidate && candidate.sandbox_profile !== undefined && candidate.sandbox_profile !== null) {
-        if (typeof candidate.sandbox_profile !== "string") {
-            return null;
-        }
-        const normalizedProfile = normalizePolicySandboxProfile(candidate.sandbox_profile);
-        if (normalizedProfile !== candidate.sandbox_profile.trim().toLowerCase()) {
-            return null;
-        }
-        sandboxProfile = normalizedProfile;
+    const sandboxProfile = parseManifestSandboxProfile(candidate);
+    if (sandboxProfile === null) {
+        return null;
     }
-    let provenance;
-    if ("provenance" in candidate && candidate.provenance !== undefined && candidate.provenance !== null) {
-        const provenanceRecord = asRecordLoose(candidate.provenance);
-        if (!provenanceRecord) {
-            return null;
-        }
-        const source = typeof provenanceRecord.source === "string" && provenanceRecord.source.trim().length > 0
-            ? provenanceRecord.source.trim()
-            : undefined;
-        const signature = typeof provenanceRecord.signature === "string" && provenanceRecord.signature.trim().length > 0
-            ? provenanceRecord.signature.trim()
-            : undefined;
-        const attestation = typeof provenanceRecord.attestation === "string" && provenanceRecord.attestation.trim().length > 0
-            ? provenanceRecord.attestation.trim()
-            : undefined;
-        const verified = provenanceRecord.verified === undefined || provenanceRecord.verified === null
-            ? undefined
-            : typeof provenanceRecord.verified === "boolean"
-                ? provenanceRecord.verified
-                : null;
-        if (verified === null) {
-            return null;
-        }
-        provenance = {
-            ...(source ? { source } : {}),
-            ...(signature ? { signature } : {}),
-            ...(attestation ? { attestation } : {}),
-            ...(typeof verified === "boolean" ? { verified } : {}),
-        };
+    const provenance = parseManifestProvenance(candidate.provenance);
+    if (provenance === null) {
+        return null;
     }
-    let permissions;
-    if ("permissions" in candidate && candidate.permissions !== undefined && candidate.permissions !== null) {
-        const permissionsRecord = asRecordLoose(candidate.permissions);
-        if (!permissionsRecord) {
-            return null;
-        }
-        const parseOptionalBoolean = (value) => {
-            if (value === undefined || value === null) {
-                return undefined;
-            }
-            if (typeof value !== "boolean") {
-                return null;
-            }
-            return value;
-        };
-        const fsRead = parseOptionalBoolean(permissionsRecord.fs_read);
-        const fsWrite = parseOptionalBoolean(permissionsRecord.fs_write);
-        const network = parseOptionalBoolean(permissionsRecord.network);
-        const envRead = parseOptionalBoolean(permissionsRecord.env_read);
-        const envWrite = parseOptionalBoolean(permissionsRecord.env_write);
-        const processSpawn = parseOptionalBoolean(permissionsRecord.process_spawn);
-        if ([fsRead, fsWrite, network, envRead, envWrite, processSpawn].includes(null)) {
-            return null;
-        }
-        permissions = {
-            ...(typeof fsRead === "boolean" ? { fs_read: fsRead } : {}),
-            ...(typeof fsWrite === "boolean" ? { fs_write: fsWrite } : {}),
-            ...(typeof network === "boolean" ? { network } : {}),
-            ...(typeof envRead === "boolean" ? { env_read: envRead } : {}),
-            ...(typeof envWrite === "boolean" ? { env_write: envWrite } : {}),
-            ...(typeof processSpawn === "boolean" ? { process_spawn: processSpawn } : {}),
-        };
+    const permissions = parseManifestPermissions(candidate.permissions);
+    if (permissions === null) {
+        return null;
     }
-    let capabilities = [];
-    let legacyCapabilityAliases = [];
-    if ("capabilities" in candidate && candidate.capabilities !== undefined && candidate.capabilities !== null) {
-        if (!Array.isArray(candidate.capabilities) || candidate.capabilities.some((value) => typeof value !== "string")) {
-            return null;
-        }
-        const normalizedCapabilities = normalizeManifestCapabilities(candidate.capabilities);
-        capabilities = normalizedCapabilities.capabilities;
-        legacyCapabilityAliases = normalizedCapabilities.legacy_aliases;
+    const capabilities = parseManifestCapabilities(candidate.capabilities);
+    if (capabilities === null) {
+        return null;
     }
-    let activation;
-    if ("activation" in candidate && candidate.activation !== undefined && candidate.activation !== null) {
-        const activationRecord = asRecordLoose(candidate.activation);
-        if (!activationRecord) {
-            return null;
-        }
-        const rawCommands = activationRecord.commands;
-        if (rawCommands !== undefined && rawCommands !== null) {
-            if (!Array.isArray(rawCommands) || rawCommands.some((value) => typeof value !== "string")) {
-                return null;
-            }
-            const commands = [
-                ...new Set(rawCommands
-                    .map((value) => normalizeCommandName(value))
-                    .filter((value) => value.length > 0)),
-            ].sort((left, right) => left.localeCompare(right));
-            if (commands.length > 0) {
-                activation = {
-                    commands,
-                };
-            }
-        }
+    const activation = parseManifestActivation(candidate.activation);
+    if (activation === null) {
+        return null;
     }
     return {
-        name: candidate.name.trim(),
-        version: candidate.version.trim(),
-        entry: candidate.entry.trim(),
-        priority,
         manifest_version: manifestVersion,
         pm_min_version: pmMinVersion,
         pm_max_version: pmMaxVersion,
         engines,
         trusted,
-        provenance,
         sandbox_profile: sandboxProfile,
+        provenance,
         permissions,
+        capabilities: capabilities.capabilities,
+        legacy_capability_aliases: capabilities.legacy_aliases,
         activation,
-        capabilities,
-        legacy_capability_aliases: legacyCapabilityAliases.length > 0 ? legacyCapabilityAliases : undefined,
+    };
+}
+function parseManifest(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return null;
+    }
+    const candidate = raw;
+    const name = parseRequiredManifestString(candidate, "name");
+    if (name === null) {
+        return null;
+    }
+    const version = parseRequiredManifestString(candidate, "version");
+    if (version === null) {
+        return null;
+    }
+    const entry = parseRequiredManifestString(candidate, "entry");
+    if (entry === null) {
+        return null;
+    }
+    const priority = parseManifestPriority(candidate);
+    if (priority === null) {
+        return null;
+    }
+    const metadata = parseManifestMetadata(candidate);
+    if (metadata === null) {
+        return null;
+    }
+    return {
+        name,
+        version,
+        entry,
+        priority,
+        manifest_version: metadata.manifest_version,
+        pm_min_version: metadata.pm_min_version,
+        pm_max_version: metadata.pm_max_version,
+        engines: metadata.engines,
+        trusted: metadata.trusted,
+        provenance: metadata.provenance,
+        sandbox_profile: metadata.sandbox_profile,
+        permissions: metadata.permissions,
+        activation: metadata.activation,
+        capabilities: metadata.capabilities,
+        legacy_capability_aliases: metadata.legacy_capability_aliases.length > 0 ? metadata.legacy_capability_aliases : undefined,
     };
 }
 function shouldEnable(name, enabled, disabled) {
@@ -380,26 +447,61 @@ async function scanExtensionLayer(layer, extensionsRoot, enabled, disabled, pmMa
     }
     return { diagnostics, warnings, candidates };
 }
+/**
+ * Build the `warn`-status scan result for a directory whose manifest is missing
+ * or unparseable, carrying the supplied diagnostic warning and no candidate.
+ */
+function buildUnavailableExtensionScan(layer, directory, manifestPath, warning) {
+    return {
+        diagnostic: {
+            layer,
+            directory,
+            manifest_path: manifestPath,
+            name: null,
+            version: null,
+            entry: null,
+            priority: null,
+            entry_path: null,
+            enabled: null,
+            status: "warn",
+        },
+        warnings: [warning],
+        candidate: null,
+    };
+}
+/**
+ * Collect the non-fatal load warnings for a parsed extension manifest, in
+ * detection order: legacy capability aliases, unknown capabilities, an entry
+ * outside or absent from the extension directory, then the pm version
+ * floor/ceiling incompatibility warnings.
+ */
+function collectScannedExtensionWarnings(layer, manifest, entryWithinDirectory, entryExists, pmVersionCompatibility, pmMaxVersionCompatibility) {
+    const extensionWarnings = [];
+    if (Array.isArray(manifest.legacy_capability_aliases) && manifest.legacy_capability_aliases.length > 0) {
+        extensionWarnings.push(formatLegacyExtensionCapabilityAliasWarning(layer, manifest.name, manifest.legacy_capability_aliases));
+    }
+    for (const capability of collectUnknownExtensionCapabilities(manifest.capabilities)) {
+        extensionWarnings.push(formatUnknownExtensionCapabilityWarning(layer, manifest.name, capability));
+    }
+    if (!entryWithinDirectory) {
+        extensionWarnings.push(`extension_entry_outside_extension:${layer}:${manifest.name}`);
+    }
+    else if (!entryExists) {
+        extensionWarnings.push(`extension_entry_missing:${layer}:${manifest.name}`);
+    }
+    if (pmVersionCompatibility.warning) {
+        extensionWarnings.push(pmVersionCompatibility.warning);
+    }
+    if (pmMaxVersionCompatibility.warning) {
+        extensionWarnings.push(pmMaxVersionCompatibility.warning);
+    }
+    return extensionWarnings;
+}
 async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled, disabled, managedSourcePackages, pmMaxVersionExceededMode) {
     const extensionDir = path.join(extensionsRoot, directory);
     const manifestPath = path.join(extensionDir, "manifest.json");
     if (!(await pathExists(manifestPath))) {
-        return {
-            diagnostic: {
-                layer,
-                directory,
-                manifest_path: manifestPath,
-                name: null,
-                version: null,
-                entry: null,
-                priority: null,
-                entry_path: null,
-                enabled: null,
-                status: "warn",
-            },
-            warnings: [`extension_manifest_missing:${layer}:${directory}`],
-            candidate: null,
-        };
+        return buildUnavailableExtensionScan(layer, directory, manifestPath, `extension_manifest_missing:${layer}:${directory}`);
     }
     let manifest = null;
     try {
@@ -410,22 +512,7 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
         manifest = null;
     }
     if (!manifest) {
-        return {
-            diagnostic: {
-                layer,
-                directory,
-                manifest_path: manifestPath,
-                name: null,
-                version: null,
-                entry: null,
-                priority: null,
-                entry_path: null,
-                enabled: null,
-                status: "warn",
-            },
-            warnings: [`extension_manifest_invalid:${layer}:${directory}`],
-            candidate: null,
-        };
+        return buildUnavailableExtensionScan(layer, directory, manifestPath, `extension_manifest_invalid:${layer}:${directory}`);
     }
     const entryPath = path.resolve(extensionDir, manifest.entry);
     const entryWithinDirectoryByPath = isPathWithinDirectory(extensionDir, entryPath);
@@ -434,27 +521,9 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
         ? await isCanonicalPathWithinDirectory(extensionDir, entryPath)
         : entryWithinDirectoryByPath;
     const enabledForLoad = shouldEnable(manifest.name, enabled, disabled);
-    const extensionWarnings = [];
-    if (Array.isArray(manifest.legacy_capability_aliases) && manifest.legacy_capability_aliases.length > 0) {
-        extensionWarnings.push(formatLegacyExtensionCapabilityAliasWarning(layer, manifest.name, manifest.legacy_capability_aliases));
-    }
-    for (const capability of collectUnknownExtensionCapabilities(manifest.capabilities)) {
-        extensionWarnings.push(formatUnknownExtensionCapabilityWarning(layer, manifest.name, capability));
-    }
-    if (!entryWithinDirectory) {
-        extensionWarnings.push(`extension_entry_outside_extension:${layer}:${manifest.name}`);
-    }
-    else if (!entryExists) {
-        extensionWarnings.push(`extension_entry_missing:${layer}:${manifest.name}`);
-    }
     const pmVersionCompatibility = await evaluatePmMinVersionCompatibility(layer, manifest);
-    if (pmVersionCompatibility.warning) {
-        extensionWarnings.push(pmVersionCompatibility.warning);
-    }
     const pmMaxVersionCompatibility = await evaluatePmMaxVersionCompatibility(layer, manifest, pmMaxVersionExceededMode);
-    if (pmMaxVersionCompatibility.warning) {
-        extensionWarnings.push(pmMaxVersionCompatibility.warning);
-    }
+    const extensionWarnings = collectScannedExtensionWarnings(layer, manifest, entryWithinDirectory, entryExists, pmVersionCompatibility, pmMaxVersionCompatibility);
     const extensionReady = entryWithinDirectory &&
         entryExists &&
         pmVersionCompatibility.allowed &&
@@ -1374,69 +1443,70 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
         received: sanitizeRegistrationValue(received),
         hint,
     });
-    const registerCommand = (commandOrDefinition, override) => {
-        assertExtensionCapability(extension, "commands", "registerCommand");
-        if (typeof commandOrDefinition === "string") {
-            const normalizedCommand = normalizeCommandName(commandOrDefinition);
-            if (normalizedCommand.length === 0) {
-                throw createRegistrationValidationError("registerCommand requires a non-empty command name", registerCommandTrace("override", commandOrDefinition, 'registerCommand("<command>", (context) => unknown)', commandOrDefinition, "Provide a non-empty command path as the first argument."));
-            }
-            if (typeof override !== "function") {
-                const trace = registerCommandTrace("override", normalizedCommand, 'registerCommand("<command>", (context) => unknown)', { command: commandOrDefinition, override }, "Provide a function as the second registerCommand argument.");
-                throw createRegistrationValidationError(`registerCommand requires an override function when command name is provided (command="${normalizedCommand}", registration_index=${trace.registration_index})`, trace);
-            }
-            if (!allowRegistration("commands.override", "registerCommand", "commands", { command: normalizedCommand })) {
-                return;
-            }
-            commands.overrides.push({
-                layer: extension.layer,
-                name: extension.name,
-                command: normalizedCommand,
-                run: override,
-            });
-            return;
-        }
-        if (typeof commandOrDefinition !== "object" || commandOrDefinition === null) {
-            throw createRegistrationValidationError("registerCommand requires a command definition object", registerCommandTrace("definition", undefined, "{ name: string; run: (context) => unknown; }", commandOrDefinition, "Use registerCommand({ name: \"command path\", run: (context) => ... })."));
+    const registerCommandOverride = (command, override) => {
+        const normalizedCommand = normalizeCommandName(command);
+        if (normalizedCommand.length === 0) {
+            throw createRegistrationValidationError("registerCommand requires a non-empty command name", registerCommandTrace("override", command, 'registerCommand("<command>", (context) => unknown)', command, "Provide a non-empty command path as the first argument."));
         }
-        if (typeof commandOrDefinition.name !== "string") {
-            throw createRegistrationValidationError("registerCommand requires a command definition name", registerCommandTrace("definition", undefined, "{ name: string; run: (context) => unknown; }", commandOrDefinition, "Set command definition.name to a non-empty string command path."));
+        if (typeof override !== "function") {
+            const trace = registerCommandTrace("override", normalizedCommand, 'registerCommand("<command>", (context) => unknown)', { command, override }, "Provide a function as the second registerCommand argument.");
+            throw createRegistrationValidationError(`registerCommand requires an override function when command name is provided (command="${normalizedCommand}", registration_index=${trace.registration_index})`, trace);
         }
-        const normalizedCommand = normalizeCommandName(commandOrDefinition.name);
-        if (normalizedCommand.length === 0) {
-            throw createRegistrationValidationError("registerCommand requires a non-empty command definition name", registerCommandTrace("definition", commandOrDefinition.name, "{ name: string; run: (context) => unknown; }", commandOrDefinition, "Ensure command definition.name contains a non-empty command path."));
+        if (!allowRegistration("commands.override", "registerCommand", "commands", { command: normalizedCommand })) {
+            return;
         }
-        const runHandler = typeof commandOrDefinition.run === "function" ? commandOrDefinition.run : undefined;
-        const legacyHandler = typeof commandOrDefinition.handler === "function" ? commandOrDefinition.handler : undefined;
+        commands.overrides.push({
+            layer: extension.layer,
+            name: extension.name,
+            command: normalizedCommand,
+            run: override,
+        });
+    };
+    const resolveCommandDefinitionRunHandler = (definition, normalizedCommand) => {
+        const runHandler = typeof definition.run === "function" ? definition.run : undefined;
+        const legacyHandler = typeof definition.handler === "function" ? definition.handler : undefined;
         if (!runHandler && legacyHandler) {
             activationWarnings.push(`extension_command_definition_legacy_handler_alias:${extension.layer}:${extension.name}:${normalizedCommand}`);
         }
-        const resolvedHandler = runHandler ?? legacyHandler;
+        return runHandler ?? legacyHandler;
+    };
+    const registerCommandDefinition = (definition) => {
+        if (typeof definition !== "object" || definition === null) {
+            throw createRegistrationValidationError("registerCommand requires a command definition object", registerCommandTrace("definition", undefined, "{ name: string; run: (context) => unknown; }", definition, "Use registerCommand({ name: \"command path\", run: (context) => ... })."));
+        }
+        if (typeof definition.name !== "string") {
+            throw createRegistrationValidationError("registerCommand requires a command definition name", registerCommandTrace("definition", undefined, "{ name: string; run: (context) => unknown; }", definition, "Set command definition.name to a non-empty string command path."));
+        }
+        const normalizedCommand = normalizeCommandName(definition.name);
+        if (normalizedCommand.length === 0) {
+            throw createRegistrationValidationError("registerCommand requires a non-empty command definition name", registerCommandTrace("definition", definition.name, "{ name: string; run: (context) => unknown; }", definition, "Ensure command definition.name contains a non-empty command path."));
+        }
+        const resolvedHandler = resolveCommandDefinitionRunHandler(definition, normalizedCommand);
         if (typeof resolvedHandler !== "function") {
-            const trace = registerCommandTrace("definition", normalizedCommand, "{ name: string; run: (context) => unknown; }", commandOrDefinition, "Define command definition.run as a function.");
+            const trace = registerCommandTrace("definition", normalizedCommand, "{ name: string; run: (context) => unknown; }", definition, "Define command definition.run as a function.");
             throw createRegistrationValidationError(`registerCommand requires a command definition run handler (command="${normalizedCommand}", registration_index=${trace.registration_index})`, trace);
         }
         try {
-            assertOptionalStringField("registerCommand definition.action", commandOrDefinition.action);
-            assertOptionalStringField("registerCommand definition.description", commandOrDefinition.description);
-            assertOptionalStringField("registerCommand definition.intent", commandOrDefinition.intent);
-            const action = resolveCommandDefinitionAction(normalizedCommand, commandOrDefinition.action);
+            assertOptionalStringField("registerCommand definition.action", definition.action);
+            assertOptionalStringField("registerCommand definition.description", definition.description);
+            assertOptionalStringField("registerCommand definition.intent", definition.intent);
+            const action = resolveCommandDefinitionAction(normalizedCommand, definition.action);
             if (!allowRegistration("commands.handler", "registerCommand", "commands", { command: normalizedCommand, action })) {
                 return;
             }
-            const description = commandOrDefinition.description?.trim();
-            const intent = commandOrDefinition.intent?.trim();
-            const examples = normalizeOptionalStringArrayField("registerCommand definition.examples", commandOrDefinition.examples);
-            const failureHints = normalizeOptionalStringArrayField("registerCommand definition.failure_hints", commandOrDefinition.failure_hints);
-            const argumentsDefinition = normalizeCommandDefinitionArguments(commandOrDefinition.arguments);
-            if (commandOrDefinition.flags !== undefined) {
+            const description = definition.description?.trim();
+            const intent = definition.intent?.trim();
+            const examples = normalizeOptionalStringArrayField("registerCommand definition.examples", definition.examples);
+            const failureHints = normalizeOptionalStringArrayField("registerCommand definition.failure_hints", definition.failure_hints);
+            const argumentsDefinition = normalizeCommandDefinitionArguments(definition.arguments);
+            if (definition.flags !== undefined) {
                 assertExtensionCapability(extension, "schema", "registerCommand flags");
-                validateFlagDefinitions(commandOrDefinition.flags);
+                validateFlagDefinitions(definition.flags);
                 registrations.flags.push({
                     layer: extension.layer,
                     name: extension.name,
                     target_command: normalizedCommand,
-                    flags: normalizeRegistrationRecordList("registerCommand definition.flags", commandOrDefinition.flags),
+                    flags: normalizeRegistrationRecordList("registerCommand definition.flags", definition.flags),
                 });
             }
             const registration = {
@@ -1459,7 +1529,7 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
         }
         catch (error) {
             const reason = formatUnknownError(error);
-            const trace = registerCommandTrace("definition", normalizedCommand, "{ name: string; run: (context) => unknown; action?: string; arguments?: object[]; flags?: object[]; }", commandOrDefinition, "Use schema-style metadata (action/arguments/flags/examples/intent) with valid values.");
+            const trace = registerCommandTrace("definition", normalizedCommand, "{ name: string; run: (context) => unknown; action?: string; arguments?: object[]; flags?: object[]; }", definition, "Use schema-style metadata (action/arguments/flags/examples/intent) with valid values.");
             throw createRegistrationValidationError(`registerCommand definition metadata invalid (command="${normalizedCommand}", registration_index=${trace.registration_index}): ${reason}`, trace);
         }
         commands.handlers.push({
@@ -1469,6 +1539,14 @@ function createExtensionApi(extension, hooks, commands, parsers, preflight, serv
             run: resolvedHandler,
         });
     };
+    const registerCommand = (commandOrDefinition, override) => {
+        assertExtensionCapability(extension, "commands", "registerCommand");
+        if (typeof commandOrDefinition === "string") {
+            registerCommandOverride(commandOrDefinition, override);
+            return;
+        }
+        registerCommandDefinition(commandOrDefinition);
+    };
     const registerParser = (command, override) => {
         assertExtensionCapability(extension, "parser", "registerParser");
         if (!allowRegistration("parser.override", "registerParser", "parser")) {
@@ -2063,4 +2141,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=a323e13b-37e3-5ec6-bc21-1ab78e0b30b9
+//# debugId=c04aa899-5cba-5907-be3e-4db7c63b7f13