@schnick371/devsteps-shared 0.0.1 → 0.5.0

package/src/types/commands.ts

@@ -0,0 +1,116 @@
+import type { EisenhowerQuadrant, ItemType, Priority } from '../schemas/index.js';
+
+/**
+ * Central type shortcuts mapping
+ */
+export const TYPE_SHORTCUTS: Record<string, ItemType> = {
+  epic: 'epic',
+  story: 'story',
+  task: 'task',
+  req: 'requirement',
+  feat: 'feature',
+  bug: 'bug',
+  spike: 'spike',
+  test: 'test',
+} as const;
+
+/**
+ * Command argument types - central source of truth
+ */
+
+export interface AddItemCommandArgs {
+  type: string; // Will be mapped via TYPE_SHORTCUTS
+  title: string;
+  description?: string;
+  category?: string;
+  priority?: string;
+  eisenhower?: string;
+  tags?: string[];
+  assignee?: string;
+  paths?: string[];
+}
+
+export interface UpdateItemCommandArgs {
+  id: string;
+  status?: string;
+  priority?: string;
+  eisenhower?: string;
+  superseded_by?: string;
+  title?: string;
+  description?: string;
+  assignee?: string;
+  tags?: string[];
+  paths?: string[];
+}
+
+export interface ListItemsCommandArgs {
+  type?: string;
+  status?: string;
+  priority?: string;
+  eisenhower?: string;
+  assignee?: string;
+  tags?: string[];
+  archived?: boolean;
+  limit?: string;
+}
+
+export interface SearchItemsCommandArgs {
+  query: string;
+  type?: string;
+  limit?: string;
+}
+
+export interface StatusCommandArgs {
+  detailed?: boolean;
+}
+
+export interface TraceCommandArgs {
+  id: string;
+  depth?: string;
+}
+
+export interface ExportCommandArgs {
+  format?: string;
+  output?: string;
+  types?: string[];
+}
+
+export interface ArchiveCommandArgs {
+  id: string;
+}
+
+export interface PurgeCommandArgs {
+  status?: string[];
+  type?: string;
+}
+
+/**
+ * Response types
+ */
+
+export interface CommandSuccessResponse {
+  success: true;
+  message: string;
+  [key: string]: unknown;
+}
+
+export interface CommandErrorResponse {
+  success: false;
+  error: string;
+}
+
+export type CommandResponse = CommandSuccessResponse | CommandErrorResponse;
+
+/**
+ * Index item summary type (from index.json)
+ */
+export interface IndexItem {
+  id: string;
+  type: ItemType;
+  title: string;
+  status: string;
+  priority: Priority;
+  updated: string;
+  tags?: string[];
+  category?: string;
+}

package/src/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAYA,gDAA8B"}

package/src/types/index.ts

@@ -0,0 +1,13 @@
+export type {
+  ItemType,
+  ItemStatus,
+  Priority,
+  RelationType,
+  LinkedItems,
+  GitCommit,
+  ItemMetadata,
+  DevCrumbsConfig,
+  DevCrumbsIndex,
+} from '../schemas/index.js';
+
+export * from './commands.js';

package/src/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["cache.ts"],"names":[],"mappings":"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"}

package/src/utils/cache.ts

@@ -0,0 +1,200 @@
+import { statSync } from 'node:fs';
+
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  mtime?: number; // for file-based invalidation
+}
+
+export interface CacheStats {
+  size: number;
+  keys: string[];
+  hits: number;
+  misses: number;
+  hitRate: number;
+}
+
+/**
+ * Cache configuration
+ */
+export const CACHE_CONFIG = {
+  PROJECT_MD_TTL: 60 * 60 * 1000, // 1 hour
+  PACKAGE_ANALYSIS_TTL: 30 * 60 * 1000, // 30 minutes
+  ITEM_COUNTS_TTL: 5 * 60 * 1000, // 5 minutes
+  RECENT_UPDATES_TTL: 1 * 60 * 1000, // 1 minute
+  MAX_CACHE_SIZE: 1000, // Maximum number of cache entries
+};
+
+/**
+ * Smart context cache with TTL and file-based invalidation
+ */
+export class ContextCache {
+  private cache = new Map<string, CacheEntry<unknown>>();
+  private hits = 0;
+  private misses = 0;
+
+  /**
+   * Get cached value
+   * @param key Cache key
+   * @param maxAge Maximum age in milliseconds
+   * @param filePath Optional file path for mtime-based invalidation
+   * @returns Cached value or null if invalid/expired
+   */
+  get<T>(key: string, maxAge: number, filePath?: string): T | null {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    // Check file modification time
+    if (filePath && entry.mtime !== undefined) {
+      try {
+        const currentMtime = statSync(filePath).mtimeMs;
+        if (currentMtime > entry.mtime) {
+          this.cache.delete(key);
+          this.misses++;
+          return null;
+        }
+      } catch {
+        // File doesn't exist anymore, invalidate cache
+        this.cache.delete(key);
+        this.misses++;
+        return null;
+      }
+    }
+
+    // Check TTL
+    if (Date.now() - entry.timestamp > maxAge) {
+      this.cache.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    this.hits++;
+    return entry.data as T;
+  }
+
+  /**
+   * Set cached value
+   * @param key Cache key
+   * @param data Data to cache
+   * @param filePath Optional file path for mtime tracking
+   */
+  set<T>(key: string, data: T, filePath?: string): void {
+    // Enforce max cache size (simple LRU: remove oldest)
+    if (this.cache.size >= CACHE_CONFIG.MAX_CACHE_SIZE) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    let mtime: number | undefined;
+    if (filePath) {
+      try {
+        mtime = statSync(filePath).mtimeMs;
+      } catch {
+        // File doesn't exist, don't track mtime
+        mtime = undefined;
+      }
+    }
+
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      mtime,
+    });
+  }
+
+  /**
+   * Check if key exists and is valid
+   * @param key Cache key
+   * @param maxAge Maximum age in milliseconds
+   * @param filePath Optional file path for mtime-based invalidation
+   * @returns true if valid cached value exists
+   */
+  has(key: string, maxAge: number, filePath?: string): boolean {
+    return this.get(key, maxAge, filePath) !== null;
+  }
+
+  /**
+   * Clear entire cache
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Clear specific cache key
+   * @param key Cache key to clear
+   */
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear cache entries matching pattern
+   * @param pattern Regex pattern to match keys
+   */
+  clearPattern(pattern: RegExp): number {
+    let cleared = 0;
+    for (const key of this.cache.keys()) {
+      if (pattern.test(key)) {
+        this.cache.delete(key);
+        cleared++;
+      }
+    }
+    return cleared;
+  }
+
+  /**
+   * Get cache statistics
+   * @returns Cache statistics including hit rate
+   */
+  stats(): CacheStats {
+    const total = this.hits + this.misses;
+    const hitRate = total > 0 ? this.hits / total : 0;
+
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys()),
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: Math.round(hitRate * 100) / 100,
+    };
+  }
+
+  /**
+   * Reset hit/miss counters
+   */
+  resetStats(): void {
+    this.hits = 0;
+    this.misses = 0;
+  }
+}
+
+// Global singleton instance
+let globalCache: ContextCache | null = null;
+
+/**
+ * Get or create global cache instance
+ */
+export function getCache(): ContextCache {
+  if (!globalCache) {
+    globalCache = new ContextCache();
+  }
+  return globalCache;
+}
+
+/**
+ * Clear global cache
+ */
+export function clearGlobalCache(): void {
+  if (globalCache) {
+    globalCache.clear();
+  }
+}

package/src/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/src/utils/index.ts

@@ -0,0 +1,170 @@
+import type { ItemType, Methodology } from '../schemas/index.js';
+
+// Export cache utilities
+export {
+  ContextCache,
+  CACHE_CONFIG,
+  getCache,
+  clearGlobalCache,
+  type CacheStats,
+} from './cache.js';
+
+/**
+ * Type to plural directory mapping
+ */
+export const TYPE_TO_DIRECTORY: Record<ItemType, string> = {
+  epic: 'epics',
+  story: 'stories',
+  task: 'tasks',
+  requirement: 'requirements',
+  feature: 'features',
+  bug: 'bugs',
+  spike: 'spikes',
+  test: 'tests',
+};
+
+/**
+ * Get methodology configuration
+ */
+export function getMethodologyConfig(methodology: Methodology) {
+  const configs = {
+    scrum: {
+      item_types: ['epic', 'story', 'task', 'bug', 'spike', 'test'] as ItemType[],
+      item_prefixes: {
+        epic: 'EPIC',
+        story: 'STORY',
+        task: 'TASK',
+        bug: 'BUG',
+        spike: 'SPIKE',
+        test: 'TEST',
+      },
+      directories: ['epics', 'stories', 'tasks', 'bugs', 'spikes', 'tests'],
+    },
+    waterfall: {
+      item_types: ['requirement', 'feature', 'task', 'bug', 'test'] as ItemType[],
+      item_prefixes: {
+        requirement: 'REQ',
+        feature: 'FEAT',
+        task: 'TASK',
+        bug: 'BUG',
+        test: 'TEST',
+      },
+      directories: ['requirements', 'features', 'tasks', 'bugs', 'tests'],
+    },
+    hybrid: {
+      item_types: [
+        'epic',
+        'story',
+        'requirement',
+        'feature',
+        'task',
+        'bug',
+        'spike',
+        'test',
+      ] as ItemType[],
+      item_prefixes: {
+        epic: 'EPIC',
+        story: 'STORY',
+        requirement: 'REQ',
+        feature: 'FEAT',
+        task: 'TASK',
+        bug: 'BUG',
+        spike: 'SPIKE',
+        test: 'TEST',
+      },
+      directories: [
+        'epics',
+        'stories',
+        'requirements',
+        'features',
+        'tasks',
+        'bugs',
+        'spikes',
+        'tests',
+      ],
+    },
+  };
+
+  return configs[methodology];
+}
+
+/**
+ * Generates a new item ID with proper prefix and number
+ */
+export function generateItemId(
+  type: string,
+  counter: number,
+  prefixes?: Record<string, string>
+): string {
+  const defaultPrefixes: Record<string, string> = {
+    epic: 'EPIC',
+    story: 'STORY',
+    task: 'TASK',
+    requirement: 'REQ',
+    feature: 'FEAT',
+    bug: 'BUG',
+    spike: 'SPIKE',
+    test: 'TEST',
+  };
+
+  const prefixMap = prefixes || defaultPrefixes;
+  const prefix = prefixMap[type] || 'ITEM';
+  const paddedNumber = counter.toString().padStart(3, '0');
+  return `${prefix}-${paddedNumber}`;
+}
+
+/**
+ * Parses an item ID into type and number
+ */
+export function parseItemId(id: string): { type: ItemType; number: number } | null {
+  const match = id.match(/^(EPIC|STORY|TASK|REQ|FEAT|BUG|SPIKE|TEST)-(\d+)$/);
+  if (!match) return null;
+
+  const typeMap: Record<string, ItemType> = {
+    EPIC: 'epic',
+    STORY: 'story',
+    TASK: 'task',
+    REQ: 'requirement',
+    FEAT: 'feature',
+    BUG: 'bug',
+    SPIKE: 'spike',
+    TEST: 'test',
+  };
+
+  return {
+    type: typeMap[match[1]],
+    number: Number.parseInt(match[2], 10),
+  };
+}
+
+/**
+ * Formats a date for display
+ */
+export function formatDate(date: string | Date): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  return d.toISOString();
+}
+
+/**
+ * Gets current timestamp in ISO format
+ */
+export function getCurrentTimestamp(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Validates email format
+ */
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+/**
+ * Sanitizes a string for use in filenames
+ */
+export function sanitizeFilename(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}

package/index.js

@@ -1,6 +0,0 @@
-// DevSteps Shared - Reserved Package
-// Full implementation coming soon
-module.exports = {
-  version: '0.0.1',
-  status: 'reserved'
-};