prjct-cli 0.6.0 → 0.7.0

package/core/utils/file-helper.js

@@ -0,0 +1,327 @@
+const fs = require('fs').promises
+const path = require('path')
+
+/**
+ * File Helper - Centralized file operations with error handling
+ *
+ * Eliminates duplicated fs operations across:
+ * - 101 fs.readFile/writeFile calls in 18 files
+ * - Consistent error handling
+ * - JSON read/write patterns
+ *
+ * @module file-helper
+ */
+
+/**
+ * Read JSON file and parse
+ *
+ * @param {string} filePath - Path to JSON file
+ * @param {*} defaultValue - Default value if file doesn't exist (default: null)
+ * @returns {Promise<Object|*>} - Parsed JSON or default value
+ */
+async function readJson(filePath, defaultValue = null) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    return JSON.parse(content)
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return defaultValue
+    }
+    throw error
+  }
+}
+
+/**
+ * Write object to JSON file (pretty-printed)
+ *
+ * @param {string} filePath - Path to JSON file
+ * @param {Object} data - Data to write
+ * @param {number} indent - Indentation spaces (default: 2)
+ * @returns {Promise<void>}
+ */
+async function writeJson(filePath, data, indent = 2) {
+  const content = JSON.stringify(data, null, indent)
+  await fs.writeFile(filePath, content, 'utf-8')
+}
+
+/**
+ * Read text file
+ *
+ * @param {string} filePath - Path to file
+ * @param {string} defaultValue - Default value if file doesn't exist (default: '')
+ * @returns {Promise<string>} - File content or default value
+ */
+async function readFile(filePath, defaultValue = '') {
+  try {
+    return await fs.readFile(filePath, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return defaultValue
+    }
+    throw error
+  }
+}
+
+/**
+ * Write text file
+ *
+ * @param {string} filePath - Path to file
+ * @param {string} content - Content to write
+ * @returns {Promise<void>}
+ */
+async function writeFile(filePath, content) {
+  await fs.writeFile(filePath, content, 'utf-8')
+}
+
+/**
+ * Append to text file
+ *
+ * @param {string} filePath - Path to file
+ * @param {string} content - Content to append
+ * @returns {Promise<void>}
+ */
+async function appendToFile(filePath, content) {
+  await fs.appendFile(filePath, content, 'utf-8')
+}
+
+/**
+ * Prepend to text file (adds content at beginning)
+ *
+ * @param {string} filePath - Path to file
+ * @param {string} content - Content to prepend
+ * @returns {Promise<void>}
+ */
+async function prependToFile(filePath, content) {
+  try {
+    const existing = await fs.readFile(filePath, 'utf-8')
+    await fs.writeFile(filePath, content + existing, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      await fs.writeFile(filePath, content, 'utf-8')
+    } else {
+      throw error
+    }
+  }
+}
+
+/**
+ * Check if file exists
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<boolean>} - True if file exists
+ */
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if directory exists
+ *
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<boolean>} - True if directory exists
+ */
+async function dirExists(dirPath) {
+  try {
+    const stats = await fs.stat(dirPath)
+    return stats.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Ensure directory exists (create if not)
+ *
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<void>}
+ */
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true })
+}
+
+/**
+ * Delete file if it exists
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<boolean>} - True if file was deleted
+ */
+async function deleteFile(filePath) {
+  try {
+    await fs.unlink(filePath)
+    return true
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return false // File didn't exist
+    }
+    throw error
+  }
+}
+
+/**
+ * Delete directory and all contents
+ *
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<boolean>} - True if directory was deleted
+ */
+async function deleteDir(dirPath) {
+  try {
+    await fs.rm(dirPath, { recursive: true, force: true })
+    return true
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return false
+    }
+    throw error
+  }
+}
+
+/**
+ * List files in directory
+ *
+ * @param {string} dirPath - Path to directory
+ * @param {Object} options - Options
+ * @param {boolean} options.filesOnly - Only return files (not directories)
+ * @param {boolean} options.dirsOnly - Only return directories
+ * @param {string} options.extension - Filter by file extension (e.g., '.md')
+ * @returns {Promise<Array<string>>} - Array of filenames
+ */
+async function listFiles(dirPath, options = {}) {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true })
+    let files = entries
+
+    if (options.filesOnly) {
+      files = files.filter((entry) => entry.isFile())
+    }
+
+    if (options.dirsOnly) {
+      files = files.filter((entry) => entry.isDirectory())
+    }
+
+    if (options.extension) {
+      files = files.filter((entry) => entry.name.endsWith(options.extension))
+    }
+
+    return files.map((entry) => entry.name)
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return []
+    }
+    throw error
+  }
+}
+
+/**
+ * Get file size in bytes
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<number>} - File size in bytes
+ */
+async function getFileSize(filePath) {
+  const stats = await fs.stat(filePath)
+  return stats.size
+}
+
+/**
+ * Get file modification time
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<Date>} - Last modification time
+ */
+async function getFileModifiedTime(filePath) {
+  const stats = await fs.stat(filePath)
+  return stats.mtime
+}
+
+/**
+ * Copy file
+ *
+ * @param {string} sourcePath - Source file path
+ * @param {string} destPath - Destination file path
+ * @returns {Promise<void>}
+ */
+async function copyFile(sourcePath, destPath) {
+  await fs.copyFile(sourcePath, destPath)
+}
+
+/**
+ * Move/rename file
+ *
+ * @param {string} oldPath - Current file path
+ * @param {string} newPath - New file path
+ * @returns {Promise<void>}
+ */
+async function moveFile(oldPath, newPath) {
+  await fs.rename(oldPath, newPath)
+}
+
+/**
+ * Read file and split into lines
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<Array<string>>} - Array of lines
+ */
+async function readLines(filePath) {
+  const content = await readFile(filePath, '')
+  return content.split('\n')
+}
+
+/**
+ * Write lines to file
+ *
+ * @param {string} filePath - Path to file
+ * @param {Array<string>} lines - Array of lines
+ * @returns {Promise<void>}
+ */
+async function writeLines(filePath, lines) {
+  const content = lines.join('\n')
+  await writeFile(filePath, content)
+}
+
+/**
+ * Get file extension
+ *
+ * @param {string} filePath - Path to file
+ * @returns {string} - File extension (e.g., '.md')
+ */
+function getFileExtension(filePath) {
+  return path.extname(filePath)
+}
+
+/**
+ * Get filename without extension
+ *
+ * @param {string} filePath - Path to file
+ * @returns {string} - Filename without extension
+ */
+function getFileNameWithoutExtension(filePath) {
+  return path.basename(filePath, path.extname(filePath))
+}
+
+module.exports = {
+  readJson,
+  writeJson,
+  readFile,
+  writeFile,
+  appendToFile,
+  prependToFile,
+  fileExists,
+  dirExists,
+  ensureDir,
+  deleteFile,
+  deleteDir,
+  listFiles,
+  getFileSize,
+  getFileModifiedTime,
+  copyFile,
+  moveFile,
+  readLines,
+  writeLines,
+  getFileExtension,
+  getFileNameWithoutExtension,
+}

package/core/utils/jsonl-helper.js

@@ -0,0 +1,206 @@
+const fs = require('fs').promises
+
+/**
+ * JSONL Helper - Centralized JSONL parsing and writing
+ *
+ * Eliminates duplicated JSONL logic across:
+ * - session-manager.js (_parseJsonLines)
+ * - commands.js (inline parsing)
+ * - analyzer.js (inline parsing)
+ *
+ * JSONL Format: One JSON object per line, newline-separated
+ * Example:
+ * {"ts":"2025-10-04T14:30:00Z","type":"feature_add","name":"auth"}
+ * {"ts":"2025-10-04T15:00:00Z","type":"task_start","task":"JWT"}
+ *
+ * @module jsonl-helper
+ */
+
+/**
+ * Parse JSONL content into array of objects
+ * Handles malformed lines gracefully (skips them)
+ *
+ * @param {string} content - JSONL content
+ * @returns {Array<Object>} - Array of parsed objects
+ */
+function parseJsonLines(content) {
+  const lines = content.split('\n').filter((line) => line.trim())
+  const entries = []
+
+  for (const line of lines) {
+    try {
+      entries.push(JSON.parse(line))
+    } catch (error) {
+      // Skip malformed lines silently
+      // Could optionally log warning
+    }
+  }
+
+  return entries
+}
+
+/**
+ * Convert array of objects to JSONL string
+ *
+ * @param {Array<Object>} objects - Array of objects to stringify
+ * @returns {string} - JSONL formatted string
+ */
+function stringifyJsonLines(objects) {
+  return objects.map((obj) => JSON.stringify(obj)).join('\n') + '\n'
+}
+
+/**
+ * Read and parse JSONL file
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @returns {Promise<Array<Object>>} - Array of parsed objects
+ */
+async function readJsonLines(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    return parseJsonLines(content)
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return [] // File doesn't exist, return empty array
+    }
+    throw error
+  }
+}
+
+/**
+ * Write array of objects to JSONL file (overwrites)
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @param {Array<Object>} objects - Array of objects to write
+ * @returns {Promise<void>}
+ */
+async function writeJsonLines(filePath, objects) {
+  const content = stringifyJsonLines(objects)
+  await fs.writeFile(filePath, content, 'utf-8')
+}
+
+/**
+ * Append a single object to JSONL file
+ * Uses append mode for efficiency (no full file read/write)
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @param {Object} object - Object to append
+ * @returns {Promise<void>}
+ */
+async function appendJsonLine(filePath, object) {
+  const line = JSON.stringify(object) + '\n'
+  await fs.appendFile(filePath, line, 'utf-8')
+}
+
+/**
+ * Append multiple objects to JSONL file
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @param {Array<Object>} objects - Objects to append
+ * @returns {Promise<void>}
+ */
+async function appendJsonLines(filePath, objects) {
+  const content = stringifyJsonLines(objects)
+  await fs.appendFile(filePath, content, 'utf-8')
+}
+
+/**
+ * Filter JSONL file entries by predicate
+ * Reads all entries, filters, returns matching ones
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @param {Function} predicate - Filter function (entry => boolean)
+ * @returns {Promise<Array<Object>>} - Filtered entries
+ */
+async function filterJsonLines(filePath, predicate) {
+  const entries = await readJsonLines(filePath)
+  return entries.filter(predicate)
+}
+
+/**
+ * Count lines in JSONL file (non-empty, parseable lines)
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @returns {Promise<number>} - Number of valid lines
+ */
+async function countJsonLines(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    const lines = content.split('\n').filter((line) => line.trim())
+    return lines.length
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return 0
+    }
+    throw error
+  }
+}
+
+/**
+ * Get last N entries from JSONL file
+ * Efficient for large files (reads whole file but only returns last N)
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @param {number} n - Number of entries to return
+ * @returns {Promise<Array<Object>>} - Last N entries
+ */
+async function getLastJsonLines(filePath, n) {
+  const entries = await readJsonLines(filePath)
+  return entries.slice(-n)
+}
+
+/**
+ * Get first N entries from JSONL file
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @param {number} n - Number of entries to return
+ * @returns {Promise<Array<Object>>} - First N entries
+ */
+async function getFirstJsonLines(filePath, n) {
+  const entries = await readJsonLines(filePath)
+  return entries.slice(0, n)
+}
+
+/**
+ * Merge multiple JSONL files into one array
+ * Useful for reading multiple sessions
+ *
+ * @param {Array<string>} filePaths - Array of JSONL file paths
+ * @returns {Promise<Array<Object>>} - Merged entries from all files
+ */
+async function mergeJsonLines(filePaths) {
+  const allEntries = []
+
+  for (const filePath of filePaths) {
+    const entries = await readJsonLines(filePath)
+    allEntries.push(...entries)
+  }
+
+  return allEntries
+}
+
+/**
+ * Check if JSONL file is empty or doesn't exist
+ *
+ * @param {string} filePath - Path to JSONL file
+ * @returns {Promise<boolean>} - True if empty or non-existent
+ */
+async function isJsonLinesEmpty(filePath) {
+  const count = await countJsonLines(filePath)
+  return count === 0
+}
+
+module.exports = {
+  parseJsonLines,
+  stringifyJsonLines,
+  readJsonLines,
+  writeJsonLines,
+  appendJsonLine,
+  appendJsonLines,
+  filterJsonLines,
+  countJsonLines,
+  getLastJsonLines,
+  getFirstJsonLines,
+  mergeJsonLines,
+  isJsonLinesEmpty,
+}

package/core/{project-capabilities.js → utils/project-capabilities.js}

@@ -25,12 +25,12 @@ class ProjectCapabilities {
    */
   async hasDesign(projectPath) {
     return (
-      await this.hasFolder(projectPath, 'design') ||
-      await this.hasFolder(projectPath, 'designs') ||
-      await this.hasFolder(projectPath, '.storybook') ||
-      await this.hasDep(projectPath, '@storybook/react') ||
-      await this.hasDep(projectPath, '@storybook/vue') ||
-      await this.hasFiles(projectPath, '**/*.figma')
+      (await this.hasFolder(projectPath, 'design')) ||
+      (await this.hasFolder(projectPath, 'designs')) ||
+      (await this.hasFolder(projectPath, '.storybook')) ||
+      (await this.hasDep(projectPath, '@storybook/react')) ||
+      (await this.hasDep(projectPath, '@storybook/vue')) ||
+      (await this.hasFiles(projectPath, '**/*.figma'))
     )
   }
 
@@ -39,13 +39,13 @@ class ProjectCapabilities {
    */
   async hasTest(projectPath) {
     return (
-      await this.hasDep(projectPath, 'jest') ||
-      await this.hasDep(projectPath, 'vitest') ||
-      await this.hasDep(projectPath, 'mocha') ||
-      await this.hasDep(projectPath, '@jest/core') ||
-      await this.hasFiles(projectPath, '**/*.{test,spec}.{js,ts,jsx,tsx}') ||
-      await this.hasFile(projectPath, 'jest.config.js') ||
-      await this.hasFile(projectPath, 'vitest.config.js')
+      (await this.hasDep(projectPath, 'jest')) ||
+      (await this.hasDep(projectPath, 'vitest')) ||
+      (await this.hasDep(projectPath, 'mocha')) ||
+      (await this.hasDep(projectPath, '@jest/core')) ||
+      (await this.hasFiles(projectPath, '**/*.{test,spec}.{js,ts,jsx,tsx}')) ||
+      (await this.hasFile(projectPath, 'jest.config.js')) ||
+      (await this.hasFile(projectPath, 'vitest.config.js'))
     )
   }
 
@@ -54,11 +54,11 @@ class ProjectCapabilities {
    */
   async hasDocs(projectPath) {
     return (
-      await this.hasFolder(projectPath, 'docs') ||
-      await this.hasFolder(projectPath, 'documentation') ||
-      await this.hasFile(projectPath, 'README.md') ||
-      await this.hasDep(projectPath, 'typedoc') ||
-      await this.hasDep(projectPath, 'jsdoc')
+      (await this.hasFolder(projectPath, 'docs')) ||
+      (await this.hasFolder(projectPath, 'documentation')) ||
+      (await this.hasFile(projectPath, 'README.md')) ||
+      (await this.hasDep(projectPath, 'typedoc')) ||
+      (await this.hasDep(projectPath, 'jsdoc'))
     )
   }
 
@@ -98,10 +98,9 @@ class ProjectCapabilities {
       const files = await fs.readdir(projectPath, { recursive: true })
 
       // Filter by pattern and ignore node_modules, dist, build
-      return files.some(file => {
-        const skip = file.includes('node_modules/') ||
-                    file.includes('dist/') ||
-                    file.includes('build/')
+      return files.some((file) => {
+        const skip =
+          file.includes('node_modules/') || file.includes('dist/') || file.includes('build/')
         return !skip && regex.test(file)
       })
     } catch {