prjct-cli 0.11.4 → 0.12.0

package/core/utils/{session-helper.js → session-helper.ts}

@@ -1,7 +1,7 @@
-const path = require('path')
-const dateHelper = require('./date-helper')
-const jsonlHelper = require('./jsonl-helper')
-const fileHelper = require('./file-helper')
+import path from 'path'
+import * as dateHelper from './date-helper'
+import * as jsonlHelper from './jsonl-helper'
+import * as fileHelper from './file-helper'
 
 /**
  * Session Helper - High-level session operations
@@ -11,19 +11,37 @@ const fileHelper = require('./file-helper')
  * - jsonl-helper (JSONL parsing)
  * - file-helper (file operations)
  * - path-manager (path construction)
- *
- * @module session-helper
  */
 
+interface SessionEntry {
+  ts?: string
+  timestamp?: string
+  type?: string
+  [key: string]: unknown
+}
+
+interface SessionStats {
+  totalEntries: number
+  byType: Record<string, number>
+  byDate: Record<string, number>
+  activeDays: number
+  averagePerDay: number
+}
+
+interface ArchiveResult {
+  archived: number
+  files: string[]
+  errors: Array<{ filename: string; error: string }>
+}
+
 /**
  * Build session file path for today
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @param {string} filename - Filename (e.g., '2025-10-04.jsonl')
- * @returns {string} - Full path to session file
  */
-function getTodaySessionFilePath(projectGlobalPath, layer, filename = null) {
+export function getTodaySessionFilePath(
+  projectGlobalPath: string,
+  layer: string,
+  filename: string | null = null
+): string {
   const today = dateHelper.getTodayKey()
   const yearMonth = dateHelper.formatMonth(new Date())
   const [year, month] = yearMonth.split('-')
@@ -39,12 +57,11 @@ function getTodaySessionFilePath(projectGlobalPath, layer, filename = null) {
 
 /**
  * Ensure today's session directory exists
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @returns {Promise<string>} - Path to session directory
  */
-async function ensureTodaySessionDir(projectGlobalPath, layer) {
+export async function ensureTodaySessionDir(
+  projectGlobalPath: string,
+  layer: string
+): Promise<string> {
   const yearMonth = dateHelper.formatMonth(new Date())
   const [year, month] = yearMonth.split('-')
 
@@ -56,14 +73,13 @@ async function ensureTodaySessionDir(projectGlobalPath, layer) {
 
 /**
  * Write log entry to today's session
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @param {Object} entry - Log entry to write
- * @param {string} filename - Optional custom filename (defaults to YYYY-MM-DD.jsonl)
- * @returns {Promise<void>}
  */
-async function writeToSession(projectGlobalPath, layer, entry, filename = null) {
+export async function writeToSession(
+  projectGlobalPath: string,
+  layer: string,
+  entry: SessionEntry,
+  filename: string | null = null
+): Promise<void> {
   await ensureTodaySessionDir(projectGlobalPath, layer)
 
   const filePath = getTodaySessionFilePath(projectGlobalPath, layer, filename)
@@ -78,31 +94,29 @@ async function writeToSession(projectGlobalPath, layer, entry, filename = null)
 
 /**
  * Read today's session logs
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @param {string} filename - Optional custom filename
- * @returns {Promise<Array<Object>>} - Array of log entries
  */
-async function readTodaySession(projectGlobalPath, layer, filename = null) {
+export async function readTodaySession<T = SessionEntry>(
+  projectGlobalPath: string,
+  layer: string,
+  filename: string | null = null
+): Promise<T[]> {
   const filePath = getTodaySessionFilePath(projectGlobalPath, layer, filename)
-  return await jsonlHelper.readJsonLines(filePath)
+  return await jsonlHelper.readJsonLines<T>(filePath)
 }
 
 /**
  * Read session logs for a date range
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @param {number} daysBack - Number of days to look back
- * @returns {Promise<Array<Object>>} - Array of all log entries
  */
-async function readRecentSessions(projectGlobalPath, layer, daysBack = 7) {
+export async function readRecentSessions<T = SessionEntry>(
+  projectGlobalPath: string,
+  layer: string,
+  daysBack = 7
+): Promise<T[]> {
   const fromDate = dateHelper.getDaysAgo(daysBack)
   const toDate = new Date()
 
   const dates = dateHelper.getDateRange(fromDate, toDate)
-  const allEntries = []
+  const allEntries: T[] = []
 
   for (const date of dates) {
     const yearMonth = dateHelper.formatMonth(date)
@@ -118,7 +132,7 @@ async function readRecentSessions(projectGlobalPath, layer, daysBack = 7) {
       `${dateKey}.jsonl`
     )
 
-    const entries = await jsonlHelper.readJsonLines(filePath)
+    const entries = await jsonlHelper.readJsonLines<T>(filePath)
     allEntries.push(...entries)
   }
 
@@ -127,24 +141,23 @@ async function readRecentSessions(projectGlobalPath, layer, daysBack = 7) {
 
 /**
  * Get session statistics for a layer
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @param {number} daysBack - Number of days to analyze
- * @returns {Promise<Object>} - Statistics object
  */
-async function getSessionStats(projectGlobalPath, layer, daysBack = 30) {
-  const entries = await readRecentSessions(projectGlobalPath, layer, daysBack)
+export async function getSessionStats(
+  projectGlobalPath: string,
+  layer: string,
+  daysBack = 30
+): Promise<SessionStats> {
+  const entries = await readRecentSessions<SessionEntry>(projectGlobalPath, layer, daysBack)
 
   // Group by type
-  const byType = {}
+  const byType: Record<string, number> = {}
   for (const entry of entries) {
     const type = entry.type || 'unknown'
     byType[type] = (byType[type] || 0) + 1
   }
 
   // Group by date
-  const byDate = {}
+  const byDate: Record<string, number> = {}
   for (const entry of entries) {
     const timestamp = entry.ts || entry.timestamp
     if (timestamp) {
@@ -164,13 +177,12 @@ async function getSessionStats(projectGlobalPath, layer, daysBack = 30) {
 
 /**
  * Archive old session data (move sessions older than N days)
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @param {number} daysToKeep - Keep sessions newer than this (default: 30)
- * @returns {Promise<Object>} - Archive result
  */
-async function archiveOldSessions(projectGlobalPath, layer, daysToKeep = 30) {
+export async function archiveOldSessions(
+  projectGlobalPath: string,
+  layer: string,
+  daysToKeep = 30
+): Promise<ArchiveResult> {
   const cutoffDate = dateHelper.getDaysAgo(daysToKeep)
   const archiveDir = path.join(projectGlobalPath, layer, 'archive')
   await fileHelper.ensureDir(archiveDir)
@@ -178,8 +190,8 @@ async function archiveOldSessions(projectGlobalPath, layer, daysToKeep = 30) {
   const sessionsDir = path.join(projectGlobalPath, layer, 'sessions')
 
   // Find all session files older than cutoff
-  const archived = []
-  const errors = []
+  const archived: string[] = []
+  const errors: Array<{ filename: string; error: string }> = []
 
   try {
     const years = await fileHelper.listFiles(sessionsDir, { dirsOnly: true })
@@ -206,13 +218,13 @@ async function archiveOldSessions(projectGlobalPath, layer, daysToKeep = 30) {
               await fileHelper.moveFile(sourcePath, destPath)
               archived.push(filename)
             } catch (error) {
-              errors.push({ filename, error: error.message })
+              errors.push({ filename, error: (error as Error).message })
             }
           }
         }
       }
     }
-  } catch (error) {
+  } catch {
     // Sessions directory might not exist yet
   }
 
@@ -225,12 +237,11 @@ async function archiveOldSessions(projectGlobalPath, layer, daysToKeep = 30) {
 
 /**
  * Clean empty session directories
- *
- * @param {string} projectGlobalPath - Global project path
- * @param {string} layer - Layer (planning/progress/memory)
- * @returns {Promise<number>} - Number of directories removed
  */
-async function cleanEmptySessionDirs(projectGlobalPath, layer) {
+export async function cleanEmptySessionDirs(
+  projectGlobalPath: string,
+  layer: string
+): Promise<number> {
   const sessionsDir = path.join(projectGlobalPath, layer, 'sessions')
   let cleaned = 0
 
@@ -258,14 +269,15 @@ async function cleanEmptySessionDirs(projectGlobalPath, layer) {
         cleaned++
       }
     }
-  } catch (error) {
+  } catch {
     // Sessions directory might not exist
   }
 
   return cleaned
 }
 
-module.exports = {
+// Default export for CommonJS compatibility
+export default {
   getTodaySessionFilePath,
   ensureTodaySessionDir,
   writeToSession,
@@ -273,5 +285,6 @@ module.exports = {
   readRecentSessions,
   getSessionStats,
   archiveOldSessions,
-  cleanEmptySessionDirs,
+  cleanEmptySessionDirs
 }
+

package/core/utils/{version.js → version.ts}

@@ -1,46 +1,47 @@
-const fs = require('fs')
-const path = require('path')
+import fs from 'fs'
+import path from 'path'
 
 /**
  * Version Manager - Single source of truth for application version
  *
  * Reads version from package.json dynamically to ensure consistency
  * across the entire application.
- *
- * @module version
  */
 
-let cachedVersion = null
-let cachedPackageJson = null
+interface PackageJson {
+  version: string
+  name?: string
+  description?: string
+  [key: string]: unknown
+}
+
+let cachedVersion: string | null = null
+let cachedPackageJson: PackageJson | null = null
 
 /**
  * Get the current application version from package.json
- *
- * @returns {string} - Semantic version string (e.g., "0.2.1")
  */
-function getVersion() {
+export function getVersion(): string {
   if (cachedVersion) {
     return cachedVersion
   }
 
   try {
     const packageJsonPath = path.join(__dirname, '..', '..', 'package.json')
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
+    const packageJson: PackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
     cachedVersion = packageJson.version
     cachedPackageJson = packageJson
     return cachedVersion
   } catch (error) {
-    console.error('Failed to read version from package.json:', error.message)
+    console.error('Failed to read version from package.json:', (error as Error).message)
     return '0.0.0'
   }
 }
 
 /**
  * Get the full package.json object
- *
- * @returns {Object} - Package.json contents
  */
-function getPackageInfo() {
+export function getPackageInfo(): PackageJson | null {
   if (!cachedPackageJson) {
     getVersion()
   }
@@ -49,12 +50,9 @@ function getPackageInfo() {
 
 /**
  * Compare two semantic version strings
- *
- * @param {string} v1 - First version (e.g., "0.2.1")
- * @param {string} v2 - Second version (e.g., "0.2.0")
- * @returns {number} - Returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ * @returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
  */
-function compareVersions(v1, v2) {
+export function compareVersions(v1: string, v2: string): number {
   const parts1 = v1.split('.').map(Number)
   const parts2 = v2.split('.').map(Number)
 
@@ -71,11 +69,8 @@ function compareVersions(v1, v2) {
 
 /**
  * Check if a config version is compatible with current version
- *
- * @param {string} configVersion - Version from config file
- * @returns {boolean} - True if compatible
  */
-function isCompatible(configVersion) {
+export function isCompatible(configVersion: string): boolean {
   const current = getVersion()
   const [currentMajor, currentMinor] = current.split('.').map(Number)
   const [configMajor, configMinor] = configVersion.split('.').map(Number)
@@ -85,23 +80,20 @@ function isCompatible(configVersion) {
 
 /**
  * Check if migration is needed based on version comparison
- *
- * @param {string} fromVersion - Current config version
- * @param {string} toVersion - Target version (defaults to current)
- * @returns {boolean} - True if migration needed
  */
-function needsMigration(fromVersion, toVersion = null) {
+export function needsMigration(fromVersion: string, toVersion: string | null = null): boolean {
   const target = toVersion || getVersion()
   return compareVersions(fromVersion, target) < 0
 }
 
-const VERSION = getVersion()
+export const VERSION = getVersion()
 
-module.exports = {
-  VERSION,
+// Default export for CommonJS compatibility
+export default {
   getVersion,
   getPackageInfo,
   compareVersions,
   isCompatible,
   needsMigration,
+  VERSION
 }