@unbrained/pm-cli 2026.5.1 → 2026.5.2

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import "./cli/main.js";
+export {};

package/dist/cli.js

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
-import "./cli/main.js";
+import { ensureSentryInit } from "./core/sentry/instrument.js";
+await ensureSentryInit();
+await import("./cli/main.js");
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,eAAe,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"/","sources":["cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,MAAM,gBAAgB,EAAE,CAAC;AACzB,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { ensureSentryInit } from \"./core/sentry/instrument.js\";\n\nawait ensureSentryInit();\nawait import(\"./cli/main.js\");\n"]}

package/dist/core/extensions/extension-types.d.ts

@@ -0,0 +1,605 @@
+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"];
+export 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";
+export type ExtensionStatus = "ok" | "warn";
+export interface ExtensionManifest {
+    name: string;
+    version: string;
+    entry: string;
+    priority: number;
+    capabilities: string[];
+    legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];
+}
+export interface ExtensionDiagnostic {
+    layer: ExtensionLayer;
+    directory: string;
+    manifest_path: string;
+    name: string | null;
+    version: string | null;
+    entry: string | null;
+    priority: number | null;
+    entry_path: string | null;
+    enabled: boolean | null;
+    status: ExtensionStatus;
+}
+export interface EffectiveExtension {
+    layer: ExtensionLayer;
+    directory: string;
+    manifest_path: string;
+    name: string;
+    version: string;
+    entry: string;
+    priority: number;
+    entry_path: string;
+    capabilities?: string[];
+}
+export interface ExtensionDiscoveryResult {
+    disabled_by_flag: boolean;
+    roots: {
+        global: string;
+        project: string;
+    };
+    configured_enabled: string[];
+    configured_disabled: string[];
+    discovered: ExtensionDiagnostic[];
+    effective: EffectiveExtension[];
+    warnings: string[];
+}
+export interface LoadedExtension extends EffectiveExtension {
+    module: unknown;
+}
+export interface FailedExtensionLoad {
+    layer: ExtensionLayer;
+    name: string;
+    entry_path: string;
+    error: string;
+}
+export interface ExtensionLoadResult extends ExtensionDiscoveryResult {
+    loaded: LoadedExtension[];
+    failed: FailedExtensionLoad[];
+}
+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;
+    scope: "project" | "global";
+    op: string;
+}
+export interface OnReadHookContext {
+    path: string;
+    scope: "project" | "global";
+}
+export interface OnIndexHookContext {
+    mode: string;
+    total_items?: number;
+}
+export type BeforeCommandHook = (context: BeforeCommandHookContext) => Promise<void> | void;
+export type AfterCommandHook = (context: AfterCommandHookContext) => Promise<void> | void;
+export type OnWriteHook = (context: OnWriteHookContext) => Promise<void> | void;
+export type OnReadHook = (context: OnReadHookContext) => Promise<void> | void;
+export type OnIndexHook = (context: OnIndexHookContext) => Promise<void> | void;
+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;
+    run: THook;
+}
+export interface ExtensionHookRegistry {
+    beforeCommand: Array<RegisteredExtensionHook<BeforeCommandHook>>;
+    afterCommand: Array<RegisteredExtensionHook<AfterCommandHook>>;
+    onWrite: Array<RegisteredExtensionHook<OnWriteHook>>;
+    onRead: Array<RegisteredExtensionHook<OnReadHook>>;
+    onIndex: Array<RegisteredExtensionHook<OnIndexHook>>;
+}
+export interface CommandOverrideContext {
+    command: string;
+    args: string[];
+    options?: Record<string, unknown>;
+    global?: GlobalOptions;
+    pm_root: string;
+    result: unknown;
+}
+export interface RendererOverrideContext {
+    format: OutputRendererFormat;
+    command?: string;
+    args?: string[];
+    options?: Record<string, unknown>;
+    global?: GlobalOptions;
+    pm_root?: string;
+    result: unknown;
+}
+export interface CommandHandlerContext {
+    command: string;
+    args: string[];
+    options: Record<string, unknown>;
+    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;
+    /**
+     * @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 interface RegisteredExtensionCommandOverride {
+    layer: ExtensionLayer;
+    name: string;
+    command: string;
+    run: CommandOverride;
+}
+export interface RegisteredExtensionCommandHandler {
+    layer: ExtensionLayer;
+    name: string;
+    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;
+    format: OutputRendererFormat;
+    run: RendererOverride;
+}
+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[];
+}
+export interface RegisteredExtensionFlagDefinitions {
+    layer: ExtensionLayer;
+    name: string;
+    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;
+    name: string;
+    importer: string;
+}
+export interface RegisteredExtensionExporter {
+    layer: ExtensionLayer;
+    name: string;
+    exporter: string;
+}
+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[];
+    search_providers: RegisteredExtensionSearchProvider[];
+    vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];
+}
+export interface ExtensionRegistrationCounts {
+    commands: number;
+    flags: number;
+    item_fields: number;
+    item_types: number;
+    migrations: number;
+    importers: number;
+    exporters: number;
+    search_providers: number;
+    vector_store_adapters: number;
+}
+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;
+    registerExporter(name: string, exporter: Exporter): void;
+    registerSearchProvider(provider: SearchProviderDefinition): void;
+    registerVectorStoreAdapter(adapter: VectorStoreAdapterDefinition): void;
+    hooks: {
+        beforeCommand(hook: BeforeCommandHook): void;
+        afterCommand(hook: AfterCommandHook): void;
+        onWrite(hook: OnWriteHook): void;
+        onRead(hook: OnReadHook): void;
+        onIndex(hook: OnIndexHook): void;
+    };
+}
+export interface FailedExtensionActivation {
+    layer: ExtensionLayer;
+    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[];
+    warnings: string[];
+    hook_counts: {
+        before_command: number;
+        after_command: number;
+        on_write: number;
+        on_read: number;
+        on_index: number;
+    };
+    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 ExtensionCandidate {
+    layer: ExtensionLayer;
+    directory: string;
+    manifest_path: string;
+    entry_path: string;
+    manifest: ExtensionManifest;
+}
+export interface ExtensionLayerScanResult {
+    diagnostics: ExtensionDiagnostic[];
+    warnings: string[];
+    candidates: ExtensionCandidate[];
+}
+export interface ScannedExtensionDirectory {
+    diagnostic: ExtensionDiagnostic;
+    warnings: string[];
+    candidate: ExtensionCandidate | null;
+}
+export interface LegacyExtensionCapabilityAliasMapping {
+    alias: string;
+    target: ExtensionCapability;
+}
+export interface DiscoverExtensionsOptions {
+    pmRoot: string;
+    settings: PmSettings;
+    cwd?: string;
+    noExtensions?: boolean;
+}
+export interface ActivatableExtension {
+    activate: (api: ExtensionApi) => void | Promise<void>;
+}
+export interface ServiceOverrideResult {
+    handled: boolean;
+    result: unknown;
+    warnings: string[];
+}
+export interface CommandOverrideResult {
+    overridden: boolean;
+    result: unknown;
+    warnings: string[];
+}
+export interface CommandHandlerResult {
+    handled: boolean;
+    result: unknown;
+    warnings: string[];
+}
+export interface ParserOverrideResult {
+    overridden: boolean;
+    context: CommandHandlerContext;
+    warnings: string[];
+}
+export interface PreflightOverrideResult {
+    overridden: boolean;
+    context: CommandHandlerContext;
+    decision: PreflightRuntimeDecision;
+    warnings: string[];
+}
+export interface RendererOverrideResult {
+    overridden: boolean;
+    rendered: string | null;
+    warnings: string[];
+}
+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;
+}

package/dist/core/extensions/extension-types.js

@@ -0,0 +1,22 @@
+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 },
+});
+//# sourceMappingURL=extension-types.js.map

package/dist/core/extensions/extension-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-types.js","sourceRoot":"/","sources":["core/extensions/extension-types.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,UAAU;IACV,WAAW;IACX,OAAO;IACP,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,mCAAmC,GAAkD,MAAM,CAAC,MAAM,CAAC;IAC9G,SAAS,EAAE,QAAQ;IACnB,UAAU,EAAE,QAAQ;CACrB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC,MAAM,CAAC;IACzD,OAAO,EAAE,qCAAqC;IAC9C,YAAY,EAAE,CAAC,GAAG,4BAA4B,CAAC;IAC/C,cAAc,EAAE,EAAE,GAAG,mCAAmC,EAAE;CAC3D,CAAC,CAAC","sourcesContent":["import type { ItemDocument, PmSettings } from \"../../types/index.js\";\nimport type { GlobalOptions } from \"../shared/command-types.js\";\n\nexport const KNOWN_EXTENSION_CAPABILITIES = [\n  \"commands\",\n  \"renderers\",\n  \"hooks\",\n  \"schema\",\n  \"importers\",\n  \"search\",\n  \"parser\",\n  \"preflight\",\n  \"services\",\n] as const;\nexport type ExtensionCapability = (typeof KNOWN_EXTENSION_CAPABILITIES)[number];\nexport const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;\nexport const EXTENSION_CAPABILITY_LEGACY_ALIASES: Readonly<Record<string, ExtensionCapability>> = Object.freeze({\n  migration: \"schema\",\n  validation: \"schema\",\n});\nexport const EXTENSION_CAPABILITY_CONTRACT = Object.freeze({\n  version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  capabilities: [...KNOWN_EXTENSION_CAPABILITIES],\n  legacy_aliases: { ...EXTENSION_CAPABILITY_LEGACY_ALIASES },\n});\n\nexport type ExtensionLayer = \"global\" | \"project\";\nexport type ExtensionStatus = \"ok\" | \"warn\";\n\nexport interface ExtensionManifest {\n  name: string;\n  version: string;\n  entry: string;\n  priority: number;\n  capabilities: string[];\n  legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];\n}\n\nexport interface ExtensionDiagnostic {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  name: string | null;\n  version: string | null;\n  entry: string | null;\n  priority: number | null;\n  entry_path: string | null;\n  enabled: boolean | null;\n  status: ExtensionStatus;\n}\n\nexport interface EffectiveExtension {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  name: string;\n  version: string;\n  entry: string;\n  priority: number;\n  entry_path: string;\n  capabilities?: string[];\n}\n\nexport interface ExtensionDiscoveryResult {\n  disabled_by_flag: boolean;\n  roots: {\n    global: string;\n    project: string;\n  };\n  configured_enabled: string[];\n  configured_disabled: string[];\n  discovered: ExtensionDiagnostic[];\n  effective: EffectiveExtension[];\n  warnings: string[];\n}\n\nexport interface LoadedExtension extends EffectiveExtension {\n  module: unknown;\n}\n\nexport interface FailedExtensionLoad {\n  layer: ExtensionLayer;\n  name: string;\n  entry_path: string;\n  error: string;\n}\n\nexport interface ExtensionLoadResult extends ExtensionDiscoveryResult {\n  loaded: LoadedExtension[];\n  failed: FailedExtensionLoad[];\n}\n\nexport interface BeforeCommandHookContext {\n  command: string;\n  args: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root: string;\n}\n\nexport interface AfterCommandHookContext extends BeforeCommandHookContext {\n  ok: boolean;\n  error?: string;\n  result?: unknown;\n}\n\nexport interface OnWriteHookContext {\n  path: string;\n  scope: \"project\" | \"global\";\n  op: string;\n}\n\nexport interface OnReadHookContext {\n  path: string;\n  scope: \"project\" | \"global\";\n}\n\nexport interface OnIndexHookContext {\n  mode: string;\n  total_items?: number;\n}\n\nexport type BeforeCommandHook = (context: BeforeCommandHookContext) => Promise<void> | void;\nexport type AfterCommandHook = (context: AfterCommandHookContext) => Promise<void> | void;\nexport type OnWriteHook = (context: OnWriteHookContext) => Promise<void> | void;\nexport type OnReadHook = (context: OnReadHookContext) => Promise<void> | void;\nexport type OnIndexHook = (context: OnIndexHookContext) => Promise<void> | void;\nexport type OutputRendererFormat = \"toon\" | \"json\";\nexport type CommandOverride = (context: CommandOverrideContext) => unknown;\nexport type RendererOverride = (context: RendererOverrideContext) => string;\nexport type CommandHandler = (context: CommandHandlerContext) => unknown;\nexport type ParserOverride = (context: ParserOverrideContext) => ParserOverrideDelta | Promise<ParserOverrideDelta>;\nexport type PreflightOverride = (context: PreflightOverrideContext) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;\nexport type ServiceOverride = (context: ServiceOverrideContext) => unknown;\n\nexport interface RegisteredExtensionHook<THook> {\n  layer: ExtensionLayer;\n  name: string;\n  run: THook;\n}\n\nexport interface ExtensionHookRegistry {\n  beforeCommand: Array<RegisteredExtensionHook<BeforeCommandHook>>;\n  afterCommand: Array<RegisteredExtensionHook<AfterCommandHook>>;\n  onWrite: Array<RegisteredExtensionHook<OnWriteHook>>;\n  onRead: Array<RegisteredExtensionHook<OnReadHook>>;\n  onIndex: Array<RegisteredExtensionHook<OnIndexHook>>;\n}\n\nexport interface CommandOverrideContext {\n  command: string;\n  args: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root: string;\n  result: unknown;\n}\n\nexport interface RendererOverrideContext {\n  format: OutputRendererFormat;\n  command?: string;\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root?: string;\n  result: unknown;\n}\n\nexport interface CommandHandlerContext {\n  command: string;\n  args: string[];\n  options: Record<string, unknown>;\n  global: GlobalOptions;\n  pm_root: string;\n}\n\nexport interface ParserOverrideContext extends CommandHandlerContext {}\n\nexport interface ParserOverrideDelta {\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n}\n\nexport interface PreflightOverrideContext extends CommandHandlerContext {\n  decision: PreflightRuntimeDecision;\n}\n\nexport interface PreflightRuntimeDecision {\n  enforce_item_format_gate: boolean;\n  run_preflight_item_format_sync: boolean;\n  run_extension_migrations: boolean;\n  enforce_mandatory_migration_gate: boolean;\n}\n\nexport interface PreflightOverrideDelta extends ParserOverrideDelta {\n  enforce_item_format_gate?: boolean;\n  run_preflight_item_format_sync?: boolean;\n  run_extension_migrations?: boolean;\n  enforce_mandatory_migration_gate?: boolean;\n}\n\nexport type ExtensionServiceName =\n  | \"output_format\"\n  | \"error_format\"\n  | \"help_format\"\n  | \"lock_acquire\"\n  | \"lock_release\"\n  | \"history_append\"\n  | \"item_store_write\"\n  | \"item_store_delete\";\n\nexport interface ServiceOverrideContext {\n  service: ExtensionServiceName;\n  command?: string;\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root?: string;\n  payload: unknown;\n}\n\nexport interface ExtensionCommandArgumentDefinition {\n  name: string;\n  required?: boolean;\n  variadic?: boolean;\n  description?: string;\n}\n\nexport interface CommandDefinition {\n  name: string;\n  run?: CommandHandler;\n  /**\n   * @deprecated Use `run` instead. This alias remains for backward compatibility.\n   */\n  handler?: CommandHandler;\n  action?: string;\n  description?: string;\n  intent?: string;\n  examples?: string[];\n  failure_hints?: string[];\n  arguments?: ExtensionCommandArgumentDefinition[];\n  flags?: FlagDefinition[];\n}\n\nexport type FlagValueType = \"string\" | \"number\" | \"boolean\";\n\nexport interface FlagDefinition {\n  long?: string;\n  short?: string;\n  value_name?: string;\n  description?: string;\n  required?: boolean;\n  enabled?: boolean;\n  visible?: boolean;\n  type?: FlagValueType;\n  value_type?: FlagValueType;\n  [key: string]: unknown;\n}\n\nexport interface SchemaFieldDefinition {\n  name: string;\n  type: string;\n  optional?: boolean;\n  [key: string]: unknown;\n}\n\nexport interface SchemaItemTypeCommandOptionPolicyDefinition {\n  command: string;\n  option: string;\n  enabled?: boolean;\n  required?: boolean;\n  visible?: boolean;\n  [key: string]: unknown;\n}\n\nexport interface SchemaItemTypeOptionDefinition {\n  key: string;\n  values?: string[];\n  required?: boolean;\n  aliases?: string[];\n  [key: string]: unknown;\n}\n\nexport interface SchemaItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  command_option_policies?: SchemaItemTypeCommandOptionPolicyDefinition[];\n  options?: SchemaItemTypeOptionDefinition[];\n  [key: string]: unknown;\n}\n\nexport interface SchemaMigrationRunContext {\n  id: string;\n  command: \"migration\";\n  layer: ExtensionLayer;\n  extension: string;\n  pm_root: string;\n  status: string;\n}\n\nexport type SchemaMigrationRunner = (context: SchemaMigrationRunContext) => unknown | Promise<unknown>;\n\nexport interface SchemaMigrationDefinition {\n  id?: string;\n  description?: string;\n  status?: string;\n  mandatory?: boolean;\n  run?: SchemaMigrationRunner;\n  [key: string]: unknown;\n}\n\nexport interface ImportExportContext {\n  registration: string;\n  action: \"import\" | \"export\";\n  command: string;\n  args: string[];\n  options: Record<string, unknown>;\n  global: GlobalOptions;\n  pm_root: string;\n}\n\nexport type Importer = (context: ImportExportContext) => unknown | Promise<unknown>;\nexport type Exporter = (context: ImportExportContext) => unknown | Promise<unknown>;\n\nexport type ExtensionSearchMode = \"keyword\" | \"semantic\" | \"hybrid\";\n\nexport interface SearchProviderQueryContext {\n  query: string;\n  mode: ExtensionSearchMode;\n  tokens: string[];\n  options: Record<string, unknown>;\n  settings: PmSettings;\n  documents: ItemDocument[];\n  [key: string]: unknown;\n}\n\nexport interface SearchProviderHit {\n  id: string;\n  score: number;\n  matched_fields?: string[];\n  [key: string]: unknown;\n}\n\nexport type SearchProviderQueryResult = SearchProviderHit[] | { hits?: SearchProviderHit[] };\n\nexport interface SearchProviderEmbedBatchContext {\n  inputs: string[];\n  settings: PmSettings;\n  model: string;\n  [key: string]: unknown;\n}\n\nexport interface SearchProviderEmbedContext {\n  input: string;\n  settings: PmSettings;\n  model: string;\n  [key: string]: unknown;\n}\n\nexport interface SearchProviderDefinition {\n  name: string;\n  query?: (context: SearchProviderQueryContext) => SearchProviderQueryResult | Promise<SearchProviderQueryResult>;\n  embedBatch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;\n  embed_batch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;\n  embed?: (context: SearchProviderEmbedContext) => number[] | Promise<number[]>;\n  [key: string]: unknown;\n}\n\nexport interface VectorStoreQueryHit {\n  id: string;\n  score: number;\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\nexport interface VectorStoreQueryContext {\n  vector: number[];\n  limit: number;\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\nexport interface VectorStoreUpsertPoint {\n  id: string;\n  vector: number[];\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\nexport interface VectorStoreUpsertContext {\n  points: VectorStoreUpsertPoint[];\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\nexport interface VectorStoreDeleteContext {\n  ids: string[];\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\nexport interface VectorStoreAdapterDefinition {\n  name: string;\n  query?: (context: VectorStoreQueryContext) => VectorStoreQueryHit[] | Promise<VectorStoreQueryHit[]>;\n  upsert?: (context: VectorStoreUpsertContext) => unknown | Promise<unknown>;\n  delete?: (context: VectorStoreDeleteContext) => unknown | Promise<unknown>;\n  [key: string]: unknown;\n}\n\nexport interface RegisteredExtensionCommandOverride {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: CommandOverride;\n}\n\nexport interface RegisteredExtensionCommandHandler {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: CommandHandler;\n}\n\nexport interface RegisteredExtensionParserOverride {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: ParserOverride;\n}\n\nexport interface RegisteredExtensionPreflightOverride {\n  layer: ExtensionLayer;\n  name: string;\n  run: PreflightOverride;\n}\n\nexport interface RegisteredExtensionServiceOverride {\n  layer: ExtensionLayer;\n  name: string;\n  service: ExtensionServiceName;\n  run: ServiceOverride;\n}\n\nexport interface RegisteredExtensionRendererOverride {\n  layer: ExtensionLayer;\n  name: string;\n  format: OutputRendererFormat;\n  run: RendererOverride;\n}\n\nexport interface ExtensionCommandRegistry {\n  overrides: RegisteredExtensionCommandOverride[];\n  handlers: RegisteredExtensionCommandHandler[];\n}\n\nexport interface ExtensionParserRegistry {\n  overrides: RegisteredExtensionParserOverride[];\n}\n\nexport interface ExtensionPreflightRegistry {\n  overrides: RegisteredExtensionPreflightOverride[];\n}\n\nexport interface ExtensionServiceRegistry {\n  overrides: RegisteredExtensionServiceOverride[];\n}\n\nexport interface ExtensionRendererRegistry {\n  overrides: RegisteredExtensionRendererOverride[];\n}\n\nexport interface RegisteredExtensionFlagDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  target_command: string;\n  flags: FlagDefinition[];\n}\n\nexport interface RegisteredExtensionCommandDefinition {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  action: string;\n  description?: string;\n  intent?: string;\n  examples: string[];\n  failure_hints: string[];\n  arguments: ExtensionCommandArgumentDefinition[];\n}\n\nexport interface RegisteredExtensionSchemaFieldDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  fields: SchemaFieldDefinition[];\n}\n\nexport interface RegisteredExtensionSchemaItemTypeDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  types: SchemaItemTypeDefinition[];\n}\n\nexport interface RegisteredExtensionSchemaMigrationDefinition {\n  layer: ExtensionLayer;\n  name: string;\n  definition: SchemaMigrationDefinition;\n  runtime_definition: SchemaMigrationDefinition;\n}\n\nexport interface RegisteredExtensionImporter {\n  layer: ExtensionLayer;\n  name: string;\n  importer: string;\n}\n\nexport interface RegisteredExtensionExporter {\n  layer: ExtensionLayer;\n  name: string;\n  exporter: string;\n}\n\nexport interface RegisteredExtensionSearchProvider {\n  layer: ExtensionLayer;\n  name: string;\n  definition: SearchProviderDefinition;\n  runtime_definition: SearchProviderDefinition;\n}\n\nexport interface RegisteredExtensionVectorStoreAdapter {\n  layer: ExtensionLayer;\n  name: string;\n  definition: VectorStoreAdapterDefinition;\n  runtime_definition: VectorStoreAdapterDefinition;\n}\n\nexport interface ExtensionRegistrationRegistry {\n  commands: RegisteredExtensionCommandDefinition[];\n  flags: RegisteredExtensionFlagDefinitions[];\n  item_fields: RegisteredExtensionSchemaFieldDefinitions[];\n  item_types: RegisteredExtensionSchemaItemTypeDefinitions[];\n  migrations: RegisteredExtensionSchemaMigrationDefinition[];\n  importers: RegisteredExtensionImporter[];\n  exporters: RegisteredExtensionExporter[];\n  search_providers: RegisteredExtensionSearchProvider[];\n  vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];\n}\n\nexport interface ExtensionRegistrationCounts {\n  commands: number;\n  flags: number;\n  item_fields: number;\n  item_types: number;\n  migrations: number;\n  importers: number;\n  exporters: number;\n  search_providers: number;\n  vector_store_adapters: number;\n}\n\nexport interface ExtensionApi {\n  registerCommand(command: string, override: CommandOverride): void;\n  registerCommand(definition: CommandDefinition): void;\n  registerParser(command: string, override: ParserOverride): void;\n  registerPreflight(override: PreflightOverride): void;\n  registerService(service: ExtensionServiceName, override: ServiceOverride): void;\n  registerFlags(targetCommand: string, flags: FlagDefinition[]): void;\n  registerItemFields(fields: SchemaFieldDefinition[]): void;\n  registerItemTypes(types: SchemaItemTypeDefinition[]): void;\n  registerMigration(definition: SchemaMigrationDefinition): void;\n  registerRenderer(format: OutputRendererFormat, renderer: RendererOverride): void;\n  registerImporter(name: string, importer: Importer): void;\n  registerExporter(name: string, exporter: Exporter): void;\n  registerSearchProvider(provider: SearchProviderDefinition): void;\n  registerVectorStoreAdapter(adapter: VectorStoreAdapterDefinition): void;\n  hooks: {\n    beforeCommand(hook: BeforeCommandHook): void;\n    afterCommand(hook: AfterCommandHook): void;\n    onWrite(hook: OnWriteHook): void;\n    onRead(hook: OnReadHook): void;\n    onIndex(hook: OnIndexHook): void;\n  };\n}\n\nexport interface FailedExtensionActivation {\n  layer: ExtensionLayer;\n  name: string;\n  entry_path: string;\n  error: string;\n  trace?: ExtensionActivationFailureTrace;\n}\n\nexport interface ExtensionActivationFailureTrace {\n  method: string;\n  registration_index: number;\n  command?: string;\n  expected_schema: string;\n  received?: unknown;\n  hint?: string;\n}\n\nexport interface ExtensionActivationResult {\n  hooks: ExtensionHookRegistry;\n  commands: ExtensionCommandRegistry;\n  parsers: ExtensionParserRegistry;\n  preflight: ExtensionPreflightRegistry;\n  services: ExtensionServiceRegistry;\n  renderers: ExtensionRendererRegistry;\n  registrations: ExtensionRegistrationRegistry;\n  failed: FailedExtensionActivation[];\n  warnings: string[];\n  hook_counts: {\n    before_command: number;\n    after_command: number;\n    on_write: number;\n    on_read: number;\n    on_index: number;\n  };\n  command_override_count: number;\n  command_handler_count: number;\n  parser_override_count: number;\n  preflight_override_count: number;\n  service_override_count: number;\n  renderer_override_count: number;\n  registration_counts: ExtensionRegistrationCounts;\n}\n\nexport interface ExtensionCandidate {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  entry_path: string;\n  manifest: ExtensionManifest;\n}\n\nexport interface ExtensionLayerScanResult {\n  diagnostics: ExtensionDiagnostic[];\n  warnings: string[];\n  candidates: ExtensionCandidate[];\n}\n\nexport interface ScannedExtensionDirectory {\n  diagnostic: ExtensionDiagnostic;\n  warnings: string[];\n  candidate: ExtensionCandidate | null;\n}\n\nexport interface LegacyExtensionCapabilityAliasMapping {\n  alias: string;\n  target: ExtensionCapability;\n}\n\nexport interface DiscoverExtensionsOptions {\n  pmRoot: string;\n  settings: PmSettings;\n  cwd?: string;\n  noExtensions?: boolean;\n}\n\nexport interface ActivatableExtension {\n  activate: (api: ExtensionApi) => void | Promise<void>;\n}\n\nexport interface ServiceOverrideResult {\n  handled: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\nexport interface CommandOverrideResult {\n  overridden: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\nexport interface CommandHandlerResult {\n  handled: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\nexport interface ParserOverrideResult {\n  overridden: boolean;\n  context: CommandHandlerContext;\n  warnings: string[];\n}\n\nexport interface PreflightOverrideResult {\n  overridden: boolean;\n  context: CommandHandlerContext;\n  decision: PreflightRuntimeDecision;\n  warnings: string[];\n}\n\nexport interface RendererOverrideResult {\n  overridden: boolean;\n  rendered: string | null;\n  warnings: string[];\n}\n\nexport interface UnknownExtensionCapabilityWarningDetails {\n  layer: ExtensionLayer;\n  name: string;\n  capability: string;\n  allowed_capabilities: string[];\n  capability_contract_version: number;\n  suggested_capability?: string;\n  suggestion_source?: \"legacy_alias\" | \"nearest_match\";\n  legacy_alias_target?: string;\n}\n"]}