prjct-cli 1.6.13 → 1.7.0

package/CHANGELOG.md

@@ -1,12 +1,37 @@
 # Changelog
 
-## [1.6.13] - 2026-02-07
+## [1.7.0] - 2026-02-07
 
-### Refactoring
+### Features
+
+- use relative timestamps to reduce token waste (PRJ-274) (#139)
+- use relative timestamps to reduce token waste (PRJ-274)
+
+
+## [1.6.16] - 2026-02-07
+
+### Improvement
+- **Use relative timestamps to reduce token waste (PRJ-274)**: Added `toRelative()` function using `date-fns` `formatDistanceToNowStrict`. Replaced raw ISO-8601 timestamps in Markdown context files (`now.md`, `ideas.md`, `shipped.md`) with human-readable relative time ("5 minutes ago", "3 days ago"). JSON storage retains full ISO timestamps — no data loss.
+
+### Implementation Details
+Added `date-fns` as a dependency and created a thin `toRelative(date)` wrapper around `formatDistanceToNowStrict` in `core/utils/date-helper.ts`. Updated `toMarkdown()` in `state-storage.ts` (Started/Paused fields), `ideas-storage.ts` (all 3 sections: pending, converted, archived), and `shipped-storage.ts` (ship date per entry). 6 new unit tests added covering minutes, hours, days, months, Date objects, and ISO string inputs.
+
+### Learnings
+- `date-fns` `formatDistanceToNowStrict` gives exact units ("5 minutes ago" not "about 5 minutes ago") — better for token efficiency
+- Tests need `setSystemTime()` from `bun:test` since `formatDistanceToNowStrict` uses system clock internally
+
+### Test Plan
 
-- remove unused templates and dead code (PRJ-293) (#138)
-- remove unused templates and dead code (PRJ-293)
+#### For QA
+1. Run `bun test core/__tests__/utils/date-helper.test.ts` — verify all 55 tests pass (6 new for `toRelative`)
+2. Run `bun run build` — verify build succeeds
+3. Run `prjct sync` — verify `context/now.md` shows relative timestamps instead of raw ISO
+4. Check `ideas.md` and `shipped.md` for relative date format
 
+#### For Users
+**What changed:** Timestamps in context files now show "5 minutes ago", "3 days ago" instead of raw ISO-8601 strings.
+**How to use:** No action needed — automatic.
+**Breaking changes:** None.
 
 ## [1.6.15] - 2026-02-07
 

package/core/__tests__/utils/date-helper.test.ts

@@ -21,6 +21,7 @@ import {
   isToday,
   isWithinLastDays,
   parseDate,
+  toRelative,
 } from '../../utils/date-helper'
 
 describe('DateHelper', () => {
@@ -402,4 +403,47 @@ describe('DateHelper', () => {
       expect(original.getMinutes()).toBe(30)
     })
   })
+
+  describe('toRelative', () => {
+    it('should show minutes for dates within 1 hour', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const fiveMinAgo = '2025-10-15T11:55:00.000Z'
+      expect(toRelative(fiveMinAgo)).toBe('5 minutes ago')
+      setSystemTime()
+    })
+
+    it('should show hours for dates within 24 hours', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const threeHoursAgo = '2025-10-15T09:00:00.000Z'
+      expect(toRelative(threeHoursAgo)).toBe('3 hours ago')
+      setSystemTime()
+    })
+
+    it('should show days for dates within 7 days', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const twoDaysAgo = '2025-10-13T12:00:00.000Z'
+      expect(toRelative(twoDaysAgo)).toBe('2 days ago')
+      setSystemTime()
+    })
+
+    it('should show months for dates older than 30 days', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const twoMonthsAgo = '2025-08-15T12:00:00.000Z'
+      expect(toRelative(twoMonthsAgo)).toBe('2 months ago')
+      setSystemTime()
+    })
+
+    it('should accept Date objects', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      const date = new Date('2025-10-15T11:00:00.000Z')
+      expect(toRelative(date)).toBe('1 hour ago')
+      setSystemTime()
+    })
+
+    it('should accept ISO string timestamps', () => {
+      setSystemTime(new Date('2025-10-15T12:00:00.000Z'))
+      expect(toRelative('2025-10-14T12:00:00.000Z')).toBe('1 day ago')
+      setSystemTime()
+    })
+  })
 })

package/core/storage/ideas-storage.ts

@@ -7,7 +7,7 @@
 
 import { generateUUID } from '../schemas'
 import type { Idea, IdeaPriority, IdeaStatus, IdeasJson } from '../types'
-import { getTimestamp } from '../utils/date-helper'
+import { getTimestamp, toRelative } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class IdeasStorage extends StorageManager<IdeasJson> {
@@ -45,10 +45,10 @@ class IdeasStorage extends StorageManager<IdeasJson> {
     lines.push('## Brain Dump')
     if (pending.length > 0) {
       pending.forEach((idea) => {
-        const date = idea.addedAt.split('T')[0]
+        const rel = toRelative(idea.addedAt)
         const tags = idea.tags.length > 0 ? ` ${idea.tags.map((t) => `#${t}`).join(' ')}` : ''
         const priority = idea.priority !== 'medium' ? ` [${idea.priority.toUpperCase()}]` : ''
-        lines.push(`- ${idea.text}${priority} _(${date})_${tags}`)
+        lines.push(`- ${idea.text}${priority} _(${rel})_${tags}`)
       })
     } else {
       lines.push('_No pending ideas_')
@@ -59,9 +59,9 @@ class IdeasStorage extends StorageManager<IdeasJson> {
     if (converted.length > 0) {
       lines.push('## Converted')
       converted.forEach((idea) => {
-        const date = idea.addedAt.split('T')[0]
+        const rel = toRelative(idea.addedAt)
         const feat = idea.convertedTo ? ` \u2192 ${idea.convertedTo}` : ''
-        lines.push(`- \u2713 ${idea.text}${feat} _(${date})_`)
+        lines.push(`- \u2713 ${idea.text}${feat} _(${rel})_`)
       })
       lines.push('')
     }
@@ -70,8 +70,8 @@ class IdeasStorage extends StorageManager<IdeasJson> {
     if (archived.length > 0) {
       lines.push('## Archived')
       archived.forEach((idea) => {
-        const date = idea.addedAt.split('T')[0]
-        lines.push(`- ${idea.text} _(${date})_`)
+        const rel = toRelative(idea.addedAt)
+        lines.push(`- ${idea.text} _(${rel})_`)
       })
       lines.push('')
     }

package/core/storage/shipped-storage.ts

@@ -7,7 +7,7 @@
 
 import { generateUUID } from '../schemas'
 import type { ShippedFeature, ShippedJson } from '../types'
-import { getTimestamp } from '../utils/date-helper'
+import { getTimestamp, toRelative } from '../utils/date-helper'
 import { StorageManager } from './storage-manager'
 
 class ShippedStorage extends StorageManager<ShippedJson> {
@@ -72,13 +72,10 @@ class ShippedStorage extends StorageManager<ShippedJson> {
         .sort((a, b) => new Date(b.shippedAt).getTime() - new Date(a.shippedAt).getTime())
 
       ships.forEach((ship) => {
-        const date = new Date(ship.shippedAt).toLocaleDateString('en-US', {
-          month: 'short',
-          day: 'numeric',
-        })
+        const rel = toRelative(ship.shippedAt)
         const version = ship.version ? ` v${ship.version}` : ''
         const duration = ship.duration ? ` (${ship.duration})` : ''
-        lines.push(`- **${ship.name}**${version}${duration} - ${date}`)
+        lines.push(`- **${ship.name}**${version}${duration} - ${rel}`)
         if (ship.description) {
           lines.push(`  _${ship.description}_`)
         }

package/core/storage/state-storage.ts

@@ -16,7 +16,7 @@ import type {
   Subtask,
   SubtaskSummary,
 } from '../schemas/state'
-import { getTimestamp } from '../utils/date-helper'
+import { getTimestamp, toRelative } from '../utils/date-helper'
 import { md } from '../utils/markdown-builder'
 import { StorageManager } from './storage-manager'
 
@@ -52,7 +52,7 @@ class StateStorage extends StorageManager<StateJson> {
         const task = data.currentTask!
         m.bold(task.description)
           .blank()
-          .raw(`Started: ${task.startedAt}`)
+          .raw(`Started: ${toRelative(task.startedAt)}`)
           .raw(`Session: ${task.sessionId}`)
           .maybe(task.featureId, (m, id) => m.raw(`Feature: ${id}`))
 
@@ -122,7 +122,7 @@ class StateStorage extends StorageManager<StateJson> {
         m.hr()
           .h2('Paused')
           .bold(prev.description)
-          .raw(`Paused: ${prev.pausedAt}`)
+          .raw(`Paused: ${toRelative(prev.pausedAt)}`)
           .maybe(prev.pauseReason, (m, reason) => m.raw(`Reason: ${reason}`))
           .blank()
           .italic('Use /p:resume to continue')

package/core/utils/date-helper.ts

@@ -7,6 +7,7 @@
  * - commands.ts (38+ inline date operations)
  */
 
+import { formatDistanceToNowStrict } from 'date-fns'
 import type { DateComponents } from '../types'
 
 /**
@@ -164,3 +165,12 @@ export function getEndOfDay(date: Date): Date {
   result.setHours(23, 59, 59, 999)
   return result
 }
+
+/**
+ * Convert a date/timestamp to a relative string (e.g. "5 minutes ago").
+ * Uses date-fns formatDistanceToNowStrict for accurate, token-friendly output.
+ */
+export function toRelative(date: string | Date): string {
+  const d = typeof date === 'string' ? new Date(date) : date
+  return formatDistanceToNowStrict(d, { addSuffix: true })
+}

package/dist/bin/prjct.mjs

@@ -667,8 +667,10 @@ __export(date_helper_exports, {
   getYearMonthDay: () => getYearMonthDay,
   isToday: () => isToday,
   isWithinLastDays: () => isWithinLastDays,
-  parseDate: () => parseDate
+  parseDate: () => parseDate,
+  toRelative: () => toRelative
 });
+import { formatDistanceToNowStrict } from "date-fns";
 function formatDate(date) {
   const year = date.getFullYear();
   const month = (date.getMonth() + 1).toString().padStart(2, "0");
@@ -755,6 +757,10 @@ function getEndOfDay(date) {
   result.setHours(23, 59, 59, 999);
   return result;
 }
+function toRelative(date) {
+  const d = typeof date === "string" ? new Date(date) : date;
+  return formatDistanceToNowStrict(d, { addSuffix: true });
+}
 var init_date_helper = __esm({
   "core/utils/date-helper.ts"() {
     "use strict";
@@ -774,6 +780,7 @@ var init_date_helper = __esm({
     __name(calculateDuration, "calculateDuration");
     __name(getStartOfDay, "getStartOfDay");
     __name(getEndOfDay, "getEndOfDay");
+    __name(toRelative, "toRelative");
   }
 });
 
@@ -10716,10 +10723,10 @@ var init_ideas_storage = __esm({
         lines.push("## Brain Dump");
         if (pending.length > 0) {
           pending.forEach((idea) => {
-            const date = idea.addedAt.split("T")[0];
+            const rel = toRelative(idea.addedAt);
             const tags = idea.tags.length > 0 ? ` ${idea.tags.map((t) => `#${t}`).join(" ")}` : "";
             const priority = idea.priority !== "medium" ? ` [${idea.priority.toUpperCase()}]` : "";
-            lines.push(`- ${idea.text}${priority} _(${date})_${tags}`);
+            lines.push(`- ${idea.text}${priority} _(${rel})_${tags}`);
           });
         } else {
           lines.push("_No pending ideas_");
@@ -10728,17 +10735,17 @@ var init_ideas_storage = __esm({
         if (converted.length > 0) {
           lines.push("## Converted");
           converted.forEach((idea) => {
-            const date = idea.addedAt.split("T")[0];
+            const rel = toRelative(idea.addedAt);
             const feat = idea.convertedTo ? ` \u2192 ${idea.convertedTo}` : "";
-            lines.push(`- \u2713 ${idea.text}${feat} _(${date})_`);
+            lines.push(`- \u2713 ${idea.text}${feat} _(${rel})_`);
           });
           lines.push("");
         }
         if (archived.length > 0) {
           lines.push("## Archived");
           archived.forEach((idea) => {
-            const date = idea.addedAt.split("T")[0];
-            lines.push(`- ${idea.text} _(${date})_`);
+            const rel = toRelative(idea.addedAt);
+            lines.push(`- ${idea.text} _(${rel})_`);
           });
           lines.push("");
         }
@@ -11466,13 +11473,10 @@ var init_shipped_storage = __esm({
           lines.push("");
           const ships = byMonth.get(month).sort((a, b) => new Date(b.shippedAt).getTime() - new Date(a.shippedAt).getTime());
           ships.forEach((ship) => {
-            const date = new Date(ship.shippedAt).toLocaleDateString("en-US", {
-              month: "short",
-              day: "numeric"
-            });
+            const rel = toRelative(ship.shippedAt);
             const version = ship.version ? ` v${ship.version}` : "";
             const duration = ship.duration ? ` (${ship.duration})` : "";
-            lines.push(`- **${ship.name}**${version}${duration} - ${date}`);
+            lines.push(`- **${ship.name}**${version}${duration} - ${rel}`);
             if (ship.description) {
               lines.push(`  _${ship.description}_`);
             }
@@ -11848,7 +11852,7 @@ var init_state_storage = __esm({
       toMarkdown(data) {
         return md().h1("NOW").when(!!data.currentTask, (m) => {
           const task = data.currentTask;
-          m.bold(task.description).blank().raw(`Started: ${task.startedAt}`).raw(`Session: ${task.sessionId}`).maybe(task.featureId, (m2, id) => m2.raw(`Feature: ${id}`));
+          m.bold(task.description).blank().raw(`Started: ${toRelative(task.startedAt)}`).raw(`Session: ${task.sessionId}`).maybe(task.featureId, (m2, id) => m2.raw(`Feature: ${id}`));
           if (task.subtasks && task.subtasks.length > 0) {
             m.blank().h2("Subtasks Progress").raw(
               `**Progress**: ${task.subtaskProgress?.completed || 0}/${task.subtaskProgress?.total || 0} (${task.subtaskProgress?.percentage || 0}%)`
@@ -11883,7 +11887,7 @@ var init_state_storage = __esm({
         }).when(!data.currentTask, (m) => {
           m.italic("No active task. Use /p:work to start.");
         }).maybe(data.previousTask, (m, prev) => {
-          m.hr().h2("Paused").bold(prev.description).raw(`Paused: ${prev.pausedAt}`).maybe(prev.pauseReason, (m2, reason2) => m2.raw(`Reason: ${reason2}`)).blank().italic("Use /p:resume to continue");
+          m.hr().h2("Paused").bold(prev.description).raw(`Paused: ${toRelative(prev.pausedAt)}`).maybe(prev.pauseReason, (m2, reason2) => m2.raw(`Reason: ${reason2}`)).blank().italic("Use /p:resume to continue");
         }).blank().build();
       }
       // =========== Domain Methods ===========
@@ -28706,7 +28710,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "1.6.13",
+      version: "1.7.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {
@@ -28761,6 +28765,7 @@ var require_package = __commonJS({
         "@linear/sdk": "^29.0.0",
         chalk: "^4.1.2",
         chokidar: "^5.0.0",
+        "date-fns": "^4.1.0",
         esbuild: "^0.25.0",
         glob: "^13.0.1",
         hono: "^4.11.3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "1.6.13",
+  "version": "1.7.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {
@@ -55,6 +55,7 @@
     "@linear/sdk": "^29.0.0",
     "chalk": "^4.1.2",
     "chokidar": "^5.0.0",
+    "date-fns": "^4.1.0",
     "esbuild": "^0.25.0",
     "glob": "^13.0.1",
     "hono": "^4.11.3",