prjct-cli 0.5.1 → 0.7.0

package/core/utils/session-helper.js

@@ -0,0 +1,277 @@
+const path = require('path')
+const dateHelper = require('./date-helper')
+const jsonlHelper = require('./jsonl-helper')
+const fileHelper = require('./file-helper')
+
+/**
+ * Session Helper - High-level session operations
+ *
+ * Simplifies common session workflows by combining:
+ * - date-helper (date formatting)
+ * - jsonl-helper (JSONL parsing)
+ * - file-helper (file operations)
+ * - path-manager (path construction)
+ *
+ * @module session-helper
+ */
+
+/**
+ * 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) {
+  const today = dateHelper.getTodayKey()
+  const yearMonth = dateHelper.formatMonth(new Date())
+  const [year, month] = yearMonth.split('-')
+
+  const sessionDir = path.join(projectGlobalPath, layer, 'sessions', year, month)
+
+  if (filename) {
+    return path.join(sessionDir, filename)
+  }
+
+  return path.join(sessionDir, `${today}.jsonl`)
+}
+
+/**
+ * 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) {
+  const yearMonth = dateHelper.formatMonth(new Date())
+  const [year, month] = yearMonth.split('-')
+
+  const sessionDir = path.join(projectGlobalPath, layer, 'sessions', year, month)
+  await fileHelper.ensureDir(sessionDir)
+
+  return sessionDir
+}
+
+/**
+ * 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) {
+  await ensureTodaySessionDir(projectGlobalPath, layer)
+
+  const filePath = getTodaySessionFilePath(projectGlobalPath, layer, filename)
+
+  // Add timestamp if not present
+  if (!entry.ts && !entry.timestamp) {
+    entry.ts = dateHelper.getTimestamp()
+  }
+
+  await jsonlHelper.appendJsonLine(filePath, entry)
+}
+
+/**
+ * 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) {
+  const filePath = getTodaySessionFilePath(projectGlobalPath, layer, filename)
+  return await jsonlHelper.readJsonLines(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) {
+  const fromDate = dateHelper.getDaysAgo(daysBack)
+  const toDate = new Date()
+
+  const dates = dateHelper.getDateRange(fromDate, toDate)
+  const allEntries = []
+
+  for (const date of dates) {
+    const yearMonth = dateHelper.formatMonth(date)
+    const dateKey = dateHelper.getDateKey(date)
+    const [year, month] = yearMonth.split('-')
+
+    const filePath = path.join(
+      projectGlobalPath,
+      layer,
+      'sessions',
+      year,
+      month,
+      `${dateKey}.jsonl`
+    )
+
+    const entries = await jsonlHelper.readJsonLines(filePath)
+    allEntries.push(...entries)
+  }
+
+  return allEntries
+}
+
+/**
+ * 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)
+
+  // Group by type
+  const byType = {}
+  for (const entry of entries) {
+    const type = entry.type || 'unknown'
+    byType[type] = (byType[type] || 0) + 1
+  }
+
+  // Group by date
+  const byDate = {}
+  for (const entry of entries) {
+    const timestamp = entry.ts || entry.timestamp
+    if (timestamp) {
+      const date = dateHelper.getDateKey(new Date(timestamp))
+      byDate[date] = (byDate[date] || 0) + 1
+    }
+  }
+
+  return {
+    totalEntries: entries.length,
+    byType,
+    byDate,
+    activeDays: Object.keys(byDate).length,
+    averagePerDay: entries.length / Math.max(daysBack, 1),
+  }
+}
+
+/**
+ * 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) {
+  const cutoffDate = dateHelper.getDaysAgo(daysToKeep)
+  const archiveDir = path.join(projectGlobalPath, layer, 'archive')
+  await fileHelper.ensureDir(archiveDir)
+
+  const sessionsDir = path.join(projectGlobalPath, layer, 'sessions')
+
+  // Find all session files older than cutoff
+  const archived = []
+  const errors = []
+
+  try {
+    const years = await fileHelper.listFiles(sessionsDir, { dirsOnly: true })
+
+    for (const year of years) {
+      const yearPath = path.join(sessionsDir, year)
+      const months = await fileHelper.listFiles(yearPath, { dirsOnly: true })
+
+      for (const month of months) {
+        const monthPath = path.join(yearPath, month)
+        const sessionFiles = await fileHelper.listFiles(monthPath, { filesOnly: true })
+
+        for (const filename of sessionFiles) {
+          // Parse date from filename (YYYY-MM-DD.jsonl)
+          const dateMatch = filename.match(/(\d{4}-\d{2}-\d{2})/)
+          if (!dateMatch) continue
+
+          const sessionDate = new Date(dateMatch[1])
+          if (sessionDate < cutoffDate) {
+            const sourcePath = path.join(monthPath, filename)
+            const destPath = path.join(archiveDir, filename)
+
+            try {
+              await fileHelper.moveFile(sourcePath, destPath)
+              archived.push(filename)
+            } catch (error) {
+              errors.push({ filename, error: error.message })
+            }
+          }
+        }
+      }
+    }
+  } catch (error) {
+    // Sessions directory might not exist yet
+  }
+
+  return {
+    archived: archived.length,
+    files: archived,
+    errors,
+  }
+}
+
+/**
+ * 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) {
+  const sessionsDir = path.join(projectGlobalPath, layer, 'sessions')
+  let cleaned = 0
+
+  try {
+    const years = await fileHelper.listFiles(sessionsDir, { dirsOnly: true })
+
+    for (const year of years) {
+      const yearPath = path.join(sessionsDir, year)
+      const months = await fileHelper.listFiles(yearPath, { dirsOnly: true })
+
+      for (const month of months) {
+        const monthPath = path.join(yearPath, month)
+        const files = await fileHelper.listFiles(monthPath)
+
+        if (files.length === 0) {
+          await fileHelper.deleteDir(monthPath)
+          cleaned++
+        }
+      }
+
+      // Check if year directory is now empty
+      const remainingMonths = await fileHelper.listFiles(yearPath, { dirsOnly: true })
+      if (remainingMonths.length === 0) {
+        await fileHelper.deleteDir(yearPath)
+        cleaned++
+      }
+    }
+  } catch (error) {
+    // Sessions directory might not exist
+  }
+
+  return cleaned
+}
+
+module.exports = {
+  getTodaySessionFilePath,
+  ensureTodaySessionDir,
+  writeToSession,
+  readTodaySession,
+  readRecentSessions,
+  getSessionStats,
+  archiveOldSessions,
+  cleanEmptySessionDirs,
+}

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

@@ -24,7 +24,7 @@ function getVersion() {
   }
 
   try {
-    const packageJsonPath = path.join(__dirname, '..', 'package.json')
+    const packageJsonPath = path.join(__dirname, '..', '..', 'package.json')
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
     cachedVersion = packageJson.version
     cachedPackageJson = packageJson

package/package.json

@@ -1,20 +1,19 @@
 {
   "name": "prjct-cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Built for Claude - Ship fast, track progress, stay focused. Developer momentum tool for indie hackers.",
   "main": "core/index.js",
   "bin": {
-    "prjct": "./bin/prjct"
+    "prjct": "bin/prjct"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "postinstall": "node scripts/post-install.js",
-    "preuninstall": "node scripts/preuninstall.js",
     "install-global": "./scripts/install.sh",
     "test": "echo 'No tests configured'",
+    "validate": "node scripts/validate-commands.js",
     "lint": "eslint \"**/*.js\" --ignore-pattern \"node_modules/**\" --ignore-pattern \"website/**\"",
     "lint:fix": "eslint \"**/*.js\" --fix --ignore-pattern \"node_modules/**\" --ignore-pattern \"website/**\"",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\" --config .config/.prettierrc --ignore-path .config/.prettierignore",
@@ -40,13 +39,12 @@
   "license": "MIT",
   "dependencies": {
     "chalk": "^4.1.2",
-    "commander": "^11.0.0",
-    "ora": "^5.4.1",
     "prompts": "^2.4.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-config-standard": "^17.1.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^16.6.2",
@@ -57,7 +55,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jlopezlira/prjct-cli"
+    "url": "git+https://github.com/jlopezlira/prjct-cli.git"
   },
   "bugs": {
     "url": "https://github.com/jlopezlira/prjct-cli/issues"
@@ -71,9 +69,6 @@
     "core/",
     "templates/",
     "scripts/install.sh",
-    "scripts/verify-installation.sh",
-    "scripts/post-install.js",
-    "scripts/preuninstall.js",
     "LICENSE",
     "README.md",
     "CHANGELOG.md",
@@ -81,8 +76,6 @@
   ],
   "trustedDependencies": [
     "chalk",
-    "commander",
-    "ora",
     "prompts"
   ]
 }

package/templates/agents/AGENTS.md

@@ -1,37 +1,112 @@
 # AGENTS.md
 
-AI assistant guidance for prjct-cli.
+AI assistant guidance for **prjct-cli** - developer momentum tool for solo builders & small teams (2-5 people). Just ship. No BS.
+
+## What This Is
+
+**NOT** project management. NO sprints, story points, ceremonies, or meetings.
+
+**IS** frictionless progress tracking. Talk naturally, ship features, celebrate wins.
+
+---
+
+## Dynamic Agent Generation
+
+**YOU decide** what specialists to generate based on project analysis. No predetermined lists.
+
+### When to Generate Agents
+
+From commands that analyze the project:
+
+- `/p:sync` - Sync and generate agents
+- `/p:init` - Initialize with existing code
+- `/p:architect` - After generating project plan
+
+### How to Generate
+
+```javascript
+const generator = new AgentGenerator(projectId)
+
+await generator.generateDynamicAgent('agent-name', {
+  role: 'Clear Role Description',
+  expertise: 'Specific technologies, versions, tools',
+  responsibilities: 'What they handle in this project',
+  projectContext: {
+    /* optional context */
+  },
+})
+```
+
+### Example Usage
+
+**1. Read the analysis first:**
+
+```javascript
+// Read analysis/repo-summary.md to understand the stack
+const analysis = await readAnalysis('analysis/repo-summary.md')
+```
+
+**2. Generate specialists for technologies YOU find:**
+
+```javascript
+// For EACH major technology found in the analysis, create a specialist
+// Use descriptive names and specific details from the analysis
+
+await generator.generateDynamicAgent('descriptive-name', {
+  role: 'Clear role based on what you found',
+  expertise: 'Specific versions, frameworks, tools from analysis',
+  responsibilities: 'What this agent handles in THIS specific project',
+  projectContext: {
+    /* any relevant context from analysis */
+  },
+})
+```
+
+**You decide everything** - read the analysis, understand the stack, generate appropriate specialists. No predetermined lists, no assumptions, no limitations.
+
+### Guidelines
+
+1. **Read analysis** - Understand full stack from analysis/repo-summary.md
+2. **Create specialists** - For each major technology found
+3. **Name descriptively** - `go-backend` not `be`, `vuejs-frontend` not `fe`
+4. **Be specific** - Include versions, frameworks, tools
+5. **No predetermined list** - ANY stack works (Elixir, Phoenix, Svelte, etc.)
+6. **Follow project plan** - Only generate agents for technologies found in project plan and related to your role
+7. **Best practices** - Allways use best practices for your role
+
+---
 
 ## Talk Naturally
 
-**You don't need to memorize commands** - just describe what you want to do!
+**Zero memorization** - just describe what you want!
 
-The AI assistant uses **semantic understanding** to map your intent to commands. Works in **any language** the LLM understands (primarily English and Spanish).
+Works in **any language** via semantic understanding.
 
 **Examples:**
+
 ```
-Intent: Start working on something
+Start working:
 → "I want to build the login page"
-→ "Let me work on authentication"
-→ "Voy a hacer el dashboard"
 → Command: /p:now
 
-Intent: Finished current work
-→ "I'm done" | "finished" | "terminé" | "completed"
+Finished:
+→ "I'm done" | "completed"
 → Command: /p:done
 
-Intent: Ship a feature
+Ship:
 → "ship this" | "deploy it" | "ready to launch"
 → Command: /p:ship
 ```
 
-**Both work simultaneously:**
-- Talk naturally: "I want to start building auth"
-- Use commands directly: `/p:now "building auth"`
+**Both work:**
+
+- Natural: "I want to start building auth"
+- Direct: `/p:now "building auth"`
 
 ## Architecture
 
 **Global**: `~/.prjct-cli/projects/{id}/`
+
 ```
 core/        # now.md, next.md, context.md
 progress/    # shipped.md, metrics.md
@@ -42,123 +117,100 @@ memory/      # context.jsonl
 
 **Local**: `.prjct/prjct.config.json`
 
-## MCP Servers
-
-- **Context7**: Library docs (always on)
-- **Filesystem**: File ops
-- **Memory**: Persistence
-- **Sequential**: Complex reasoning
-
 ## Quick Start
 
-1. Initialize: `/p:init`
-2. Type: `/p:help` for interactive guide
-3. Or just talk: "I want to start [task]"
+1. `/p:init` - Initialize
+2. `/p:help` - Guide
+3. Or talk: "I want to start [task]"
 
 ## Commands
 
-**💡 Tip**: Type `/p:help` anytime for an interactive guide with natural language options.
-
-| Command | Say This Instead | Action |
-|---------|------------------|--------|
-| `/p:help` | "help" or "what can I do?" | Interactive guide |
-| `/p:init` | - | Create global dirs + config |
-| `/p:now [task]` | "start [task]" | Update `core/now.md` |
-| `/p:done` | "I'm done" or "finished" | Clear focus, suggest next |
-| `/p:ship <feature>` | "ship [feature]" | Add to `progress/shipped.md` |
-| `/p:next` | "what's next?" | Read `core/next.md` |
-| `/p:idea <text>` | "I have an idea about [x]" | Append to `planning/ideas.md` |
-| `/p:recap` | "show my progress" | Aggregate all metrics |
-| `/p:progress [period]` | "how am I doing?" | Filter by timeframe |
-| `/p:stuck <issue>` | "I'm stuck on [issue]" | Context-based guidance |
-| `/p:context` | "show project context" | Display config + activity |
-| `/p:roadmap` | "show the plan" | Read `planning/roadmap.md` |
-| `/p:analyze` | "analyze this repo" | Generate `analysis/repo-summary.md` |
-| `/p:task` | "break this down" | Multi-step execution |
-| `/p:git` | - | Smart commits with context |
-| `/p:fix` | "help me fix [x]" | Quick problem solving |
-| `/p:test` | "run tests" | Execute + report |
-| `/p:design` | "design [x]" | Generate diagrams + specs |
-| `/p:cleanup` | "clean up code" | Remove dead code/deps |
+**💡 Tip**: `/p:help` for interactive guide
+
+| Command                | Say This          | Action            |
+| ---------------------- | ----------------- | ----------------- |
+| `/p:help`              | "help"            | Interactive guide |
+| `/p:init`              | -                 | Create structure  |
+| `/p:now [task]`        | "start [task]"    | Set current task  |
+| `/p:done`              | "I'm done"        | Complete & next   |
+| `/p:ship <feature>`    | "ship [feature]"  | Celebrate win     |
+| `/p:next`              | "what's next?"    | Show queue        |
+| `/p:idea <text>`       | "idea about [x]"  | Capture ideas     |
+| `/p:recap`             | "show progress"   | Overview          |
+| `/p:progress [period]` | "how am I doing?" | Metrics           |
+| `/p:stuck <issue>`     | "I'm stuck"       | Get help          |
+| `/p:context`           | "show context"    | Display state     |
+| `/p:analyze`           | "analyze repo"    | Generate summary  |
+| `/p:design`            | "design [x]"      | Generate specs    |
+| `/p:cleanup`           | "clean up"        | Remove dead code  |
 
 ## How It Works
 
-**You can talk naturally:**
-- System detects intent from your message
-- Maps to appropriate command automatically
-- Responds conversationally with options
-- Always suggests what to do next
+**Natural conversation:**
 
-**Every response includes:**
-- What you just did
-- Natural language options for next steps
-- Command alternatives if you prefer
+- Detect intent
+- Map to command
+- Respond with options
+- Suggest next steps
 
-**Zero memorization needed** - just describe what you want!
+**Every response:**
 
-## Natural Language Detection
+- What you did
+- Natural options
+- Command alternatives
 
-The AI assistant uses **semantic understanding** to map user intent to commands.
+**Zero memorization!**
 
-### How It Works
+## Intent Detection
 
-**You're an LLM** - use your natural language understanding, not pattern matching!
+Semantic understanding, not pattern matching.
 
-1. **Check if direct command**: Does message start with `/p:`? → Execute directly
-2. **Understand user intent**: What is the user trying to accomplish?
-3. **Map to appropriate command**: Based on semantic meaning
-4. **Extract parameters**: Pull relevant information from the message
-5. **Show transparency**: Always say what you understood and what you'll execute
+| Intent     | Command    | Examples                                     |
+| ---------- | ---------- | -------------------------------------------- |
+| Start task | `/p:now`   | "work on X", "starting API", "voy a hacer X" |
+| Finish     | `/p:done`  | "done", "finished", "terminé", "listo"       |
+| Ship       | `/p:ship`  | "ship this", "deploy X", "it's ready"        |
+| Idea       | `/p:idea`  | "I have an idea", "what if we..."            |
+| Progress   | `/p:recap` | "show progress", "how am I doing"            |
+| Stuck      | `/p:stuck` | "I'm stuck", "help with X"                   |
+| Next       | `/p:next`  | "what's next", "qué sigue"                   |
 
-### Command Intent Map
+**Any language works** - if you understand intent, execute the command.
 
-| User Intent | Command | Examples of Natural Expression |
-|-------------|---------|-------------------------------|
-| Start/focus on task | `/p:now` | "let me work on X", "starting the API", "voy a hacer X" |
-| Finished current work | `/p:done` | "done", "finished", "terminé", "completed", "listo" |
-| Ship/deploy feature | `/p:ship` | "ship this", "deploy X", "it's ready", "let's launch" |
-| Capture an idea | `/p:idea` | "I have an idea", "what if we...", "tengo una idea" |
-| Check progress/status | `/p:recap` | "show progress", "how am I doing", "muéstrame el avance" |
-| Stuck on problem | `/p:stuck` | "I'm stuck", "help with X", "estoy atascado" |
-| What to work on next | `/p:next` | "what's next", "qué sigue", "what should I do" |
+### Example
 
-**Key principle**: If you understand what the user wants, map it to the right command. Don't rely on exact phrase matching.
+**User:** "I want to start building the login page"
 
-### Example Flow
+**Your reasoning:**
 
-**User:** "I want to start building the login page"
+- Intent: Start working
+- Command: `/p:now`
+- Param: "building the login page"
 
-**Your Reasoning:**
-- Intent detected: User wants to begin working on something
-- Appropriate command: `/p:now`
-- Parameter to extract: "building the login page"
+**Response:**
 
-**Your Response:**
 ```
-💬 I understood: "start working on building the login page"
+💬 Understood: "start building the login page"
 ⚡ Executing: /p:now "building the login page"
 
-✅ Starting task: building the login page
+✅ Starting: building the login page
 
-What's next?
+Next:
 • Say "I'm done" when finished
 • Or: /p:done
 ```
 
-### Works in Any Language
-
-If you understand the user's intent in **any language**, execute the command:
-- English: "I want to start the API"
-- Spanish: "Quiero empezar con la autenticación"
-- Casual: "gonna work on that login thing"
-- Formal: "I shall commence development of the authentication module"
-
-All map to: `/p:now`
-
 ## Implementation
 
 - All ops atomic
-- Log to `memory/context.jsonl` with author
-- Conversational responses with clear options
-- Intent detection (English + Spanish)
-- Handle missing files gracefully
+- Log to `memory/context.jsonl`
+- Conversational responses
+- Intent detection (any language)
+- Handle missing files
+
+## MCP Servers
+
+- **Context7**: Library docs (always on)
+- **Filesystem**: File ops
+- **Memory**: Persistence
+- **Sequential**: Complex reasoning