v2.0.2: fix Things packed-date / Unix-epoch decoding

startDate/deadline are bit-packed calendar dates (not Unix seconds) and
stopDate/creationDate are Unix seconds (not Cocoa). The old code had both
backwards, so today counted recurrence templates via todayIndex>0, due/
overdue/upcoming were silently empty, and completedToday counted all-time
completions. Add decode/encode helpers, redefine Today by scheduled date,
rebuild the fixture with real encodings, and add a regression test.

Author: kaufmanhenry

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 2.0.2
+
+Fix date decoding across every list and stat. The previous releases misread the
+Things SQLite schema, which made several commands return wrong or empty results
+on real databases (tests passed only because the fixture encoded dates the same
+wrong way).
+
+- **`startDate` / `deadline` are bit-packed calendar dates**, not Unix seconds
+  (`2026-06-16` → `132802560`). Added `decodeThingsDate` / `encodeThingsDate` and
+  repointed every read. This fixes scheduled-date display in `show`, `export`,
+  `review`, and the `→`/`📅` markers.
+- **`today` membership is now scheduled-date based.** Previously a task was
+  considered "in Today" when `todayIndex > 0`, but that flag marks recurrence
+  *templates* Things hides — real Today rows carry a negative `todayIndex`. Today
+  now lists Anytime to-dos scheduled for today or earlier (overdue-scheduled roll
+  in), matching the app.
+- **`due` / `overdue` / `upcoming` were silently empty** (they gated deadlines on
+  `> 1000000000`, which packed dates never satisfy). Now corrected.
+- **`someday`** no longer swallows dated tasks; dated items surface under
+  `upcoming` as Things intends.
+- **`stopDate` / `creationDate` / `userModificationDate` are Unix seconds**, not
+  Cocoa. `stats.completedToday` previously counted *all* completed tasks ever;
+  `logbook` and `review` rendered completion dates ~56 years in the future. Both
+  fixed.
+- Rebuilt the test fixture with the real Things encodings and added a
+  recurrence-template regression test so this class of bug can't reappear.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "thingsctl",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "A full-featured command-line interface and MCP server for Things 3 on macOS.",
   "main": "src/cli.js",
   "type": "commonjs",

src/commands/export.js

@@ -4,7 +4,7 @@ const db = require('../lib/db');
 const queries = require('../lib/queries');
 const csv = require('../lib/csv');
 const { taskToJson } = require('../lib/format');
-const { formatShortDate } = require('../lib/dates');
+const { formatThingsShortDate, decodeThingsDate } = require('../lib/dates');
 const { STATUS } = require('../lib/constants');
 
 function _gather(database, source, opts) {
@@ -44,7 +44,7 @@ function _markdown(database, tasks, title) {
     let line = `- ${check} ${t.title}`;
     const tags = t.tagList ? t.tagList.split(',').filter(Boolean) : [];
     if (tags.length) line += ` #${tags.join(' #')}`;
-    const deadline = formatShortDate(t.deadline);
+    const deadline = formatThingsShortDate(t.deadline);
     if (deadline) line += ` 📅 ${deadline}`;
     lines.push(line);
     if (t.notes) {
@@ -64,8 +64,8 @@ function _csv(tasks) {
     const status = t.status === STATUS.COMPLETED ? 'completed'
       : t.status === STATUS.CANCELED ? 'canceled' : 'open';
     const tags = (t.tagList || '').split(',').filter(Boolean).join(';');
-    const deadline = t.deadline >= 1000000000
-      ? new Date(t.deadline * 1000).toISOString().split('T')[0] : '';
+    const dl = decodeThingsDate(t.deadline);
+    const deadline = dl ? dl.toISOString().split('T')[0] : '';
     rows.push([t.uuid, t.title, status, tags, t.projectName || '', t.areaName || '', deadline, t.notes || '']);
   }
   return csv.format(rows);

src/commands/logbook.js

@@ -3,11 +3,11 @@
 const db = require('../lib/db');
 const queries = require('../lib/queries');
 const { colors, taskToJson } = require('../lib/format');
-const { cocoaToDate, daysAgoUnix, unixToCocoa } = require('../lib/dates');
+const { unixToDate, daysAgoUnix } = require('../lib/dates');
 
 function _line(t) {
   let line = `✓ ${t.title}`;
-  const d = cocoaToDate(t.stopDate);
+  const d = unixToDate(t.stopDate);
   if (d) {
     const s = d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
     line += ` ${colors.dim('(' + s + ')')}`;
@@ -16,17 +16,17 @@ function _line(t) {
 }
 
 function run(opts = {}) {
-  let sinceCocoa;
+  let sinceUnix;
   if (opts.since != null) {
     const days = parseInt(opts.since, 10);
-    if (!Number.isNaN(days)) sinceCocoa = unixToCocoa(daysAgoUnix(days));
+    if (!Number.isNaN(days)) sinceUnix = daysAgoUnix(days);
   }
   const limit = opts.limit ? parseInt(opts.limit, 10) : 20;
-  const tasks = queries.logbookTasks(db.open(), { limit, sinceCocoa });
+  const tasks = queries.logbookTasks(db.open(), { limit, sinceUnix });
   if (opts.json) {
     return tasks.map((t) => ({
       ...taskToJson(t),
-      completedAt: cocoaToDate(t.stopDate)?.toISOString() ?? null,
+      completedAt: unixToDate(t.stopDate)?.toISOString() ?? null,
     }));
   }
   if (opts.ids) return tasks.map((t) => t.uuid);

src/commands/review.js

@@ -1,15 +1,19 @@
 'use strict';
 
 const db = require('../lib/db');
-const { todayBounds, daysAgoUnix, unixToCocoa, formatShortDate, cocoaToDate } = require('../lib/dates');
+const { daysAgoUnix, encodeThingsDate, formatThingsShortDate, unixToDate } = require('../lib/dates');
 const { colors } = require('../lib/format');
 
 function _gather(database, days) {
   const now = new Date();
-  const bounds = todayBounds(now);
+  // Timestamps (stopDate, creationDate) are Unix seconds; deadlines are packed
+  // calendar dates, so the two windows use different encodings.
   const sinceUnix = daysAgoUnix(days, now);
-  const sinceCocoa = unixToCocoa(sinceUnix);
-  const untilUnix = bounds.start + days * 86400; // for deadline window: today .. today+N
+  const todayMidnight = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const deadlineFrom = encodeThingsDate(todayMidnight);
+  const until = new Date(todayMidnight);
+  until.setDate(until.getDate() + days);
+  const deadlineTo = encodeThingsDate(until); // deadline window: today .. today+N
 
   const completed = database.prepare(`
     SELECT t.uuid, t.title, t.stopDate, t.area, t.project,
@@ -20,7 +24,7 @@ function _gather(database, days) {
     FROM TMTask t
     WHERE t.status = 3 AND t.trashed = 0 AND t.type = 0 AND t.stopDate >= ?
     ORDER BY t.stopDate DESC
-  `).all(sinceCocoa);
+  `).all(sinceUnix);
 
   const added = database.prepare(`
     SELECT t.uuid, t.title, t.creationDate, t.area, t.project,
@@ -29,7 +33,7 @@ function _gather(database, days) {
     FROM TMTask t
     WHERE t.trashed = 0 AND t.type = 0 AND t.creationDate >= ?
     ORDER BY t.creationDate DESC
-  `).all(sinceCocoa);
+  `).all(sinceUnix);
 
   const deadlines = database.prepare(`
     SELECT t.uuid, t.title, t.deadline,
@@ -39,7 +43,7 @@ function _gather(database, days) {
     WHERE t.status = 0 AND t.trashed = 0 AND t.type = 0
       AND t.deadline >= ? AND t.deadline < ?
     ORDER BY t.deadline ASC
-  `).all(bounds.start, untilUnix);
+  `).all(deadlineFrom, deadlineTo);
 
   return { days, completed, added, deadlines };
 }
@@ -60,9 +64,9 @@ function run(opts = {}) {
   if (opts.json) {
     return {
       windowDays: days,
-      completed: data.completed.map((c) => ({ uuid: c.uuid, title: c.title, completedAt: cocoaToDate(c.stopDate)?.toISOString(), area: c.areaName, project: c.projectName })),
-      added: data.added.map((a) => ({ uuid: a.uuid, title: a.title, createdAt: cocoaToDate(a.creationDate)?.toISOString(), area: a.areaName, project: a.projectName })),
-      deadlines: data.deadlines.map((d) => ({ uuid: d.uuid, title: d.title, deadline: formatShortDate(d.deadline), area: d.areaName, project: d.projectName })),
+      completed: data.completed.map((c) => ({ uuid: c.uuid, title: c.title, completedAt: unixToDate(c.stopDate)?.toISOString(), area: c.areaName, project: c.projectName })),
+      added: data.added.map((a) => ({ uuid: a.uuid, title: a.title, createdAt: unixToDate(a.creationDate)?.toISOString(), area: a.areaName, project: a.projectName })),
+      deadlines: data.deadlines.map((d) => ({ uuid: d.uuid, title: d.title, deadline: formatThingsShortDate(d.deadline), area: d.areaName, project: d.projectName })),
     };
   }
 
@@ -73,7 +77,7 @@ function run(opts = {}) {
   for (const [area, items] of _groupBy(data.completed, 'areaName')) {
     lines.push(`  ${colors.magenta('[' + area + ']')} ${items.length}`);
     for (const t of items.slice(0, 50)) {
-      const d = cocoaToDate(t.stopDate);
+      const d = unixToDate(t.stopDate);
       const day = d ? d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' }) : '';
       lines.push(`    ✓ ${t.title} ${colors.dim('(' + day + ')')}`);
     }
@@ -86,7 +90,7 @@ function run(opts = {}) {
   lines.push('');
   lines.push(`${colors.bold('Deadlines next ' + days + ' day' + (days === 1 ? '' : 's'))} (${data.deadlines.length})`);
   for (const t of data.deadlines) {
-    const d = formatShortDate(t.deadline);
+    const d = formatThingsShortDate(t.deadline);
     lines.push(`  📅 ${d}  ${t.title}${t.areaName ? ` ${colors.magenta('[' + t.areaName + ']')}` : ''}`);
   }
   return lines;

src/commands/show.js

@@ -4,7 +4,7 @@ const db = require('../lib/db');
 const queries = require('../lib/queries');
 const { resolveTaskId } = require('../lib/uuid');
 const { colors, taskToJson } = require('../lib/format');
-const { formatShortDate } = require('../lib/dates');
+const { formatThingsShortDate } = require('../lib/dates');
 const { STATUS, START } = require('../lib/constants');
 
 function _details(database, task) {
@@ -24,9 +24,9 @@ function _details(database, task) {
   if (task.areaName) lines.push(`Area: ${task.areaName}`);
   const tags = task.tagList ? task.tagList.split(',').filter(Boolean) : [];
   if (tags.length) lines.push(`Tags: ${tags.join(', ')}`);
-  const scheduled = formatShortDate(task.startDate);
+  const scheduled = formatThingsShortDate(task.startDate);
   if (scheduled) lines.push(`Scheduled: ${scheduled}`);
-  const deadline = formatShortDate(task.deadline);
+  const deadline = formatThingsShortDate(task.deadline);
   if (deadline) lines.push(`Deadline: ${deadline}`);
   if (task.notes) {
     lines.push('');

src/commands/stats.js

@@ -1,20 +1,21 @@
 'use strict';
 
 const db = require('../lib/db');
-const { todayBounds, unixToCocoa } = require('../lib/dates');
+const { todayBounds, encodeThingsDate, packedTomorrow } = require('../lib/dates');
 const { colors } = require('../lib/format');
 
 function _gather(database) {
   const bounds = todayBounds();
-  const cocoaTodayStart = unixToCocoa(bounds.start);
+  const today = encodeThingsDate();      // packed calendar date for startDate/deadline
+  const tomorrow = packedTomorrow();     // exclusive upper bound for "today or earlier"
   const q = (sql, ...p) => database.prepare(sql).get(...p).count;
 
   return {
     today: q(`
       SELECT COUNT(*) as count FROM TMTask
       WHERE status = 0 AND trashed = 0 AND type = 0
-        AND (todayIndex > 0 OR (startDate >= 1000000000 AND startDate < ?))
-    `, bounds.end),
+        AND start = 1 AND startDate IS NOT NULL AND startDate > 0 AND startDate < ?
+    `, tomorrow),
     inbox: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0 AND start=0`),
     anytime: q(`
       SELECT COUNT(*) as count FROM TMTask
@@ -23,13 +24,13 @@ function _gather(database) {
     someday: q(`
       SELECT COUNT(*) as count FROM TMTask
       WHERE status=0 AND trashed=0 AND type=0 AND start=2 AND todayIndex<=0
-        AND (startDate IS NULL OR startDate < 1000000000)
+        AND startDate IS NULL
     `),
-    upcoming: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0 AND startDate >= ?`, bounds.end),
+    upcoming: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0 AND startDate IS NOT NULL AND startDate >= ? AND todayIndex<=0`, tomorrow),
     evening: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0 AND startBucket=1 AND todayIndex<=0`),
-    overdue: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0 AND deadline > 1000000000 AND deadline < ?`, bounds.start),
+    overdue: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0 AND deadline IS NOT NULL AND deadline > 0 AND deadline < ?`, today),
     totalOpen: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=0`),
-    completedToday: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=3 AND trashed=0 AND type=0 AND stopDate >= ?`, cocoaTodayStart),
+    completedToday: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=3 AND trashed=0 AND type=0 AND stopDate >= ?`, bounds.start),
     projects: q(`SELECT COUNT(*) as count FROM TMTask WHERE status=0 AND trashed=0 AND type=1`),
   };
 }

src/commands/watch.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const db = require('../lib/db');
-const { cocoaToDate } = require('../lib/dates');
+const { unixToDate } = require('../lib/dates');
 
 // Polls TMTask.userModificationDate; emits NDJSON for each event detected.
 function run(opts = {}) {
@@ -30,7 +30,7 @@ function run(opts = {}) {
     for (const r of rows) {
       if (r.userModificationDate > lastSeen) lastSeen = r.userModificationDate;
       if (r.type !== 0) continue;
-      const at = cocoaToDate(r.userModificationDate)?.toISOString();
+      const at = unixToDate(r.userModificationDate)?.toISOString();
       if (wantAdditions && r.creationDate >= startedAt) {
         _emit({ event: 'added', uuid: r.uuid, title: r.title, at });
       }

src/lib/dates.js

@@ -1,8 +1,11 @@
 'use strict';
 
 // Cocoa epoch is 2001-01-01T00:00:00Z; Unix epoch is 1970-01-01T00:00:00Z.
-// Things stores some timestamps as Cocoa seconds (stopDate, creationDate,
-// userModificationDate) and others as Unix seconds (startDate, deadline).
+// The COCOA_EPOCH_OFFSET helpers remain for any Cocoa-encoded column, but note:
+// in the current Things schema the *timestamp* columns (stopDate, creationDate,
+// userModificationDate) are plain Unix seconds, and the *calendar-date* columns
+// (startDate, deadline) are NOT timestamps at all — they're bit-packed dates.
+// See decodeThingsDate/encodeThingsDate below.
 const COCOA_EPOCH_OFFSET = 978307200;
 
 function cocoaToUnix(seconds) {
@@ -53,6 +56,43 @@ function formatIsoDate(unixSeconds) {
   return date.toISOString();
 }
 
+// Things stores calendar dates (startDate, deadline) as a bit-packed integer,
+// NOT a timestamp:  (year << 16) | (month << 12) | (day << 7),  low 7 bits
+// reserved. e.g. 2026-06-16 -> 132802560. Because the packing is year-major it
+// is monotonic in real date order, so packed ints compare correctly (<, <=, >=).
+function decodeThingsDate(packed) {
+  if (packed == null || packed <= 0) return null;
+  const day = (packed >> 7) & 0x1f;
+  const month = (packed >> 12) & 0x0f;
+  const year = packed >> 16;
+  if (!year || !month || !day) return null;
+  return new Date(year, month - 1, day);
+}
+
+function encodeThingsDate(date = new Date()) {
+  const y = date.getFullYear();
+  const m = date.getMonth() + 1;
+  const d = date.getDate();
+  return (y << 16) | (m << 12) | (d << 7);
+}
+
+// Midnight tonight, packed — the exclusive upper bound for "today or earlier".
+function packedTomorrow(now = new Date()) {
+  const d = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
+  return encodeThingsDate(d);
+}
+
+function formatThingsShortDate(packed) {
+  const date = decodeThingsDate(packed);
+  if (!date) return null;
+  return `${MONTHS[date.getMonth()]} ${date.getDate()}`;
+}
+
+function thingsDateToIso(packed) {
+  const date = decodeThingsDate(packed);
+  return date ? date.toISOString() : null;
+}
+
 module.exports = {
   COCOA_EPOCH_OFFSET,
   cocoaToUnix,
@@ -63,4 +103,9 @@ module.exports = {
   daysAgoUnix,
   formatShortDate,
   formatIsoDate,
+  decodeThingsDate,
+  encodeThingsDate,
+  packedTomorrow,
+  formatThingsShortDate,
+  thingsDateToIso,
 };

src/lib/format.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { STATUS, START } = require('./constants');
-const { formatShortDate } = require('./dates');
+const { formatThingsShortDate, thingsDateToIso, encodeThingsDate, packedTomorrow } = require('./dates');
 
 // TTY-aware coloring. Disabled if NO_COLOR is set or stdout is not a TTY.
 const _colorEnabled = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -51,17 +51,14 @@ function formatTask(task, opts = {}) {
     else if (task.areaName) line += ` ${colors.dim('[' + task.areaName + ']')}`;
   }
 
-  const deadline = formatShortDate(task.deadline);
+  const deadline = formatThingsShortDate(task.deadline);
   if (deadline) line += ` ${colors.yellow('📅 ' + deadline)}`;
 
-  if (showScheduled) {
-    const scheduled = formatShortDate(task.startDate);
-    if (scheduled && task.startDate >= 1000000000) {
-      // Only show the arrow when the scheduled date is in the future.
-      const todayEnd = new Date(new Date().setHours(24, 0, 0, 0)).getTime() / 1000;
-      if (task.startDate >= todayEnd) {
-        line += ` ${colors.blue('→ ' + scheduled)}`;
-      }
+  if (showScheduled && task.startDate) {
+    const scheduled = formatThingsShortDate(task.startDate);
+    // Only show the arrow when the scheduled date is in the future.
+    if (scheduled && task.startDate > encodeThingsDate()) {
+      line += ` ${colors.blue('→ ' + scheduled)}`;
     }
   }
 
@@ -70,7 +67,6 @@ function formatTask(task, opts = {}) {
 
 // Render a task as a plain JSON-ready object.
 function taskToJson(task) {
-  const { unixToDate } = require('./dates');
   return {
     uuid: task.uuid,
     title: task.title,
@@ -81,12 +77,12 @@ function taskToJson(task) {
         : task.status === STATUS.CANCELED
         ? 'canceled'
         : 'open',
-    startDate: task.startDate >= 1000000000 ? unixToDate(task.startDate).toISOString() : null,
-    deadline: task.deadline >= 1000000000 ? unixToDate(task.deadline).toISOString() : null,
+    startDate: thingsDateToIso(task.startDate),
+    deadline: thingsDateToIso(task.deadline),
     tags: task.tagList ? task.tagList.split(',').filter(Boolean).sort() : (task._tags || []),
     project: task.projectName || null,
     area: task.areaName || null,
-    inToday: task.todayIndex > 0,
+    inToday: task.start === START.ANYTIME && task.startDate != null && task.startDate > 0 && task.startDate < packedTomorrow(),
     list: listName(task.start),
     evening: task.startBucket === 1,
   };