@unbrained/pm-cli 2026.10.12 → 2026.10.14

package/dist/core/store/item-store.d.ts

@@ -3,14 +3,14 @@ import { PmCliError } from "../shared/errors.js";
 import type { ItemDocument, ItemFormat, ItemMetadata, ItemType, PmSettings, RuntimeSchemaSettings } from "../../types/index.js";
 /** Documents the located item payload exchanged by command, SDK, and package integrations. */
 export interface LocatedItem {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Schema type that determines the shape and validation rules for this value. */
-    type: ItemType;
-    /** Filesystem path used for item resolution. */
-    itemPath: string;
-    /** Value that configures or reports item format for this contract. */
-    item_format: ItemFormat;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Schema type that determines the shape and validation rules for this value. */
+type: ItemType;
+/** Filesystem path used for item resolution. */
+itemPath: string;
+/** Value that configures or reports item format for this contract. */
+item_format: ItemFormat;
 }
 declare function isErrno(error: unknown, code: string): boolean;
 declare function appendWarning(warnings: string[] | undefined, warning: string): void;
@@ -22,12 +22,12 @@ declare function appendWarning(warnings: string[] | undefined, warning: string):
 export declare function locateItem(pmRoot: string, rawId: string, idPrefix?: string, preferredFormat?: ItemFormat, typeToFolder?: Record<string, string>): Promise<LocatedItem | null>;
 /** Implements read located item for the public runtime surface of this module. */
 export declare function readLocatedItem(item: LocatedItem, options?: {
-    schema?: RuntimeSchemaSettings;
-    extensionFieldNames?: readonly string[];
-    warnings?: string[];
+schema?: RuntimeSchemaSettings;
+extensionFieldNames?: readonly string[];
+warnings?: string[];
 }): Promise<{
-    raw: string;
-    document: ItemDocument;
+raw: string;
+document: ItemDocument;
 }>;
 /**
  * Read once and retain a recoverable parse failure beside its exact text snapshot.
@@ -35,13 +35,13 @@ export declare function readLocatedItem(item: LocatedItem, options?: {
  * reconstruct an invalid document before performing any mutation.
  */
 export declare function readLocatedItemSnapshot(item: LocatedItem, options?: Parameters<typeof readLocatedItem>[1]): Promise<{
-    raw: string;
-    document: ItemDocument;
-    error: null;
+raw: string;
+document: ItemDocument;
+error: null;
 } | {
-    raw: string;
-    document: null;
-    error: PmCliError;
+raw: string;
+document: null;
+error: PmCliError;
 }>;
 /** Implements list all item metadata for the public runtime surface of this module. */
 export declare function listAllItemMetadata(pmRoot: string, preferredFormat?: ItemFormat, typeToFolder?: Record<string, string>, warnings?: string[], schema?: RuntimeSchemaSettings): Promise<ItemMetadata[]>;
@@ -54,126 +54,126 @@ export declare function listAllItemMetadata(pmRoot: string, preferredFormat?: It
 export declare function listAllItemMetadataLight(pmRoot: string, preferredFormat?: ItemFormat, typeToFolder?: Record<string, string>, warnings?: string[], schema?: RuntimeSchemaSettings): Promise<ItemMetadata[]>;
 /** List item metadata with bodies, optionally bypassing the derived-index fast path when an integrity workflow must re-read authoritative files. */
 export declare function listAllItemMetadataWithBody(pmRoot: string, preferredFormat?: ItemFormat, typeToFolder?: Record<string, string>, warnings?: string[], schema?: RuntimeSchemaSettings, options?: {
-    forceSourceScan?: boolean;
+forceSourceScan?: boolean;
 }): Promise<Array<ItemMetadata & {
-    body: string;
+body: string;
 }>>;
 /** Build the minimal host-bound read-only SDK exposed to transactional extension guards. */
 export declare function createMutationGuardSdk(params: {
-    pmRoot: string;
-    settings: PmSettings;
-    typeToFolder: Record<string, string>;
+pmRoot: string;
+settings: PmSettings;
+typeToFolder: Record<string, string>;
 }): ExtensionMutationGuardSdk;
 declare function buildDidYouMeanSuggestions(pmRoot: string, badId: string, idPrefix: string, typeToFolder: Record<string, string>): Promise<string[]>;
 /** Implements build item not found error for the public runtime surface of this module. */
 export declare function buildItemNotFoundError(pmRoot: string, badId: string, idPrefix: string, typeToFolder: Record<string, string>): Promise<PmCliError>;
 declare function bypassesAssigneeConflict(op: string, bypassAssigneeConflict?: boolean): boolean;
 interface ItemMutationResult {
-    item: ItemMetadata;
-    body: string;
-    changedFields: string[];
-    warnings: string[];
+item: ItemMetadata;
+body: string;
+changedFields: string[];
+warnings: string[];
 }
 interface ItemMutationParams {
-    pmRoot: string;
-    settings: PmSettings;
-    id: string;
-    op: string;
-    author: string;
-    message?: string;
-    /** Structured immutable context attached to the appended history entry. */
-    historyContext?: Record<string, unknown>;
-    force?: boolean;
-    bypassAssigneeConflict?: boolean;
-    skipNoop?: boolean;
-    extensionFieldNames?: readonly string[];
-    typeToFolder?: Record<string, string>;
-    mutate: (document: ItemDocument) => {
-        changedFields: string[];
-        warnings?: string[];
-    } | Promise<{
-        changedFields: string[];
-        warnings?: string[];
-    }>;
+pmRoot: string;
+settings: PmSettings;
+id: string;
+op: string;
+author: string;
+message?: string;
+/** Structured immutable context attached to the appended history entry. */
+historyContext?: Record<string, unknown>;
+force?: boolean;
+bypassAssigneeConflict?: boolean;
+skipNoop?: boolean;
+extensionFieldNames?: readonly string[];
+typeToFolder?: Record<string, string>;
+mutate: (document: ItemDocument) => {
+changedFields: string[];
+warnings?: string[];
+} | Promise<{
+changedFields: string[];
+warnings?: string[];
+}>;
 }
 /** Mutate one item while attaching structured context to its immutable history event. */
 export declare function mutateItemWithHistoryContext(params: {
-    pmRoot: string;
-    settings: PmSettings;
-    id: string;
-    op: string;
-    author: string;
-    message?: string;
-    /** Structured immutable context attached to the appended history entry. */
-    historyContext?: Record<string, unknown>;
-    force?: boolean;
-    bypassAssigneeConflict?: boolean;
-    skipNoop?: boolean;
-    extensionFieldNames?: readonly string[];
-    typeToFolder?: Record<string, string>;
-    mutate: (document: ItemDocument) => {
-        changedFields: string[];
-        warnings?: string[];
-    } | Promise<{
-        changedFields: string[];
-        warnings?: string[];
-    }>;
+pmRoot: string;
+settings: PmSettings;
+id: string;
+op: string;
+author: string;
+message?: string;
+/** Structured immutable context attached to the appended history entry. */
+historyContext?: Record<string, unknown>;
+force?: boolean;
+bypassAssigneeConflict?: boolean;
+skipNoop?: boolean;
+extensionFieldNames?: readonly string[];
+typeToFolder?: Record<string, string>;
+mutate: (document: ItemDocument) => {
+changedFields: string[];
+warnings?: string[];
+} | Promise<{
+changedFields: string[];
+warnings?: string[];
+}>;
 }): Promise<{
-    item: ItemMetadata;
-    body: string;
-    changedFields: string[];
-    warnings: string[];
+item: ItemMetadata;
+body: string;
+changedFields: string[];
+warnings: string[];
 }>;
 /** Mutate one item while resolving structured history context after its locked mutation. */
 export declare function mutateItemWithHistoryContextResolver(params: Omit<ItemMutationParams, "historyContext"> & {
-    resolveHistoryContext: () => Record<string, unknown> | undefined;
+resolveHistoryContext: () => Record<string, unknown> | undefined;
 }): Promise<ItemMutationResult>;
 /** Implements mutate item for the public runtime surface of this module. */
 export declare function mutateItem(params: {
-    pmRoot: string;
-    settings: PmSettings;
-    id: string;
-    op: string;
-    author: string;
-    message?: string;
-    force?: boolean;
-    bypassAssigneeConflict?: boolean;
-    skipNoop?: boolean;
-    extensionFieldNames?: readonly string[];
-    typeToFolder?: Record<string, string>;
-    mutate: (document: ItemDocument) => {
-        changedFields: string[];
-        warnings?: string[];
-    } | Promise<{
-        changedFields: string[];
-        warnings?: string[];
-    }>;
+pmRoot: string;
+settings: PmSettings;
+id: string;
+op: string;
+author: string;
+message?: string;
+force?: boolean;
+bypassAssigneeConflict?: boolean;
+skipNoop?: boolean;
+extensionFieldNames?: readonly string[];
+typeToFolder?: Record<string, string>;
+mutate: (document: ItemDocument) => {
+changedFields: string[];
+warnings?: string[];
+} | Promise<{
+changedFields: string[];
+warnings?: string[];
+}>;
 }): Promise<{
-    item: ItemMetadata;
-    body: string;
-    changedFields: string[];
-    warnings: string[];
+item: ItemMetadata;
+body: string;
+changedFields: string[];
+warnings: string[];
 }>;
 /** Public contract for item store test only, shared by SDK and presentation-layer consumers. */
 export declare const itemStoreTestOnly: {
-    appendWarning: typeof appendWarning;
-    bypassesAssigneeConflict: typeof bypassesAssigneeConflict;
-    buildDidYouMeanSuggestions: typeof buildDidYouMeanSuggestions;
-    isErrno: typeof isErrno;
+appendWarning: typeof appendWarning;
+bypassesAssigneeConflict: typeof bypassesAssigneeConflict;
+buildDidYouMeanSuggestions: typeof buildDidYouMeanSuggestions;
+isErrno: typeof isErrno;
 };
 /** Implements delete item for the public runtime surface of this module. */
 export declare function deleteItem(params: {
-    pmRoot: string;
-    settings: PmSettings;
-    id: string;
-    author: string;
-    message?: string;
-    force?: boolean;
-    dryRun?: boolean;
+pmRoot: string;
+settings: PmSettings;
+id: string;
+author: string;
+message?: string;
+force?: boolean;
+dryRun?: boolean;
 }): Promise<{
-    item: ItemMetadata;
-    changedFields: string[];
-    warnings: string[];
-    targetPath?: string;
+item: ItemMetadata;
+changedFields: string[];
+warnings: string[];
+targetPath?: string;
 }>;
 export {};

package/dist/core/store/paths.d.ts

@@ -2,8 +2,8 @@ import type { ItemFormat, ItemType } from "../../types/index.js";
 /** Public contract for item file extension by format, shared by SDK and presentation-layer consumers. */
 export declare const ITEM_FILE_EXTENSION_BY_FORMAT: Record<ItemFormat, ".md" | ".toon">;
 declare const ITEM_FORMAT_BY_EXTENSION: {
-    readonly ".md": "json_markdown";
-    readonly ".toon": "toon";
+readonly ".md": "json_markdown";
+readonly ".toon": "toon";
 };
 /** Public contract for item file extensions, shared by SDK and presentation-layer consumers. */
 export declare const ITEM_FILE_EXTENSIONS: Array<keyof typeof ITEM_FORMAT_BY_EXTENSION>;

package/dist/core/store/settings-read-cache.d.ts

@@ -1,20 +1,20 @@
 /** Documents the settings read cache path signature payload exchanged by command, SDK, and package integrations. */
 export interface SettingsReadCachePathSignature {
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Elapsed time in milliseconds for mtime. */
-    mtime_ms: number | null;
-    /** Value that configures or reports size for this contract. */
-    size: number | null;
+/** Filesystem path used for path resolution. */
+path: string;
+/** Elapsed time in milliseconds for mtime. */
+mtime_ms: number | null;
+/** Value that configures or reports size for this contract. */
+size: number | null;
 }
 /** Documents the settings read cache entry payload exchanged by command, SDK, and package integrations. */
 export interface SettingsReadCacheEntry<T> {
-    /** Value that configures or reports tracked paths for this contract. */
-    tracked_paths: string[];
-    /** Value that configures or reports signatures for this contract. */
-    signatures: SettingsReadCachePathSignature[];
-    /** Value that configures or reports value for this contract. */
-    value: T;
+/** Value that configures or reports tracked paths for this contract. */
+tracked_paths: string[];
+/** Value that configures or reports signatures for this contract. */
+signatures: SettingsReadCachePathSignature[];
+/** Value that configures or reports value for this contract. */
+value: T;
 }
 /** Implements collect settings read cache signatures for the public runtime surface of this module. */
 export declare function collectSettingsReadCacheSignatures(paths: string[]): Promise<SettingsReadCachePathSignature[]>;

package/dist/core/store/settings-validator.d.ts

@@ -2,175 +2,175 @@ import type { AgentGuidanceSettings, ExtensionPolicySettings, GovernanceSettings
 import type { PmMaxVersionExceededModeSetting } from "../extensions/extension-types.js";
 /** Validated, unknown-key-stripped settings input (pre-merge), matching the legacy zod inference. */
 export interface ParsedSettings {
-    /** Value that configures or reports version for this contract. */
-    version: number;
-    /** Value that configures or reports id prefix for this contract. */
-    id_prefix: string;
-    /** Item id allocation policy (random base36 token length appended to the prefix). */
-    ids?: {
-        token_length?: number;
-    };
-    /** Value that configures or reports author default for this contract. */
-    author_default: string;
-    /** Declarative workspace additions to agent identity detection. */
-    agent_identity?: PmSettings["agent_identity"];
-    /** Shared pre-write mutation guard policy. */
-    mutation_guard?: {
-        require_attributed_author?: boolean;
-        secret_guard?: "off" | "advise" | "block";
-        stale_in_progress_hours?: number;
-    };
-    /** Value that configures or reports item format for this contract. */
-    item_format?: "toon" | "json_markdown";
-    /** Value that configures or reports locks for this contract. */
-    locks: {
-        ttl_seconds: number;
-        wait_ms?: number;
-    };
-    /** Value that configures or reports checkpoints for this contract. */
-    checkpoints?: {
-        retention_days?: number;
-    };
-    /** Value that configures or reports output for this contract. */
-    output: {
-        default_format: "toon" | "json";
-    };
-    /** Agent and human interaction preferences. */
-    ux?: {
-        deprecation_hints?: boolean;
-    };
-    /** Value that configures or reports history for this contract. */
-    history?: {
-        missing_stream: "auto_create" | "strict_error";
-        compact_policy?: {
-            enabled?: boolean;
-            max_entries?: number;
-            trigger?: "health_warn" | "auto";
-        };
-    };
-    /** Value that configures or reports validation for this contract. */
-    validation?: {
-        sprint_release_format: "warn" | "strict_error";
-        parent_reference?: "warn" | "strict_error";
-        metadata_profile?: "core" | "strict" | "custom";
-        metadata_required_fields?: string[];
-        lifecycle_stale_blocker_reason_patterns?: string[];
-        lifecycle_closure_like_blocked_reason_patterns?: string[];
-        lifecycle_closure_like_resolution_patterns?: string[];
-        lifecycle_closure_like_actual_result_patterns?: string[];
-        estimate_defaults_by_type?: Record<string, number>;
-    };
-    /** Value that configures or reports governance for this contract. */
-    governance?: Partial<GovernanceSettings>;
-    /** Value that configures or reports workflow for this contract. */
-    workflow?: {
-        definition_of_done: string[];
-    };
-    /** Value that configures or reports testing for this contract. */
-    testing?: {
-        record_results_to_items: boolean;
-        allow_untrusted_linked_tests?: boolean;
-    };
-    /** Value that configures or reports telemetry for this contract. */
-    telemetry?: {
-        enabled: boolean;
-        first_run_prompt_completed?: boolean;
-        capture_level?: "minimal" | "redacted" | "max";
-        endpoint?: string;
-        installation_id?: string;
-        retention_days?: number;
-    };
-    /** Value that configures or reports agent guidance for this contract. */
-    agent_guidance?: Partial<AgentGuidanceSettings>;
-    /** Value that configures or reports item types for this contract. */
-    item_types?: {
-        definitions: ItemTypeDefinition[];
-    };
-    /** Value that configures or reports schema for this contract. */
-    schema?: Partial<RuntimeSchemaSettings>;
-    /** Value that configures or reports context for this contract. */
-    context?: {
-        default_depth?: "brief" | "standard" | "deep";
-        activity_limit?: number;
-        stale_threshold_days?: number;
-        sections?: {
-            hierarchy?: boolean;
-            activity?: boolean;
-            progress?: boolean;
-            blockers?: boolean;
-            files?: boolean;
-            workload?: boolean;
-            staleness?: boolean;
-            tests?: boolean;
-        };
-    };
-    /** Value that configures or reports extensions for this contract. */
-    extensions: {
-        enabled: string[];
-        disabled: string[];
-        policy?: Partial<ExtensionPolicySettings> & {
-            pm_max_version_exceeded_mode?: PmMaxVersionExceededModeSetting;
-        };
-    };
-    /** Value that configures or reports search for this contract. */
-    search: {
-        score_threshold: number;
-        hybrid_semantic_weight?: number;
-        max_results: number;
-        embedding_model: string;
-        embedding_corpus_max_characters?: number;
-        embedding_batch_size: number;
-        embedding_timeout_ms?: number;
-        scanner_max_batch_retries: number;
-        provider?: string;
-        default_mode?: "auto" | "keyword" | "semantic" | "hybrid";
-        corpus_fields?: string[];
-        mutation_refresh_policy?: "cache_only" | "semantic_configured" | "semantic_auto";
-        query_expansion?: {
-            enabled?: boolean;
-            provider?: string;
-        };
-        rerank?: {
-            enabled?: boolean;
-            model?: string;
-            top_k?: number;
-        };
-        bm25?: {
-            k1?: number;
-            b?: number;
-        };
-    };
-    /** Value that configures or reports providers for this contract. */
-    providers: {
-        openai: {
-            base_url: string;
-            api_key: string;
-            model: string;
-        };
-        ollama: {
-            base_url: string;
-            model: string;
-        };
-    };
-    /** Value that configures or reports vector store for this contract. */
-    vector_store: {
-        adapter?: string;
-        collection_name?: string;
-        qdrant: {
-            url: string;
-            api_key: string;
-        };
-        lancedb: {
-            path: string;
-        };
-    };
+/** Value that configures or reports version for this contract. */
+version: number;
+/** Value that configures or reports id prefix for this contract. */
+id_prefix: string;
+/** Item id allocation policy (random base36 token length appended to the prefix). */
+ids?: {
+token_length?: number;
+};
+/** Value that configures or reports author default for this contract. */
+author_default: string;
+/** Declarative workspace additions to agent identity detection. */
+agent_identity?: PmSettings["agent_identity"];
+/** Shared pre-write mutation guard policy. */
+mutation_guard?: {
+require_attributed_author?: boolean;
+secret_guard?: "off" | "advise" | "block";
+stale_in_progress_hours?: number;
+};
+/** Value that configures or reports item format for this contract. */
+item_format?: "toon" | "json_markdown";
+/** Value that configures or reports locks for this contract. */
+locks: {
+ttl_seconds: number;
+wait_ms?: number;
+};
+/** Value that configures or reports checkpoints for this contract. */
+checkpoints?: {
+retention_days?: number;
+};
+/** Value that configures or reports output for this contract. */
+output: {
+default_format: "toon" | "json";
+};
+/** Agent and human interaction preferences. */
+ux?: {
+deprecation_hints?: boolean;
+};
+/** Value that configures or reports history for this contract. */
+history?: {
+missing_stream: "auto_create" | "strict_error";
+compact_policy?: {
+enabled?: boolean;
+max_entries?: number;
+trigger?: "health_warn" | "auto";
+};
+};
+/** Value that configures or reports validation for this contract. */
+validation?: {
+sprint_release_format: "warn" | "strict_error";
+parent_reference?: "warn" | "strict_error";
+metadata_profile?: "core" | "strict" | "custom";
+metadata_required_fields?: string[];
+lifecycle_stale_blocker_reason_patterns?: string[];
+lifecycle_closure_like_blocked_reason_patterns?: string[];
+lifecycle_closure_like_resolution_patterns?: string[];
+lifecycle_closure_like_actual_result_patterns?: string[];
+estimate_defaults_by_type?: Record<string, number>;
+};
+/** Value that configures or reports governance for this contract. */
+governance?: Partial<GovernanceSettings>;
+/** Value that configures or reports workflow for this contract. */
+workflow?: {
+definition_of_done: string[];
+};
+/** Value that configures or reports testing for this contract. */
+testing?: {
+record_results_to_items: boolean;
+allow_untrusted_linked_tests?: boolean;
+};
+/** Value that configures or reports telemetry for this contract. */
+telemetry?: {
+enabled: boolean;
+first_run_prompt_completed?: boolean;
+capture_level?: "minimal" | "redacted" | "max";
+endpoint?: string;
+installation_id?: string;
+retention_days?: number;
+};
+/** Value that configures or reports agent guidance for this contract. */
+agent_guidance?: Partial<AgentGuidanceSettings>;
+/** Value that configures or reports item types for this contract. */
+item_types?: {
+definitions: ItemTypeDefinition[];
+};
+/** Value that configures or reports schema for this contract. */
+schema?: Partial<RuntimeSchemaSettings>;
+/** Value that configures or reports context for this contract. */
+context?: {
+default_depth?: "brief" | "standard" | "deep";
+activity_limit?: number;
+stale_threshold_days?: number;
+sections?: {
+hierarchy?: boolean;
+activity?: boolean;
+progress?: boolean;
+blockers?: boolean;
+files?: boolean;
+workload?: boolean;
+staleness?: boolean;
+tests?: boolean;
+};
+};
+/** Value that configures or reports extensions for this contract. */
+extensions: {
+enabled: string[];
+disabled: string[];
+policy?: Partial<ExtensionPolicySettings> & {
+pm_max_version_exceeded_mode?: PmMaxVersionExceededModeSetting;
+};
+};
+/** Value that configures or reports search for this contract. */
+search: {
+score_threshold: number;
+hybrid_semantic_weight?: number;
+max_results: number;
+embedding_model: string;
+embedding_corpus_max_characters?: number;
+embedding_batch_size: number;
+embedding_timeout_ms?: number;
+scanner_max_batch_retries: number;
+provider?: string;
+default_mode?: "auto" | "keyword" | "semantic" | "hybrid";
+corpus_fields?: string[];
+mutation_refresh_policy?: "cache_only" | "semantic_configured" | "semantic_auto";
+query_expansion?: {
+enabled?: boolean;
+provider?: string;
+};
+rerank?: {
+enabled?: boolean;
+model?: string;
+top_k?: number;
+};
+bm25?: {
+k1?: number;
+b?: number;
+};
+};
+/** Value that configures or reports providers for this contract. */
+providers: {
+openai: {
+base_url: string;
+api_key: string;
+model: string;
+};
+ollama: {
+base_url: string;
+model: string;
+};
+};
+/** Value that configures or reports vector store for this contract. */
+vector_store: {
+adapter?: string;
+collection_name?: string;
+qdrant: {
+url: string;
+api_key: string;
+};
+lancedb: {
+path: string;
+};
+};
 }
 /** Restricts settings validation result values accepted by command, SDK, and storage contracts. */
 export type SettingsValidationResult = {
-    success: true;
-    data: ParsedSettings;
+success: true;
+data: ParsedSettings;
 } | {
-    success: false;
+success: false;
 };
 /** Validate raw settings, returning stripped, type-checked data or failure (matching the legacy zod safeParse). */
 export declare function validateSettings(raw: unknown): SettingsValidationResult;