@unbrained/pm-cli 2026.3.12 → 2026.5.1

package/dist/core/extensions/loader.js

@@ -4,7 +4,27 @@ import { pathToFileURL } from "node:url";
 import { pathExists } from "../fs/fs-utils.js";
 import { resolveGlobalPmRoot } from "../store/paths.js";
 const DEFAULT_EXTENSION_PRIORITY = 100;
-const KNOWN_EXTENSION_CAPABILITIES = ["commands", "renderers", "hooks", "schema", "importers", "search"];
+export const KNOWN_EXTENSION_CAPABILITIES = [
+    "commands",
+    "renderers",
+    "hooks",
+    "schema",
+    "importers",
+    "search",
+    "parser",
+    "preflight",
+    "services",
+];
+export const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;
+export const EXTENSION_CAPABILITY_LEGACY_ALIASES = Object.freeze({
+    migration: "schema",
+    validation: "schema",
+});
+export const EXTENSION_CAPABILITY_CONTRACT = Object.freeze({
+    version: EXTENSION_CAPABILITY_CONTRACT_VERSION,
+    capabilities: [...KNOWN_EXTENSION_CAPABILITIES],
+    legacy_aliases: { ...EXTENSION_CAPABILITY_LEGACY_ALIASES },
+});
 function normalizeNames(values) {
     return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))].sort((a, b) => a.localeCompare(b));
 }
@@ -14,6 +34,151 @@ function isKnownExtensionCapability(value) {
 function collectUnknownExtensionCapabilities(capabilities) {
     return capabilities.filter((capability) => !isKnownExtensionCapability(capability));
 }
+function resolveLegacyExtensionCapabilityAlias(capability) {
+    const normalized = capability.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return null;
+    }
+    return EXTENSION_CAPABILITY_LEGACY_ALIASES[normalized] ?? null;
+}
+function normalizeManifestCapabilities(rawCapabilities) {
+    const normalizedCapabilities = normalizeNames([...rawCapabilities].map((value) => value.toLowerCase()));
+    const remappedCapabilities = [];
+    const legacyAliases = [];
+    for (const capability of normalizedCapabilities) {
+        const legacyAliasTarget = resolveLegacyExtensionCapabilityAlias(capability);
+        if (legacyAliasTarget) {
+            remappedCapabilities.push(legacyAliasTarget);
+            legacyAliases.push({
+                alias: capability,
+                target: legacyAliasTarget,
+            });
+            continue;
+        }
+        remappedCapabilities.push(capability);
+    }
+    const dedupedLegacyAliases = [...new Map(legacyAliases.map((entry) => [`${entry.alias}>${entry.target}`, entry])).values()].sort((left, right) => left.alias.localeCompare(right.alias));
+    return {
+        capabilities: normalizeNames(remappedCapabilities),
+        legacy_aliases: dedupedLegacyAliases,
+    };
+}
+function levenshteinDistance(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left.length === 0) {
+        return right.length;
+    }
+    if (right.length === 0) {
+        return left.length;
+    }
+    const previous = new Array(right.length + 1);
+    const current = new Array(right.length + 1);
+    for (let j = 0; j <= right.length; j += 1) {
+        previous[j] = j;
+    }
+    for (let i = 1; i <= left.length; i += 1) {
+        current[0] = i;
+        for (let j = 1; j <= right.length; j += 1) {
+            const substitutionCost = left[i - 1] === right[j - 1] ? 0 : 1;
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + substitutionCost);
+        }
+        for (let j = 0; j <= right.length; j += 1) {
+            previous[j] = current[j];
+        }
+    }
+    return previous[right.length] ?? left.length;
+}
+function suggestKnownExtensionCapability(capability) {
+    const normalized = capability.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return null;
+    }
+    const legacyAlias = resolveLegacyExtensionCapabilityAlias(normalized);
+    if (legacyAlias) {
+        return legacyAlias;
+    }
+    let bestMatch = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of KNOWN_EXTENSION_CAPABILITIES) {
+        const distance = levenshteinDistance(normalized, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestMatch = candidate;
+        }
+    }
+    const maxDistance = Math.max(1, Math.floor(normalized.length * 0.34));
+    return bestMatch !== null && bestDistance <= maxDistance ? bestMatch : null;
+}
+function formatUnknownExtensionCapabilityWarning(layer, name, capability) {
+    const allowed = KNOWN_EXTENSION_CAPABILITIES.join(",");
+    const suggested = suggestKnownExtensionCapability(capability) ?? "none";
+    return `extension_capability_unknown:${layer}:${name}:${capability}:allowed=${allowed}:suggested=${suggested}`;
+}
+function formatLegacyExtensionCapabilityAliasWarning(layer, name, aliases) {
+    const aliasesToken = aliases.map((entry) => `${entry.alias}>${entry.target}`).join(",");
+    return `extension_capability_legacy_alias:${layer}:${name}:aliases=${aliasesToken}`;
+}
+export function parseUnknownExtensionCapabilityWarning(warning) {
+    const match = /^extension_capability_unknown:(global|project):([^:]+):([^:]+):allowed=([^:]+):suggested=([^:]+)$/.exec(warning.trim());
+    if (!match) {
+        return null;
+    }
+    const [, layerRaw, name, capability, allowedRaw, suggestedRaw] = match;
+    const layer = layerRaw;
+    const allowed_capabilities = allowedRaw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+    const legacyAlias = resolveLegacyExtensionCapabilityAlias(capability);
+    const suggestedFromWarning = suggestedRaw === "none" ? undefined : suggestedRaw;
+    const suggested_capability = suggestedFromWarning ?? legacyAlias ?? undefined;
+    const suggestion_source = suggested_capability
+        ? legacyAlias === suggested_capability
+            ? "legacy_alias"
+            : "nearest_match"
+        : undefined;
+    return {
+        layer,
+        name,
+        capability,
+        allowed_capabilities,
+        capability_contract_version: EXTENSION_CAPABILITY_CONTRACT_VERSION,
+        suggested_capability,
+        suggestion_source,
+        legacy_alias_target: legacyAlias ?? undefined,
+    };
+}
+export function parseLegacyExtensionCapabilityAliasWarning(warning) {
+    const match = /^extension_capability_legacy_alias:(global|project):([^:]+):aliases=(.+)$/.exec(warning.trim());
+    if (!match) {
+        return [];
+    }
+    const [, layerRaw, name, aliasesRaw] = match;
+    const layer = layerRaw;
+    const allowedCapabilities = [...KNOWN_EXTENSION_CAPABILITIES];
+    const parsed = [];
+    for (const token of aliasesRaw.split(",")) {
+        const [rawAlias, rawTarget] = token.split(">");
+        const alias = rawAlias?.trim();
+        const target = rawTarget?.trim().toLowerCase();
+        if (!alias || !target || !isKnownExtensionCapability(target)) {
+            continue;
+        }
+        parsed.push({
+            layer,
+            name,
+            capability: alias,
+            allowed_capabilities: allowedCapabilities,
+            capability_contract_version: EXTENSION_CAPABILITY_CONTRACT_VERSION,
+            suggested_capability: target,
+            suggestion_source: "legacy_alias",
+            legacy_alias_target: target,
+        });
+    }
+    return parsed;
+}
 function parseManifest(raw) {
     if (typeof raw !== "object" || raw === null) {
         return null;
@@ -36,11 +201,14 @@ function parseManifest(raw) {
         priority = candidate.priority;
     }
     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;
         }
-        capabilities = normalizeNames(candidate.capabilities.map((value) => value.toLowerCase()));
+        const normalizedCapabilities = normalizeManifestCapabilities(candidate.capabilities);
+        capabilities = normalizedCapabilities.capabilities;
+        legacyCapabilityAliases = normalizedCapabilities.legacy_aliases;
     }
     return {
         name: candidate.name.trim(),
@@ -48,6 +216,7 @@ function parseManifest(raw) {
         entry: candidate.entry.trim(),
         priority,
         capabilities,
+        legacy_capability_aliases: legacyCapabilityAliases.length > 0 ? legacyCapabilityAliases : undefined,
     };
 }
 function asRecord(value) {
@@ -97,6 +266,21 @@ export function createEmptyExtensionCommandRegistry() {
         handlers: [],
     };
 }
+export function createEmptyExtensionParserRegistry() {
+    return {
+        overrides: [],
+    };
+}
+export function createEmptyExtensionPreflightRegistry() {
+    return {
+        overrides: [],
+    };
+}
+export function createEmptyExtensionServiceRegistry() {
+    return {
+        overrides: [],
+    };
+}
 export function createEmptyExtensionRendererRegistry() {
     return {
         overrides: [],
@@ -104,8 +288,10 @@ export function createEmptyExtensionRendererRegistry() {
 }
 export function createEmptyExtensionRegistrationRegistry() {
     return {
+        commands: [],
         flags: [],
         item_fields: [],
+        item_types: [],
         migrations: [],
         importers: [],
         exporters: [],
@@ -232,8 +418,11 @@ async function scanExtensionDirectory(layer, extensionsRoot, directory, enabled,
         : 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(`extension_capability_unknown:${layer}:${manifest.name}:${capability}`);
+        extensionWarnings.push(formatUnknownExtensionCapabilityWarning(layer, manifest.name, capability));
     }
     if (!entryWithinDirectory) {
         extensionWarnings.push(`extension_entry_outside_extension:${layer}:${manifest.name}`);
@@ -386,6 +575,19 @@ function cloneContextSnapshot(value) {
 function isOutputRendererFormat(value) {
     return value === "toon" || value === "json";
 }
+const EXTENSION_SERVICE_NAMES = [
+    "output_format",
+    "error_format",
+    "help_format",
+    "lock_acquire",
+    "lock_release",
+    "history_append",
+    "item_store_write",
+    "item_store_delete",
+];
+function isExtensionServiceName(value) {
+    return EXTENSION_SERVICE_NAMES.includes(value);
+}
 function assertHookHandler(hookName, hook) {
     if (typeof hook !== "function") {
         throw new TypeError(`api.hooks.${hookName} requires a function handler`);
@@ -440,18 +642,269 @@ function sanitizeRegistrationValue(value) {
     }
     return value;
 }
+function cloneRuntimeRegistrationValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneRuntimeRegistrationValue(entry));
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        const cloned = {};
+        for (const key of Object.keys(record).sort((left, right) => left.localeCompare(right))) {
+            cloned[key] = cloneRuntimeRegistrationValue(record[key]);
+        }
+        return cloned;
+    }
+    return value;
+}
+const EXTENSION_REGISTRATION_TRACE_SYMBOL = Symbol("extension_registration_trace");
+function createRegistrationValidationError(message, trace) {
+    const error = new TypeError(message);
+    Object.defineProperty(error, EXTENSION_REGISTRATION_TRACE_SYMBOL, {
+        value: trace,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return error;
+}
+function extractRegistrationValidationTrace(error) {
+    if (!(error instanceof Error)) {
+        return undefined;
+    }
+    return error[EXTENSION_REGISTRATION_TRACE_SYMBOL];
+}
 function normalizeRegistrationRecord(name, value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new TypeError(`${name} requires an object definition`);
     }
     return sanitizeRegistrationValue(value);
 }
+function normalizeRuntimeRegistrationRecord(name, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${name} requires an object definition`);
+    }
+    return cloneRuntimeRegistrationValue(value);
+}
 function normalizeRegistrationRecordList(name, value) {
     if (!Array.isArray(value)) {
         throw new TypeError(`${name} requires an array of object definitions`);
     }
     return value.map((entry) => normalizeRegistrationRecord(name, entry));
 }
+function asRegistrationRecord(name, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${name} requires an object definition`);
+    }
+    return value;
+}
+function assertOptionalBooleanField(name, value) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw new TypeError(`${name} must be a boolean when provided`);
+    }
+}
+function assertOptionalStringField(name, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${name} must be a non-empty string when provided`);
+    }
+}
+function assertOptionalStringArrayField(name, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        throw new TypeError(`${name} must be an array of non-empty strings when provided`);
+    }
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new TypeError(`${name}[${index}] must be a non-empty string`);
+        }
+    }
+}
+function normalizeOptionalStringArrayField(name, value) {
+    assertOptionalStringArrayField(name, value);
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const entry of value) {
+        const trimmed = entry.trim();
+        if (trimmed.length === 0 || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+function normalizeCommandActionName(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, "-")
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function resolveCommandDefinitionAction(commandPath, action) {
+    if (action === undefined) {
+        return commandPath.replace(/\s+/g, "-");
+    }
+    if (typeof action !== "string" || action.trim().length === 0) {
+        throw new TypeError("registerCommand definition.action must be a non-empty string when provided");
+    }
+    const normalized = normalizeCommandActionName(action);
+    if (normalized.length === 0) {
+        throw new TypeError("registerCommand definition.action must contain alphanumeric characters");
+    }
+    return normalized;
+}
+function normalizeCommandDefinitionArguments(value) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new TypeError("registerCommand definition.arguments must be an array when provided");
+    }
+    const normalized = [];
+    for (const [index, entry] of value.entries()) {
+        const record = asRegistrationRecord(`registerCommand definition.arguments[${index}]`, entry);
+        const name = assertNonEmptyString(`registerCommand definition.arguments[${index}].name`, record.name);
+        assertOptionalBooleanField(`registerCommand definition.arguments[${index}].required`, record.required);
+        assertOptionalBooleanField(`registerCommand definition.arguments[${index}].variadic`, record.variadic);
+        assertOptionalStringField(`registerCommand definition.arguments[${index}].description`, record.description);
+        if (name.includes(" ")) {
+            throw new TypeError(`registerCommand definition.arguments[${index}].name must not contain spaces`);
+        }
+        const definition = {
+            name,
+        };
+        if (record.required === true) {
+            definition.required = true;
+        }
+        if (record.variadic === true) {
+            definition.variadic = true;
+        }
+        if (typeof record.description === "string") {
+            const trimmedDescription = record.description.trim();
+            if (trimmedDescription.length > 0) {
+                definition.description = trimmedDescription;
+            }
+        }
+        normalized.push(definition);
+    }
+    let variadicCount = 0;
+    for (const [index, argument] of normalized.entries()) {
+        if (!argument.variadic) {
+            continue;
+        }
+        variadicCount += 1;
+        if (variadicCount > 1) {
+            throw new TypeError("registerCommand definition.arguments supports at most one variadic argument");
+        }
+        if (index !== normalized.length - 1) {
+            throw new TypeError("registerCommand definition.arguments variadic argument must be the final argument");
+        }
+    }
+    return normalized;
+}
+function validateFlagDefinitions(flags) {
+    if (!Array.isArray(flags)) {
+        throw new TypeError("registerFlags flags requires an array of object definitions");
+    }
+    for (const [index, raw] of flags.entries()) {
+        const record = asRegistrationRecord(`registerFlags flags[${index}]`, raw);
+        const long = record.long;
+        const short = record.short;
+        if (long === undefined && short === undefined) {
+            throw new TypeError(`registerFlags flags[${index}] requires at least one of long or short`);
+        }
+        assertOptionalStringField(`registerFlags flags[${index}].long`, long);
+        assertOptionalStringField(`registerFlags flags[${index}].short`, short);
+        assertOptionalStringField(`registerFlags flags[${index}].value_name`, record.value_name);
+        assertOptionalStringField(`registerFlags flags[${index}].description`, record.description);
+        assertOptionalBooleanField(`registerFlags flags[${index}].required`, record.required);
+        assertOptionalBooleanField(`registerFlags flags[${index}].enabled`, record.enabled);
+        assertOptionalBooleanField(`registerFlags flags[${index}].visible`, record.visible);
+    }
+}
+function validateItemFieldDefinitions(fields) {
+    if (!Array.isArray(fields)) {
+        throw new TypeError("registerItemFields fields requires an array of object definitions");
+    }
+    for (const [index, raw] of fields.entries()) {
+        const record = asRegistrationRecord(`registerItemFields fields[${index}]`, raw);
+        assertNonEmptyString(`registerItemFields fields[${index}].name`, record.name);
+        assertNonEmptyString(`registerItemFields fields[${index}].type`, record.type);
+        assertOptionalBooleanField(`registerItemFields fields[${index}].optional`, record.optional);
+    }
+}
+function validateItemTypeDefinitions(types) {
+    if (!Array.isArray(types)) {
+        throw new TypeError("registerItemTypes types requires an array of object definitions");
+    }
+    for (const [typeIndex, raw] of types.entries()) {
+        const record = asRegistrationRecord(`registerItemTypes types[${typeIndex}]`, raw);
+        assertNonEmptyString(`registerItemTypes types[${typeIndex}].name`, record.name);
+        assertOptionalStringField(`registerItemTypes types[${typeIndex}].folder`, record.folder);
+        assertOptionalStringArrayField(`registerItemTypes types[${typeIndex}].aliases`, record.aliases);
+        assertOptionalStringArrayField(`registerItemTypes types[${typeIndex}].required_create_fields`, record.required_create_fields);
+        assertOptionalStringArrayField(`registerItemTypes types[${typeIndex}].required_create_repeatables`, record.required_create_repeatables);
+        if (record.command_option_policies !== undefined) {
+            if (!Array.isArray(record.command_option_policies)) {
+                throw new TypeError(`registerItemTypes types[${typeIndex}].command_option_policies must be an array when provided`);
+            }
+            for (const [policyIndex, rawPolicy] of record.command_option_policies.entries()) {
+                const policy = asRegistrationRecord(`registerItemTypes types[${typeIndex}].command_option_policies[${policyIndex}]`, rawPolicy);
+                assertNonEmptyString(`registerItemTypes types[${typeIndex}].command_option_policies[${policyIndex}].command`, policy.command);
+                assertNonEmptyString(`registerItemTypes types[${typeIndex}].command_option_policies[${policyIndex}].option`, policy.option);
+                assertOptionalBooleanField(`registerItemTypes types[${typeIndex}].command_option_policies[${policyIndex}].enabled`, policy.enabled);
+                assertOptionalBooleanField(`registerItemTypes types[${typeIndex}].command_option_policies[${policyIndex}].required`, policy.required);
+                assertOptionalBooleanField(`registerItemTypes types[${typeIndex}].command_option_policies[${policyIndex}].visible`, policy.visible);
+            }
+        }
+        if (record.options !== undefined) {
+            if (!Array.isArray(record.options)) {
+                throw new TypeError(`registerItemTypes types[${typeIndex}].options must be an array when provided`);
+            }
+            for (const [optionIndex, rawOption] of record.options.entries()) {
+                const option = asRegistrationRecord(`registerItemTypes types[${typeIndex}].options[${optionIndex}]`, rawOption);
+                assertNonEmptyString(`registerItemTypes types[${typeIndex}].options[${optionIndex}].key`, option.key);
+                assertOptionalStringArrayField(`registerItemTypes types[${typeIndex}].options[${optionIndex}].values`, option.values);
+                assertOptionalBooleanField(`registerItemTypes types[${typeIndex}].options[${optionIndex}].required`, option.required);
+                assertOptionalStringArrayField(`registerItemTypes types[${typeIndex}].options[${optionIndex}].aliases`, option.aliases);
+            }
+        }
+    }
+}
+function validateMigrationDefinition(definition) {
+    const record = asRegistrationRecord("registerMigration definition", definition);
+    if (record.id !== undefined && typeof record.id !== "string") {
+        throw new TypeError("registerMigration definition.id must be a string when provided");
+    }
+    if (record.description !== undefined && typeof record.description !== "string") {
+        throw new TypeError("registerMigration definition.description must be a string when provided");
+    }
+    if (record.status !== undefined && typeof record.status !== "string") {
+        throw new TypeError("registerMigration definition.status must be a string when provided");
+    }
+    assertOptionalBooleanField("registerMigration definition.mandatory", record.mandatory);
+    if (record.run !== undefined && typeof record.run !== "function") {
+        throw new TypeError("registerMigration definition.run must be a function when provided");
+    }
+}
+function attachRuntimeDefinition(entry, runtimeDefinition) {
+    Object.defineProperty(entry, "runtime_definition", {
+        value: runtimeDefinition,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return entry;
+}
 function getDeclaredExtensionCapabilities(extension) {
     if (!Array.isArray(extension.capabilities)) {
         return null;
@@ -477,16 +930,25 @@ function assertExtensionCapability(extension, capability, method) {
         throw new TypeError(`${method} requires capability '${capability}' in extension manifest capabilities`);
     }
 }
-function createExtensionApi(extension, hooks, commands, renderers, registrations) {
+function createExtensionApi(extension, hooks, commands, parsers, preflight, services, renderers, registrations, activationWarnings) {
+    const registerCommandTrace = (mode, command, expectedSchema, received, hint) => ({
+        method: "registerCommand",
+        registration_index: mode === "override" ? commands.overrides.length : commands.handlers.length,
+        command,
+        expected_schema: expectedSchema,
+        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 new TypeError("registerCommand requires a non-empty command name");
+                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") {
-                throw new TypeError("registerCommand requires an override function when command name is provided");
+                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);
             }
             commands.overrides.push({
                 layer: extension.layer,
@@ -497,23 +959,106 @@ function createExtensionApi(extension, hooks, commands, renderers, registrations
             return;
         }
         if (typeof commandOrDefinition !== "object" || commandOrDefinition === null) {
-            throw new TypeError("registerCommand requires a command definition object");
+            throw createRegistrationValidationError("registerCommand requires a command definition object", registerCommandTrace("definition", undefined, "{ name: string; run: (context) => unknown; }", commandOrDefinition, "Use registerCommand({ name: \"command path\", run: (context) => ... })."));
         }
         if (typeof commandOrDefinition.name !== "string") {
-            throw new TypeError("registerCommand requires a command definition name");
+            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."));
         }
         const normalizedCommand = normalizeCommandName(commandOrDefinition.name);
         if (normalizedCommand.length === 0) {
-            throw new TypeError("registerCommand requires a non-empty command definition name");
+            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 (typeof commandOrDefinition.run !== "function") {
-            throw new TypeError("registerCommand requires a command definition run handler");
+        const runHandler = typeof commandOrDefinition.run === "function" ? commandOrDefinition.run : undefined;
+        const legacyHandler = typeof commandOrDefinition.handler === "function" ? commandOrDefinition.handler : undefined;
+        if (!runHandler && legacyHandler) {
+            activationWarnings.push(`extension_command_definition_legacy_handler_alias:${extension.layer}:${extension.name}:${normalizedCommand}`);
+        }
+        const resolvedHandler = runHandler ?? legacyHandler;
+        if (typeof resolvedHandler !== "function") {
+            const trace = registerCommandTrace("definition", normalizedCommand, "{ name: string; run: (context) => unknown; }", commandOrDefinition, "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);
+            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) {
+                assertExtensionCapability(extension, "schema", "registerCommand flags");
+                validateFlagDefinitions(commandOrDefinition.flags);
+                registrations.flags.push({
+                    layer: extension.layer,
+                    name: extension.name,
+                    target_command: normalizedCommand,
+                    flags: normalizeRegistrationRecordList("registerCommand definition.flags", commandOrDefinition.flags),
+                });
+            }
+            const registration = {
+                layer: extension.layer,
+                name: extension.name,
+                command: normalizedCommand,
+                action,
+                examples,
+                failure_hints: failureHints,
+                arguments: argumentsDefinition,
+            };
+            if (description) {
+                registration.description = description;
+            }
+            if (intent) {
+                registration.intent = intent;
+            }
+            registrations.commands.push(registration);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : "registerCommand definition validation failed";
+            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.");
+            throw createRegistrationValidationError(`registerCommand definition metadata invalid (command="${normalizedCommand}", registration_index=${trace.registration_index}): ${reason}`, trace);
         }
         commands.handlers.push({
             layer: extension.layer,
             name: extension.name,
             command: normalizedCommand,
-            run: commandOrDefinition.run,
+            run: resolvedHandler,
+        });
+    };
+    const registerParser = (command, override) => {
+        assertExtensionCapability(extension, "parser", "registerParser");
+        const normalizedCommand = normalizeCommandName(assertNonEmptyString("registerParser command", command));
+        assertFunctionHandler("registerParser override", override);
+        parsers.overrides.push({
+            layer: extension.layer,
+            name: extension.name,
+            command: normalizedCommand,
+            run: override,
+        });
+    };
+    const registerPreflight = (override) => {
+        assertExtensionCapability(extension, "preflight", "registerPreflight");
+        assertFunctionHandler("registerPreflight override", override);
+        preflight.overrides.push({
+            layer: extension.layer,
+            name: extension.name,
+            run: override,
+        });
+    };
+    const registerService = (service, override) => {
+        assertExtensionCapability(extension, "services", "registerService");
+        const normalizedService = String(service).trim().toLowerCase();
+        if (!isExtensionServiceName(normalizedService)) {
+            throw new TypeError(`registerService service must be one of: ${EXTENSION_SERVICE_NAMES.join(", ")}`);
+        }
+        assertFunctionHandler("registerService override", override);
+        services.overrides.push({
+            layer: extension.layer,
+            name: extension.name,
+            service: normalizedService,
+            run: override,
         });
     };
     const registerRenderer = (format, renderer) => {
@@ -535,6 +1080,7 @@ function createExtensionApi(extension, hooks, commands, renderers, registrations
     const registerFlags = (targetCommand, flags) => {
         assertExtensionCapability(extension, "schema", "registerFlags");
         const normalizedTargetCommand = normalizeCommandName(assertNonEmptyString("registerFlags targetCommand", targetCommand));
+        validateFlagDefinitions(flags);
         const normalizedFlags = normalizeRegistrationRecordList("registerFlags flags", flags);
         if (normalizedFlags.length === 0) {
             throw new TypeError("registerFlags requires at least one flag definition");
@@ -548,6 +1094,7 @@ function createExtensionApi(extension, hooks, commands, renderers, registrations
     };
     const registerItemFields = (fields) => {
         assertExtensionCapability(extension, "schema", "registerItemFields");
+        validateItemFieldDefinitions(fields);
         const normalizedFields = normalizeRegistrationRecordList("registerItemFields fields", fields);
         if (normalizedFields.length === 0) {
             throw new TypeError("registerItemFields requires at least one field definition");
@@ -558,13 +1105,28 @@ function createExtensionApi(extension, hooks, commands, renderers, registrations
             fields: normalizedFields,
         });
     };
+    const registerItemTypes = (types) => {
+        assertExtensionCapability(extension, "schema", "registerItemTypes");
+        validateItemTypeDefinitions(types);
+        const normalizedTypes = normalizeRegistrationRecordList("registerItemTypes types", types);
+        if (normalizedTypes.length === 0) {
+            throw new TypeError("registerItemTypes requires at least one type definition");
+        }
+        registrations.item_types.push({
+            layer: extension.layer,
+            name: extension.name,
+            types: normalizedTypes,
+        });
+    };
     const registerMigration = (definition) => {
         assertExtensionCapability(extension, "schema", "registerMigration");
-        registrations.migrations.push({
+        validateMigrationDefinition(definition);
+        const runtimeDefinition = normalizeRuntimeRegistrationRecord("registerMigration definition", definition);
+        registrations.migrations.push(attachRuntimeDefinition({
             layer: extension.layer,
             name: extension.name,
             definition: normalizeRegistrationRecord("registerMigration definition", definition),
-        });
+        }, runtimeDefinition));
     };
     const registerImporter = (name, importer) => {
         assertExtensionCapability(extension, "importers", "registerImporter");
@@ -618,19 +1180,21 @@ function createExtensionApi(extension, hooks, commands, renderers, registrations
     };
     const registerSearchProvider = (provider) => {
         assertExtensionCapability(extension, "search", "registerSearchProvider");
-        registrations.search_providers.push({
+        const runtimeDefinition = normalizeRuntimeRegistrationRecord("registerSearchProvider provider", provider);
+        registrations.search_providers.push(attachRuntimeDefinition({
             layer: extension.layer,
             name: extension.name,
             definition: normalizeRegistrationRecord("registerSearchProvider provider", provider),
-        });
+        }, runtimeDefinition));
     };
     const registerVectorStoreAdapter = (adapter) => {
         assertExtensionCapability(extension, "search", "registerVectorStoreAdapter");
-        registrations.vector_store_adapters.push({
+        const runtimeDefinition = normalizeRuntimeRegistrationRecord("registerVectorStoreAdapter adapter", adapter);
+        registrations.vector_store_adapters.push(attachRuntimeDefinition({
             layer: extension.layer,
             name: extension.name,
             definition: normalizeRegistrationRecord("registerVectorStoreAdapter adapter", adapter),
-        });
+        }, runtimeDefinition));
     };
     const registerBeforeCommand = (hook) => {
         assertExtensionCapability(extension, "hooks", "api.hooks.beforeCommand");
@@ -679,8 +1243,12 @@ function createExtensionApi(extension, hooks, commands, renderers, registrations
     };
     return {
         registerCommand,
+        registerParser,
+        registerPreflight,
+        registerService,
         registerFlags,
         registerItemFields,
+        registerItemTypes,
         registerMigration,
         registerRenderer,
         registerImporter,
@@ -709,11 +1277,15 @@ async function executeRegisteredHooks(entries, hookName, context) {
     return warnings;
 }
 function getRegistrationCounts(registrations) {
+    const commandCount = registrations.commands.length;
     const flagCount = registrations.flags.reduce((total, entry) => total + entry.flags.length, 0);
     const itemFieldCount = registrations.item_fields.reduce((total, entry) => total + entry.fields.length, 0);
+    const itemTypeCount = registrations.item_types.reduce((total, entry) => total + entry.types.length, 0);
     return {
+        commands: commandCount,
         flags: flagCount,
         item_fields: itemFieldCount,
+        item_types: itemTypeCount,
         migrations: registrations.migrations.length,
         importers: registrations.importers.length,
         exporters: registrations.exporters.length,
@@ -721,9 +1293,110 @@ function getRegistrationCounts(registrations) {
         vector_store_adapters: registrations.vector_store_adapters.length,
     };
 }
+function collectCommandCollisionWarnings(commands) {
+    const warnings = [];
+    const collectByCommand = (entries, codePrefix) => {
+        const grouped = new Map();
+        for (const entry of entries) {
+            const bucket = grouped.get(entry.command) ?? [];
+            bucket.push(entry);
+            grouped.set(entry.command, bucket);
+        }
+        for (const command of [...grouped.keys()].sort((left, right) => left.localeCompare(right))) {
+            const bucket = grouped.get(command) ?? [];
+            if (bucket.length <= 1) {
+                continue;
+            }
+            const winner = bucket[bucket.length - 1];
+            for (const displaced of bucket.slice(0, -1)) {
+                warnings.push(`${codePrefix}:${command}:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+            }
+        }
+    };
+    collectByCommand(commands.handlers, "extension_command_handler_collision");
+    collectByCommand(commands.overrides, "extension_command_override_collision");
+    const handlerCommands = new Set(commands.handlers.map((entry) => entry.command));
+    const overlapCommands = [...new Set(commands.overrides.map((entry) => entry.command))]
+        .filter((command) => handlerCommands.has(command))
+        .sort((left, right) => left.localeCompare(right));
+    for (const command of overlapCommands) {
+        warnings.push(`extension_command_override_handler_overlap:${command}`);
+    }
+    return warnings;
+}
+function collectRendererCollisionWarnings(renderers) {
+    const grouped = new Map();
+    for (const entry of renderers.overrides) {
+        const bucket = grouped.get(entry.format) ?? [];
+        bucket.push(entry);
+        grouped.set(entry.format, bucket);
+    }
+    const warnings = [];
+    for (const format of [...grouped.keys()].sort((left, right) => left.localeCompare(right))) {
+        const bucket = grouped.get(format) ?? [];
+        if (bucket.length <= 1) {
+            continue;
+        }
+        const winner = bucket[bucket.length - 1];
+        for (const displaced of bucket.slice(0, -1)) {
+            warnings.push(`extension_renderer_collision:${format}:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+        }
+    }
+    return warnings;
+}
+function collectParserCollisionWarnings(parsers) {
+    const warnings = [];
+    const grouped = new Map();
+    for (const entry of parsers.overrides) {
+        const bucket = grouped.get(entry.command) ?? [];
+        bucket.push(entry);
+        grouped.set(entry.command, bucket);
+    }
+    for (const command of [...grouped.keys()].sort((left, right) => left.localeCompare(right))) {
+        const bucket = grouped.get(command) ?? [];
+        if (bucket.length <= 1) {
+            continue;
+        }
+        const winner = bucket[bucket.length - 1];
+        for (const displaced of bucket.slice(0, -1)) {
+            warnings.push(`extension_parser_override_collision:${command}:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+        }
+    }
+    return warnings;
+}
+function collectPreflightCollisionWarnings(preflight) {
+    if (preflight.overrides.length <= 1) {
+        return [];
+    }
+    const winner = preflight.overrides[preflight.overrides.length - 1];
+    return preflight.overrides.slice(0, -1).map((displaced) => `extension_preflight_override_collision:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+}
+function collectServiceCollisionWarnings(services) {
+    const warnings = [];
+    const grouped = new Map();
+    for (const entry of services.overrides) {
+        const bucket = grouped.get(entry.service) ?? [];
+        bucket.push(entry);
+        grouped.set(entry.service, bucket);
+    }
+    for (const service of [...grouped.keys()].sort((left, right) => left.localeCompare(right))) {
+        const bucket = grouped.get(service) ?? [];
+        if (bucket.length <= 1) {
+            continue;
+        }
+        const winner = bucket[bucket.length - 1];
+        for (const displaced of bucket.slice(0, -1)) {
+            warnings.push(`extension_service_override_collision:${service}:${winner.layer}:${winner.name}:${displaced.layer}:${displaced.name}`);
+        }
+    }
+    return warnings;
+}
 export async function activateExtensions(loadResult) {
     const hooks = createEmptyExtensionHookRegistry();
     const commands = createEmptyExtensionCommandRegistry();
+    const parsers = createEmptyExtensionParserRegistry();
+    const preflight = createEmptyExtensionPreflightRegistry();
+    const services = createEmptyExtensionServiceRegistry();
     const renderers = createEmptyExtensionRendererRegistry();
     const registrations = createEmptyExtensionRegistrationRegistry();
     const failed = [];
@@ -734,25 +1407,38 @@ export async function activateExtensions(loadResult) {
             continue;
         }
         try {
-            await activatable.activate(createExtensionApi(extension, hooks, commands, renderers, registrations));
+            await activatable.activate(createExtensionApi(extension, hooks, commands, parsers, preflight, services, renderers, registrations, warnings));
         }
         catch (error) {
             warnings.push(`extension_activate_failed:${extension.layer}:${extension.name}`);
+            const trace = extractRegistrationValidationTrace(error);
             failed.push({
                 layer: extension.layer,
                 name: extension.name,
                 entry_path: extension.entry_path,
                 error: formatUnknownError(error),
+                trace,
             });
         }
     }
+    const collisionWarnings = [
+        ...collectCommandCollisionWarnings(commands),
+        ...collectParserCollisionWarnings(parsers),
+        ...collectPreflightCollisionWarnings(preflight),
+        ...collectServiceCollisionWarnings(services),
+        ...collectRendererCollisionWarnings(renderers),
+    ];
+    const mergedWarnings = [...new Set([...warnings, ...collisionWarnings])];
     return {
         hooks,
         commands,
+        parsers,
+        preflight,
+        services,
         renderers,
         registrations,
         failed,
-        warnings,
+        warnings: mergedWarnings,
         hook_counts: {
             before_command: hooks.beforeCommand.length,
             after_command: hooks.afterCommand.length,
@@ -762,6 +1448,9 @@ export async function activateExtensions(loadResult) {
         },
         command_override_count: commands.overrides.length,
         command_handler_count: commands.handlers.length,
+        parser_override_count: parsers.overrides.length,
+        preflight_override_count: preflight.overrides.length,
+        service_override_count: services.overrides.length,
         renderer_override_count: renderers.overrides.length,
         registration_counts: getRegistrationCounts(registrations),
     };
@@ -820,6 +1509,208 @@ export async function runCommandHandler(commands, context) {
         };
     }
 }
+export async function runParserOverride(parsers, context) {
+    const command = normalizeCommandName(context.command);
+    if (command.length === 0) {
+        return {
+            overridden: false,
+            context: {
+                command,
+                args: cloneContextSnapshot(context.args),
+                options: cloneCommandOptionsSnapshot(context.options),
+                global: cloneGlobalOptionsSnapshot(context.global),
+                pm_root: context.pm_root,
+            },
+            warnings: [],
+        };
+    }
+    const matched = [...parsers.overrides].reverse().find((entry) => entry.command === command);
+    if (!matched) {
+        return {
+            overridden: false,
+            context: {
+                command,
+                args: cloneContextSnapshot(context.args),
+                options: cloneCommandOptionsSnapshot(context.options),
+                global: cloneGlobalOptionsSnapshot(context.global),
+                pm_root: context.pm_root,
+            },
+            warnings: [],
+        };
+    }
+    try {
+        const delta = (await Promise.resolve(matched.run({
+            command,
+            args: cloneContextSnapshot(context.args),
+            options: cloneCommandOptionsSnapshot(context.options),
+            global: cloneGlobalOptionsSnapshot(context.global),
+            pm_root: context.pm_root,
+        }))) ?? {};
+        const nextArgs = Array.isArray(delta.args) ? cloneContextSnapshot(delta.args) : cloneContextSnapshot(context.args);
+        const nextOptions = delta.options ? cloneCommandOptionsSnapshot(delta.options) : cloneCommandOptionsSnapshot(context.options);
+        const nextGlobal = delta.global ? cloneGlobalOptionsSnapshot(delta.global) : cloneGlobalOptionsSnapshot(context.global);
+        return {
+            overridden: true,
+            context: {
+                command,
+                args: nextArgs,
+                options: nextOptions,
+                global: nextGlobal,
+                pm_root: context.pm_root,
+            },
+            warnings: [],
+        };
+    }
+    catch {
+        return {
+            overridden: false,
+            context: {
+                command,
+                args: cloneContextSnapshot(context.args),
+                options: cloneCommandOptionsSnapshot(context.options),
+                global: cloneGlobalOptionsSnapshot(context.global),
+                pm_root: context.pm_root,
+            },
+            warnings: [`extension_parser_override_failed:${matched.layer}:${matched.name}:${matched.command}`],
+        };
+    }
+}
+export async function runPreflightOverride(preflight, context) {
+    const matched = [...preflight.overrides].reverse()[0];
+    const baseContext = {
+        command: normalizeCommandName(context.command),
+        args: cloneContextSnapshot(context.args),
+        options: cloneCommandOptionsSnapshot(context.options),
+        global: cloneGlobalOptionsSnapshot(context.global),
+        pm_root: context.pm_root,
+    };
+    const baseDecision = cloneContextSnapshot(context.decision);
+    if (!matched) {
+        return {
+            overridden: false,
+            context: baseContext,
+            decision: baseDecision,
+            warnings: [],
+        };
+    }
+    try {
+        const delta = (await Promise.resolve(matched.run({
+            command: baseContext.command,
+            args: cloneContextSnapshot(baseContext.args),
+            options: cloneCommandOptionsSnapshot(baseContext.options),
+            global: cloneGlobalOptionsSnapshot(baseContext.global),
+            pm_root: baseContext.pm_root,
+            decision: cloneContextSnapshot(baseDecision),
+        }))) ?? {};
+        const nextContext = {
+            command: baseContext.command,
+            args: Array.isArray(delta.args) ? cloneContextSnapshot(delta.args) : baseContext.args,
+            options: delta.options ? cloneCommandOptionsSnapshot(delta.options) : baseContext.options,
+            global: delta.global ? cloneGlobalOptionsSnapshot(delta.global) : baseContext.global,
+            pm_root: baseContext.pm_root,
+        };
+        const nextDecision = {
+            enforce_item_format_gate: typeof delta.enforce_item_format_gate === "boolean"
+                ? delta.enforce_item_format_gate
+                : baseDecision.enforce_item_format_gate,
+            run_preflight_item_format_sync: typeof delta.run_preflight_item_format_sync === "boolean"
+                ? delta.run_preflight_item_format_sync
+                : baseDecision.run_preflight_item_format_sync,
+            run_extension_migrations: typeof delta.run_extension_migrations === "boolean"
+                ? delta.run_extension_migrations
+                : baseDecision.run_extension_migrations,
+            enforce_mandatory_migration_gate: typeof delta.enforce_mandatory_migration_gate === "boolean"
+                ? delta.enforce_mandatory_migration_gate
+                : baseDecision.enforce_mandatory_migration_gate,
+        };
+        return {
+            overridden: true,
+            context: nextContext,
+            decision: nextDecision,
+            warnings: [],
+        };
+    }
+    catch {
+        return {
+            overridden: false,
+            context: baseContext,
+            decision: baseDecision,
+            warnings: [`extension_preflight_override_failed:${matched.layer}:${matched.name}`],
+        };
+    }
+}
+function resolveDefaultServiceResult(context) {
+    return {
+        handled: false,
+        result: context.payload,
+        warnings: [],
+    };
+}
+export function runServiceOverrideSync(services, context) {
+    const matched = [...services.overrides].reverse().find((entry) => entry.service === context.service);
+    if (!matched) {
+        return resolveDefaultServiceResult(context);
+    }
+    try {
+        const result = matched.run({
+            service: context.service,
+            command: context.command ? normalizeCommandName(context.command) : undefined,
+            args: context.args ? cloneContextSnapshot(context.args) : undefined,
+            options: context.options ? cloneCommandOptionsSnapshot(context.options) : undefined,
+            global: context.global ? cloneGlobalOptionsSnapshot(context.global) : undefined,
+            pm_root: context.pm_root,
+            payload: cloneContextSnapshot(context.payload),
+        });
+        if (result instanceof Promise) {
+            return {
+                handled: false,
+                result: context.payload,
+                warnings: [`extension_service_override_async_unsupported:${matched.layer}:${matched.name}:${matched.service}`],
+            };
+        }
+        return {
+            handled: true,
+            result,
+            warnings: [],
+        };
+    }
+    catch {
+        return {
+            handled: false,
+            result: context.payload,
+            warnings: [`extension_service_override_failed:${matched.layer}:${matched.name}:${matched.service}`],
+        };
+    }
+}
+export async function runServiceOverride(services, context) {
+    const matched = [...services.overrides].reverse().find((entry) => entry.service === context.service);
+    if (!matched) {
+        return resolveDefaultServiceResult(context);
+    }
+    try {
+        const result = await Promise.resolve(matched.run({
+            service: context.service,
+            command: context.command ? normalizeCommandName(context.command) : undefined,
+            args: context.args ? cloneContextSnapshot(context.args) : undefined,
+            options: context.options ? cloneCommandOptionsSnapshot(context.options) : undefined,
+            global: context.global ? cloneGlobalOptionsSnapshot(context.global) : undefined,
+            pm_root: context.pm_root,
+            payload: cloneContextSnapshot(context.payload),
+        }));
+        return {
+            handled: true,
+            result,
+            warnings: [],
+        };
+    }
+    catch {
+        return {
+            handled: false,
+            result: context.payload,
+            warnings: [`extension_service_override_failed:${matched.layer}:${matched.name}:${matched.service}`],
+        };
+    }
+}
 export function runCommandOverride(commands, context) {
     const command = normalizeCommandName(context.command);
     if (command.length === 0) {