/** * Metadata Manager * * Handles CRUD operations for increment metadata (status, type, timestamps). * Part of increment 0007: Smart Status Management */ import { IncrementMetadata, IncrementMetadataExtended, IncrementMetadataV2, IncrementStatus, IncrementType, SyncTarget, PrRef } from '../types/increment-metadata.js'; import { Logger } from '../../utils/logger.js'; /** * Error thrown when metadata operations fail */ export declare class MetadataError extends Error { incrementId: string; cause?: Error | undefined; constructor(message: string, incrementId: string, cause?: Error | undefined); } export declare class MetadataManager { /** * Logger instance (injectable for testing) */ private static logger; /** * When true, updateStatus() stays quiet about intermediate transitions. * * `specweave complete` auto-walks planning → active → ready_for_review → * completed. Announcing "ready for review - run sw:done to close" in the * middle of that walk contradicted the "completed!" line printed two lines * later. Set by completeIncrement() for the duration of the closure. */ static suppressTransitionNotices: boolean; /** * Set logger instance (primarily for testing with silentLogger) * * @param logger - Logger instance to use */ static setLogger(logger: Logger): void; /** * Get metadata file path for increment * * Uses resolveEffectiveRoot() to find the umbrella root in multi-repo setups, * or the nearest project root in single-repo setups. * * SECURITY: Validates increment ID to prevent path traversal attacks. */ private static getMetadataPath; /** * Get increment directory path * * Uses resolveEffectiveRoot() to find the umbrella root in multi-repo setups, * or the nearest project root in single-repo setups. * * SECURITY: Validates increment ID to prevent path traversal attacks. */ private static getIncrementPath; /** * Check if metadata file exists */ static exists(incrementId: string, rootDir?: string): boolean; /** * Read metadata from file * Creates default metadata if file doesn't exist (lazy initialization) */ static read(incrementId: string, rootDir?: string): IncrementMetadata; /** * Reserved increment IDs that cannot be used * These are status values, special folders, and state files */ private static readonly RESERVED_INCREMENT_IDS; /** * Validate increment ID is not a reserved name * Throws if ID is reserved */ private static validateNotReserved; /** * Validate increment before creation (check for duplicates and reserved names) * Throws if duplicates exist in other locations or ID is reserved */ static validateBeforeCreate(incrementId: string, rootDir?: string): Promise; /** * Write metadata to file * Uses atomic write (temp file → rename) * * @param incrementId - Increment ID * @param metadata - Metadata to write * @param rootDir - Optional root directory (defaults to process.cwd()) */ static write(incrementId: string, metadata: IncrementMetadata, rootDir?: string): void; /** * Delete metadata file */ static delete(incrementId: string, rootDir?: string): void; /** * Update increment status * Validates transition and updates timestamps * * **CRITICAL**: Also updates active increment state automatically! * * NOTE: This method is now SYNCHRONOUS to ensure spec.md is updated * before returning. This prevents race conditions in tests and ensures * data consistency. */ static updateStatus(incrementId: string, newStatus: IncrementStatus, reason?: string, rootDir?: string): IncrementMetadata; /** * Update spec.md status synchronously (used by updateStatus) * * This is a private helper to avoid async/await in updateStatus() which would * break backward compatibility with callers expecting sync behavior. */ private static updateSpecMdStatusSync; /** * Update increment type */ static updateType(incrementId: string, type: IncrementType): IncrementMetadata; /** * Touch increment (update lastActivity) */ static touch(incrementId: string): IncrementMetadata; /** * Get all increments * * Uses resolveEffectiveRoot() to find umbrella root in multi-repo setups. */ static getAll(): IncrementMetadata[]; /** * Get increments by status */ static getByStatus(status: IncrementStatus): IncrementMetadata[]; /** * Get active increments (FAST: cache-first strategy) * * **PERFORMANCE UPGRADE**: Uses ActiveIncrementManager cache instead of scanning all increments * - Old: Scan 31 metadata files (~50ms) * - New: Read 1 cache file + 1-2 metadata files (~5ms) = **10x faster** * * Fallback to full scan if cache is stale or missing */ static getActive(): IncrementMetadata[]; /** * Get backlog increments */ static getBacklog(): IncrementMetadata[]; /** * Get paused increments */ static getPaused(): IncrementMetadata[]; /** * Get completed increments */ static getCompleted(): IncrementMetadata[]; /** * Get abandoned increments */ static getAbandoned(): IncrementMetadata[]; /** * Get increments by type */ static getByType(type: IncrementType): IncrementMetadata[]; /** * Get stale increments (paused >7 days or active >30 days) */ static getStale(): IncrementMetadata[]; /** * Get increments that should be auto-abandoned (experiments inactive >14 days) */ static getShouldAutoAbandon(): IncrementMetadata[]; /** * Get extended metadata with computed fields (progress, age, etc.) */ static getExtended(incrementId: string): IncrementMetadataExtended; /** * Validate and auto-correct metadata schema issues. * * Fixes: * - id: short numeric IDs (e.g. "0399") expanded to full slug using folderName * - type: non-standard aliases mapped to canonical enum values * - created/createdAt: legacy field renamed * - externalLinks: ensured to exist (defaults to {}) * - status/priority: sensible defaults applied * * @returns corrected metadata, whether any correction was made, and warnings */ private static validateMetadataSchema; /** * Validate metadata schema */ static validate(metadata: IncrementMetadata): boolean; /** * Check if status transition is allowed */ static canTransition(from: IncrementStatus, to: IncrementStatus): boolean; /** * Get human-readable status transition error message */ static getTransitionError(from: IncrementStatus, to: IncrementStatus): string; /** * Set the external tool sync target for an increment * * This explicitly specifies which sync profile the increment uses. * The sync target provides audit trail and deterministic sync behavior. * * @param incrementId - Increment ID * @param syncTarget - Sync target configuration * @param rootDir - Optional root directory * @returns Updated metadata * * @example * ```typescript * MetadataManager.setSyncTarget('0142-feature', { * profileId: 'github-frontend', * provider: 'github', * derivedFrom: 'project-mapping', * setAt: new Date().toISOString(), * sourceProjectId: 'frontend-app' * }); * ``` */ static setSyncTarget(incrementId: string, syncTarget: SyncTarget, rootDir?: string): IncrementMetadataV2; /** * Get the sync target for an increment * * @param incrementId - Increment ID * @param rootDir - Optional root directory * @returns Sync target or undefined if not set */ static getSyncTarget(incrementId: string, rootDir?: string): SyncTarget | undefined; /** * Clear the sync target for an increment * * Use this when the external tool configuration changes and * the increment needs to be re-resolved. * * @param incrementId - Increment ID * @param rootDir - Optional root directory * @returns Updated metadata */ static clearSyncTarget(incrementId: string, rootDir?: string): IncrementMetadataV2; /** * Check if increment has a sync target configured * * @param incrementId - Increment ID * @param rootDir - Optional root directory * @returns true if sync target is set */ static hasSyncTarget(incrementId: string, rootDir?: string): boolean; /** * Add a pull request reference to an increment (v1.0.437+) * * Appends a PrRef to the prRefs array. Deduplicates by repoSlug * (or by branch name for single-repo increments without repoSlug). * * @param incrementId - Increment ID * @param ref - Pull request reference to add * @param rootDir - Optional root directory * @returns Updated metadata */ static addPrRef(incrementId: string, ref: PrRef, rootDir?: string): IncrementMetadataV2; /** * Get pull request references for an increment * * @param incrementId - Increment ID * @param rootDir - Optional root directory * @returns Array of PR refs, or empty array if none */ static getPrRefs(incrementId: string, rootDir?: string): PrRef[]; /** * Get all increments with a specific sync provider * * Useful for bulk operations on all GitHub/JIRA/ADO synced increments. * * @param provider - Provider type ('github', 'jira', 'ado') * @returns Array of increments with that provider configured */ static getByProvider(provider: 'github' | 'jira' | 'ado'): IncrementMetadataV2[]; /** * Get all increments with a specific sync profile * * @param profileId - Profile ID from config.sync.profiles * @returns Array of increments using that profile */ static getByProfile(profileId: string): IncrementMetadataV2[]; } //# sourceMappingURL=metadata-manager.d.ts.map