@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
196 lines • 6.77 kB
TypeScript
/**
* Retention Policy Types (Issue #51)
*
* Generic interfaces for retention management across all element types.
* Designed to support 50+ element types with type-specific retention strategies.
*
* @module RetentionTypes
*/
import { ElementType } from '../../portfolio/types.js';
/**
* Interface for any item that can be subject to retention policies.
* Element types implement this to enable retention management.
*/
export interface IRetainableItem {
/** Unique identifier for the item */
id: string;
/** When this item was created */
createdAt?: Date;
/** When this item expires (if set) */
expiresAt?: Date;
/** Last time this item was accessed (for LRU-style retention) */
lastAccessedAt?: Date;
/** Content preview for display in dry-run results */
contentPreview?: string;
/** Additional metadata that might affect retention */
metadata?: Record<string, unknown>;
}
/**
* Result of checking a single item for retention
*/
export interface RetentionCheckResult {
/** The item that was checked */
item: IRetainableItem;
/** Whether this item should be retained (true) or removed (false) */
shouldRetain: boolean;
/** Reason for the retention decision */
reason: RetentionReason;
/** Days until expiry (negative if already expired) */
daysUntilExpiry?: number;
}
/**
* Reasons why an item might be retained or removed
*/
export type RetentionReason = 'not_expired' | 'expired' | 'capacity_exceeded' | 'manual_request' | 'no_expiry_set' | 'pinned' | 'within_warning' | 'lru_eviction' | 'policy_disabled';
/**
* Configuration for retention policy per element type
*/
export interface ElementRetentionConfig {
/** Whether retention is enabled for this element type */
enabled: boolean;
/** Default TTL in days for new items (-1 for permanent) */
defaultTtlDays: number;
/** Maximum number of items before capacity enforcement (-1 for unlimited) */
maxItems: number;
/** Enforcement mode for this element type */
enforcementMode: RetentionEnforcementMode;
/** Whether items can be pinned to prevent deletion */
allowPinning: boolean;
/** Custom settings specific to the element type */
custom?: Record<string, unknown>;
}
/**
* When retention enforcement happens
*/
export type RetentionEnforcementMode = 'disabled' | 'manual' | 'on_load' | 'on_save' | 'scheduled';
/**
* Result of a retention enforcement operation
*/
export interface RetentionEnforcementResult {
/** Element type this result applies to */
elementType: ElementType | string;
/** Whether the operation was successful */
success: boolean;
/** Number of items checked */
itemsChecked: number;
/** Number of items that would be/were removed */
itemsRemoved: number;
/** Details of items affected */
affectedItems: RetentionCheckResult[];
/** Whether this was a dry run (preview only) */
dryRun: boolean;
/** Warning messages */
warnings: string[];
/** Error message if operation failed */
error?: string;
/** Timestamp of the operation */
timestamp: Date;
}
/**
* Summary of expiring items across element types
*/
export interface RetentionSummary {
/** Items expiring within warning threshold */
expiringSoon: Array<{
elementType: ElementType | string;
itemId: string;
contentPreview: string;
expiresAt: Date;
daysUntilExpiry: number;
}>;
/** Items that have already expired */
alreadyExpired: Array<{
elementType: ElementType | string;
itemId: string;
contentPreview: string;
expiresAt: Date;
daysOverdue: number;
}>;
/** Per-type counts */
countsByType: Record<string, {
total: number;
expiringSoon: number;
expired: number;
}>;
}
/**
* Strategy interface for element-type specific retention logic.
* Each element type that supports retention implements this interface.
*/
export interface IRetentionStrategy<T extends IRetainableItem = IRetainableItem> {
/** The element type this strategy handles */
readonly elementType: ElementType | string;
/**
* Get all retainable items from an element
* @param element - The parent element containing items
* @returns Map of item ID to retainable item
*/
getRetainableItems(element: unknown): Map<string, T>;
/**
* Check a single item against retention policy
* @param item - The item to check
* @param config - Retention configuration
* @returns Check result with retention decision
*/
checkItem(item: T, config: ElementRetentionConfig): RetentionCheckResult;
/**
* Remove an item from its parent element
* @param element - The parent element
* @param itemId - ID of item to remove
*/
removeItem(element: unknown, itemId: string): void;
/**
* Calculate expiry date for a new item
* @param config - Retention configuration
* @returns Expiry date, or undefined if permanent
*/
calculateExpiryDate(config: ElementRetentionConfig): Date | undefined;
/**
* Check if an item is pinned (exempt from retention)
* @param item - The item to check
* @returns True if item should never be deleted
*/
isPinned(item: T): boolean;
/**
* Get a content preview for display
* @param item - The item
* @param maxLength - Maximum preview length
* @returns Truncated content for display
*/
getContentPreview(item: T, maxLength?: number): string;
}
/**
* Options for retention enforcement
*/
export interface EnforcementOptions {
/** Force enforcement even if dry_run_first is enabled */
force?: boolean;
/** Name/identifier of the element being processed */
elementName?: string;
/** Skip confirmation even if required */
skipConfirmation?: boolean;
/** Callback for progress updates */
onProgress?: (processed: number, total: number) => void;
/** Stop on first error instead of continuing (prevents partial failures) */
failFast?: boolean;
}
/**
* Global retention policy defaults
*/
export declare const RETENTION_DEFAULTS: {
/** Default TTL in days */
readonly DEFAULT_TTL_DAYS: 30;
/** Minimum TTL in days */
readonly MIN_TTL_DAYS: 1;
/** Maximum TTL in days */
readonly MAX_TTL_DAYS: 3650;
/** Default warning threshold in days */
readonly WARNING_THRESHOLD_DAYS: 7;
/** Default max items per element */
readonly DEFAULT_MAX_ITEMS: 1000;
/** Default backup retention days */
readonly BACKUP_RETENTION_DAYS: 30;
/** Maximum content preview length */
readonly MAX_PREVIEW_LENGTH: 100;
};
//# sourceMappingURL=types.d.ts.map