@unbrained/pm-cli 2026.3.12 → 2026.5.1-2

package/dist/core/extensions/loader.d.ts

@@ -1,5 +1,16 @@
-import type { PmSettings } from "../../types/index.js";
+import type { ItemDocument, PmSettings } from "../../types/index.js";
 import type { GlobalOptions } from "../shared/command-types.js";
+export declare const KNOWN_EXTENSION_CAPABILITIES: readonly ["commands", "renderers", "hooks", "schema", "importers", "search", "parser", "preflight", "services"];
+type ExtensionCapability = (typeof KNOWN_EXTENSION_CAPABILITIES)[number];
+export declare const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;
+export declare const EXTENSION_CAPABILITY_LEGACY_ALIASES: Readonly<Record<string, ExtensionCapability>>;
+export declare const EXTENSION_CAPABILITY_CONTRACT: Readonly<{
+    version: 2;
+    capabilities: ("search" | "schema" | "commands" | "renderers" | "hooks" | "importers" | "parser" | "preflight" | "services")[];
+    legacy_aliases: {
+        [x: string]: "search" | "schema" | "commands" | "renderers" | "hooks" | "importers" | "parser" | "preflight" | "services";
+    };
+}>;
 export type ExtensionLayer = "global" | "project";
 type ExtensionStatus = "ok" | "warn";
 export interface ExtensionManifest {
@@ -8,6 +19,7 @@ export interface ExtensionManifest {
     entry: string;
     priority: number;
     capabilities: string[];
+    legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];
 }
 export interface ExtensionDiagnostic {
     layer: ExtensionLayer;
@@ -60,11 +72,14 @@ export interface ExtensionLoadResult extends ExtensionDiscoveryResult {
 export interface BeforeCommandHookContext {
     command: string;
     args: string[];
+    options?: Record<string, unknown>;
+    global?: GlobalOptions;
     pm_root: string;
 }
 export interface AfterCommandHookContext extends BeforeCommandHookContext {
     ok: boolean;
     error?: string;
+    result?: unknown;
 }
 export interface OnWriteHookContext {
     path: string;
@@ -88,6 +103,9 @@ export type OutputRendererFormat = "toon" | "json";
 export type CommandOverride = (context: CommandOverrideContext) => unknown;
 export type RendererOverride = (context: RendererOverrideContext) => string;
 export type CommandHandler = (context: CommandHandlerContext) => unknown;
+export type ParserOverride = (context: ParserOverrideContext) => ParserOverrideDelta | Promise<ParserOverrideDelta>;
+export type PreflightOverride = (context: PreflightOverrideContext) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;
+export type ServiceOverride = (context: ServiceOverrideContext) => unknown;
 export interface RegisteredExtensionHook<THook> {
     layer: ExtensionLayer;
     name: string;
@@ -124,17 +142,205 @@ export interface CommandHandlerContext {
     global: GlobalOptions;
     pm_root: string;
 }
+export interface ParserOverrideContext extends CommandHandlerContext {
+}
+export interface ParserOverrideDelta {
+    args?: string[];
+    options?: Record<string, unknown>;
+    global?: GlobalOptions;
+}
+export interface PreflightOverrideContext extends CommandHandlerContext {
+    decision: PreflightRuntimeDecision;
+}
+export interface PreflightRuntimeDecision {
+    enforce_item_format_gate: boolean;
+    run_preflight_item_format_sync: boolean;
+    run_extension_migrations: boolean;
+    enforce_mandatory_migration_gate: boolean;
+}
+export interface PreflightOverrideDelta extends ParserOverrideDelta {
+    enforce_item_format_gate?: boolean;
+    run_preflight_item_format_sync?: boolean;
+    run_extension_migrations?: boolean;
+    enforce_mandatory_migration_gate?: boolean;
+}
+export type ExtensionServiceName = "output_format" | "error_format" | "help_format" | "lock_acquire" | "lock_release" | "history_append" | "item_store_write" | "item_store_delete";
+export interface ServiceOverrideContext {
+    service: ExtensionServiceName;
+    command?: string;
+    args?: string[];
+    options?: Record<string, unknown>;
+    global?: GlobalOptions;
+    pm_root?: string;
+    payload: unknown;
+}
+export interface ExtensionCommandArgumentDefinition {
+    name: string;
+    required?: boolean;
+    variadic?: boolean;
+    description?: string;
+}
 export interface CommandDefinition {
     name: string;
-    run: CommandHandler;
+    run?: CommandHandler;
+    /**
+     * @deprecated Use `run` instead. This alias remains for backward compatibility.
+     */
+    handler?: CommandHandler;
+    action?: string;
+    description?: string;
+    intent?: string;
+    examples?: string[];
+    failure_hints?: string[];
+    arguments?: ExtensionCommandArgumentDefinition[];
+    flags?: FlagDefinition[];
+}
+export type FlagValueType = "string" | "number" | "boolean";
+export interface FlagDefinition {
+    long?: string;
+    short?: string;
+    value_name?: string;
+    description?: string;
+    required?: boolean;
+    enabled?: boolean;
+    visible?: boolean;
+    type?: FlagValueType;
+    value_type?: FlagValueType;
+    [key: string]: unknown;
+}
+export interface SchemaFieldDefinition {
+    name: string;
+    type: string;
+    optional?: boolean;
+    [key: string]: unknown;
+}
+export interface SchemaItemTypeCommandOptionPolicyDefinition {
+    command: string;
+    option: string;
+    enabled?: boolean;
+    required?: boolean;
+    visible?: boolean;
+    [key: string]: unknown;
+}
+export interface SchemaItemTypeOptionDefinition {
+    key: string;
+    values?: string[];
+    required?: boolean;
+    aliases?: string[];
+    [key: string]: unknown;
+}
+export interface SchemaItemTypeDefinition {
+    name: string;
+    folder?: string;
+    aliases?: string[];
+    required_create_fields?: string[];
+    required_create_repeatables?: string[];
+    command_option_policies?: SchemaItemTypeCommandOptionPolicyDefinition[];
+    options?: SchemaItemTypeOptionDefinition[];
+    [key: string]: unknown;
+}
+export interface SchemaMigrationRunContext {
+    id: string;
+    command: "migration";
+    layer: ExtensionLayer;
+    extension: string;
+    pm_root: string;
+    status: string;
+}
+export type SchemaMigrationRunner = (context: SchemaMigrationRunContext) => unknown | Promise<unknown>;
+export interface SchemaMigrationDefinition {
+    id?: string;
+    description?: string;
+    status?: string;
+    mandatory?: boolean;
+    run?: SchemaMigrationRunner;
+    [key: string]: unknown;
+}
+export interface ImportExportContext {
+    registration: string;
+    action: "import" | "export";
+    command: string;
+    args: string[];
+    options: Record<string, unknown>;
+    global: GlobalOptions;
+    pm_root: string;
+}
+export type Importer = (context: ImportExportContext) => unknown | Promise<unknown>;
+export type Exporter = (context: ImportExportContext) => unknown | Promise<unknown>;
+export type ExtensionSearchMode = "keyword" | "semantic" | "hybrid";
+export interface SearchProviderQueryContext {
+    query: string;
+    mode: ExtensionSearchMode;
+    tokens: string[];
+    options: Record<string, unknown>;
+    settings: PmSettings;
+    documents: ItemDocument[];
+    [key: string]: unknown;
+}
+export interface SearchProviderHit {
+    id: string;
+    score: number;
+    matched_fields?: string[];
+    [key: string]: unknown;
+}
+export type SearchProviderQueryResult = SearchProviderHit[] | {
+    hits?: SearchProviderHit[];
+};
+export interface SearchProviderEmbedBatchContext {
+    inputs: string[];
+    settings: PmSettings;
+    model: string;
+    [key: string]: unknown;
+}
+export interface SearchProviderEmbedContext {
+    input: string;
+    settings: PmSettings;
+    model: string;
+    [key: string]: unknown;
+}
+export interface SearchProviderDefinition {
+    name: string;
+    query?: (context: SearchProviderQueryContext) => SearchProviderQueryResult | Promise<SearchProviderQueryResult>;
+    embedBatch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;
+    embed_batch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;
+    embed?: (context: SearchProviderEmbedContext) => number[] | Promise<number[]>;
+    [key: string]: unknown;
+}
+export interface VectorStoreQueryHit {
+    id: string;
+    score: number;
+    payload?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface VectorStoreQueryContext {
+    vector: number[];
+    limit: number;
+    settings: PmSettings;
+    [key: string]: unknown;
+}
+export interface VectorStoreUpsertPoint {
+    id: string;
+    vector: number[];
+    payload?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface VectorStoreUpsertContext {
+    points: VectorStoreUpsertPoint[];
+    settings: PmSettings;
+    [key: string]: unknown;
+}
+export interface VectorStoreDeleteContext {
+    ids: string[];
+    settings: PmSettings;
+    [key: string]: unknown;
+}
+export interface VectorStoreAdapterDefinition {
+    name: string;
+    query?: (context: VectorStoreQueryContext) => VectorStoreQueryHit[] | Promise<VectorStoreQueryHit[]>;
+    upsert?: (context: VectorStoreUpsertContext) => unknown | Promise<unknown>;
+    delete?: (context: VectorStoreDeleteContext) => unknown | Promise<unknown>;
+    [key: string]: unknown;
 }
-export type FlagDefinition = Record<string, unknown>;
-export type SchemaFieldDefinition = Record<string, unknown>;
-export type SchemaMigrationDefinition = Record<string, unknown>;
-export type SearchProviderDefinition = Record<string, unknown>;
-export type VectorStoreAdapterDefinition = Record<string, unknown>;
-export type Importer = (context: unknown) => unknown;
-export type Exporter = (context: unknown) => unknown;
 export interface RegisteredExtensionCommandOverride {
     layer: ExtensionLayer;
     name: string;
@@ -147,6 +353,23 @@ export interface RegisteredExtensionCommandHandler {
     command: string;
     run: CommandHandler;
 }
+export interface RegisteredExtensionParserOverride {
+    layer: ExtensionLayer;
+    name: string;
+    command: string;
+    run: ParserOverride;
+}
+export interface RegisteredExtensionPreflightOverride {
+    layer: ExtensionLayer;
+    name: string;
+    run: PreflightOverride;
+}
+export interface RegisteredExtensionServiceOverride {
+    layer: ExtensionLayer;
+    name: string;
+    service: ExtensionServiceName;
+    run: ServiceOverride;
+}
 export interface RegisteredExtensionRendererOverride {
     layer: ExtensionLayer;
     name: string;
@@ -157,6 +380,15 @@ export interface ExtensionCommandRegistry {
     overrides: RegisteredExtensionCommandOverride[];
     handlers: RegisteredExtensionCommandHandler[];
 }
+export interface ExtensionParserRegistry {
+    overrides: RegisteredExtensionParserOverride[];
+}
+export interface ExtensionPreflightRegistry {
+    overrides: RegisteredExtensionPreflightOverride[];
+}
+export interface ExtensionServiceRegistry {
+    overrides: RegisteredExtensionServiceOverride[];
+}
 export interface ExtensionRendererRegistry {
     overrides: RegisteredExtensionRendererOverride[];
 }
@@ -166,15 +398,32 @@ export interface RegisteredExtensionFlagDefinitions {
     target_command: string;
     flags: FlagDefinition[];
 }
+export interface RegisteredExtensionCommandDefinition {
+    layer: ExtensionLayer;
+    name: string;
+    command: string;
+    action: string;
+    description?: string;
+    intent?: string;
+    examples: string[];
+    failure_hints: string[];
+    arguments: ExtensionCommandArgumentDefinition[];
+}
 export interface RegisteredExtensionSchemaFieldDefinitions {
     layer: ExtensionLayer;
     name: string;
     fields: SchemaFieldDefinition[];
 }
+export interface RegisteredExtensionSchemaItemTypeDefinitions {
+    layer: ExtensionLayer;
+    name: string;
+    types: SchemaItemTypeDefinition[];
+}
 export interface RegisteredExtensionSchemaMigrationDefinition {
     layer: ExtensionLayer;
     name: string;
     definition: SchemaMigrationDefinition;
+    runtime_definition: SchemaMigrationDefinition;
 }
 export interface RegisteredExtensionImporter {
     layer: ExtensionLayer;
@@ -190,15 +439,19 @@ export interface RegisteredExtensionSearchProvider {
     layer: ExtensionLayer;
     name: string;
     definition: SearchProviderDefinition;
+    runtime_definition: SearchProviderDefinition;
 }
 export interface RegisteredExtensionVectorStoreAdapter {
     layer: ExtensionLayer;
     name: string;
     definition: VectorStoreAdapterDefinition;
+    runtime_definition: VectorStoreAdapterDefinition;
 }
 export interface ExtensionRegistrationRegistry {
+    commands: RegisteredExtensionCommandDefinition[];
     flags: RegisteredExtensionFlagDefinitions[];
     item_fields: RegisteredExtensionSchemaFieldDefinitions[];
+    item_types: RegisteredExtensionSchemaItemTypeDefinitions[];
     migrations: RegisteredExtensionSchemaMigrationDefinition[];
     importers: RegisteredExtensionImporter[];
     exporters: RegisteredExtensionExporter[];
@@ -206,8 +459,10 @@ export interface ExtensionRegistrationRegistry {
     vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];
 }
 export interface ExtensionRegistrationCounts {
+    commands: number;
     flags: number;
     item_fields: number;
+    item_types: number;
     migrations: number;
     importers: number;
     exporters: number;
@@ -217,8 +472,12 @@ export interface ExtensionRegistrationCounts {
 export interface ExtensionApi {
     registerCommand(command: string, override: CommandOverride): void;
     registerCommand(definition: CommandDefinition): void;
+    registerParser(command: string, override: ParserOverride): void;
+    registerPreflight(override: PreflightOverride): void;
+    registerService(service: ExtensionServiceName, override: ServiceOverride): void;
     registerFlags(targetCommand: string, flags: FlagDefinition[]): void;
     registerItemFields(fields: SchemaFieldDefinition[]): void;
+    registerItemTypes(types: SchemaItemTypeDefinition[]): void;
     registerMigration(definition: SchemaMigrationDefinition): void;
     registerRenderer(format: OutputRendererFormat, renderer: RendererOverride): void;
     registerImporter(name: string, importer: Importer): void;
@@ -238,10 +497,22 @@ export interface FailedExtensionActivation {
     name: string;
     entry_path: string;
     error: string;
+    trace?: ExtensionActivationFailureTrace;
+}
+export interface ExtensionActivationFailureTrace {
+    method: string;
+    registration_index: number;
+    command?: string;
+    expected_schema: string;
+    received?: unknown;
+    hint?: string;
 }
 export interface ExtensionActivationResult {
     hooks: ExtensionHookRegistry;
     commands: ExtensionCommandRegistry;
+    parsers: ExtensionParserRegistry;
+    preflight: ExtensionPreflightRegistry;
+    services: ExtensionServiceRegistry;
     renderers: ExtensionRendererRegistry;
     registrations: ExtensionRegistrationRegistry;
     failed: FailedExtensionActivation[];
@@ -255,15 +526,37 @@ export interface ExtensionActivationResult {
     };
     command_override_count: number;
     command_handler_count: number;
+    parser_override_count: number;
+    preflight_override_count: number;
+    service_override_count: number;
     renderer_override_count: number;
     registration_counts: ExtensionRegistrationCounts;
 }
+export interface LegacyExtensionCapabilityAliasMapping {
+    alias: string;
+    target: ExtensionCapability;
+}
+export interface UnknownExtensionCapabilityWarningDetails {
+    layer: ExtensionLayer;
+    name: string;
+    capability: string;
+    allowed_capabilities: string[];
+    capability_contract_version: number;
+    suggested_capability?: string;
+    suggestion_source?: "legacy_alias" | "nearest_match";
+    legacy_alias_target?: string;
+}
+export declare function parseUnknownExtensionCapabilityWarning(warning: string): UnknownExtensionCapabilityWarningDetails | null;
+export declare function parseLegacyExtensionCapabilityAliasWarning(warning: string): UnknownExtensionCapabilityWarningDetails[];
 export declare function resolveExtensionRoots(pmRoot: string, cwd?: string): {
     global: string;
     project: string;
 };
 export declare function createEmptyExtensionHookRegistry(): ExtensionHookRegistry;
 export declare function createEmptyExtensionCommandRegistry(): ExtensionCommandRegistry;
+export declare function createEmptyExtensionParserRegistry(): ExtensionParserRegistry;
+export declare function createEmptyExtensionPreflightRegistry(): ExtensionPreflightRegistry;
+export declare function createEmptyExtensionServiceRegistry(): ExtensionServiceRegistry;
 export declare function createEmptyExtensionRendererRegistry(): ExtensionRendererRegistry;
 export declare function createEmptyExtensionRegistrationRegistry(): ExtensionRegistrationRegistry;
 interface DiscoverExtensionsOptions {
@@ -291,6 +584,26 @@ export interface CommandHandlerResult {
     warnings: string[];
 }
 export declare function runCommandHandler(commands: ExtensionCommandRegistry, context: CommandHandlerContext): Promise<CommandHandlerResult>;
+export interface ParserOverrideResult {
+    overridden: boolean;
+    context: CommandHandlerContext;
+    warnings: string[];
+}
+export declare function runParserOverride(parsers: ExtensionParserRegistry, context: ParserOverrideContext): Promise<ParserOverrideResult>;
+export interface PreflightOverrideResult {
+    overridden: boolean;
+    context: CommandHandlerContext;
+    decision: PreflightRuntimeDecision;
+    warnings: string[];
+}
+export declare function runPreflightOverride(preflight: ExtensionPreflightRegistry, context: PreflightOverrideContext): Promise<PreflightOverrideResult>;
+export interface ServiceOverrideResult {
+    handled: boolean;
+    result: unknown;
+    warnings: string[];
+}
+export declare function runServiceOverrideSync(services: ExtensionServiceRegistry, context: ServiceOverrideContext): ServiceOverrideResult;
+export declare function runServiceOverride(services: ExtensionServiceRegistry, context: ServiceOverrideContext): Promise<ServiceOverrideResult>;
 export declare function runCommandOverride(commands: ExtensionCommandRegistry, context: CommandOverrideContext): CommandOverrideResult;
 export interface RendererOverrideResult {
     overridden: boolean;