@chronicle.app/things-todo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @chronicle.app/things-todo
+
+Read Things 3 tasks/projects with `ThingsTodoExtractor`, then map task lifecycle events with `ThingsTodoTransformer`. The default path locates the installed Things database; pass `input` to use a consistent backup or fixture. Optional `agentName` labels the source-local task owner.
+
+Uses read-only `node:sqlite`. `since`/`until` are inclusive modification-date bounds; `limit: 0` is unlimited. Records are newest-modified first. Raw project/heading records enrich task relationships; the transformer emits task actions (plan, update, complete, cancel, delete), not standalone project actions. Source timestamps remain event timestamps; no store annotations are generated.
+
+Use the ETL Runner or call setup/extract/teardown directly, always tearing down in a finally block. This package has no CLI dependency. The tests build synthetic Things tables without accessing an installed application.

package/dist/connectors/ThingsTodoExtractor.d.ts

@@ -0,0 +1,20 @@
+import { Record } from '@chronicle.app/etl';
+import { SqliteExtractor } from '@chronicle.app/etl-sqlite';
+import ThingsTodoTransformer from './ThingsTodoTransformer.js';
+export declare class ThingsTodoExtractor extends SqliteExtractor<typeof ThingsTodoExtractor> {
+    static source: string;
+    static delivery: "local";
+    static strategy: string;
+    static temporality: "snapshot";
+    static description: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static schema: any;
+    static defaultTransformer: typeof ThingsTodoTransformer;
+    private getStatusLabel;
+    extract(): AsyncGenerator<Record>;
+    private getEnrichedAreas;
+    private getEnrichedProjects;
+    private getTagHierarchies;
+}
+//# sourceMappingURL=ThingsTodoExtractor.d.ts.map

package/dist/connectors/ThingsTodoExtractor.js

@@ -0,0 +1,304 @@
+import { SqliteExtractor, timeRangeConditions } from '@chronicle.app/etl-sqlite';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import ThingsTodoTransformer from './ThingsTodoTransformer.js';
+/**
+ * Resolve the Things 3 SQLite database path.
+ *
+ * Things stores its data under a per-install directory whose name is
+ * `ThingsData-XXXXX` (the suffix is unique to each installation), so the path
+ * cannot be hardcoded. Glob the Group Containers directory for the
+ * `ThingsData-*` folder and return the database inside it.
+ */
+function resolveThingsDbPath() {
+    const containerDir = `${process.env.HOME}/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac`;
+    const dbSuffix = 'Things Database.thingsdatabase/main.sqlite';
+    if (existsSync(containerDir)) {
+        const thingsDataDirs = readdirSync(containerDir).filter(name => name.startsWith('ThingsData-'));
+        for (const dir of thingsDataDirs) {
+            const dbPath = join(containerDir, dir, dbSuffix);
+            if (existsSync(dbPath)) {
+                return dbPath;
+            }
+        }
+    }
+    // Fall back to the conventional location so the error message is meaningful
+    // when Things is not installed.
+    return join(containerDir, 'ThingsData', dbSuffix);
+}
+export class ThingsTodoExtractor extends SqliteExtractor {
+    static source = 'things-todo';
+    static delivery = 'local';
+    static strategy = 'app-db';
+    // Re-reads current task state, so attributes (name, status) are sighted at
+    // read time — not back-dated to the creation/modification timestamps the
+    // actions carry. Lets a rename supersede cleanly instead of colliding with the
+    // old name at the creation instant. See Extractor.temporality.
+    static temporality = 'snapshot';
+    static description = 'Tasks and projects';
+    static recordTypes = ['tasks', 'projects'];
+    static default = true;
+    static schema = SqliteExtractor.schema.omit({ input: true }).extend({
+        input: z
+            .string()
+            .describe('The db file to read from')
+            .default(() => resolveThingsDbPath()),
+        agentName: z.string().optional().describe('Name of the task owner, when known'),
+    });
+    static defaultTransformer = ThingsTodoTransformer;
+    getStatusLabel(status) {
+        switch (status) {
+            case 0:
+                return 'open';
+            case 2:
+                return 'cancelled';
+            case 3:
+                return 'completed';
+            default:
+                return 'unknown';
+        }
+    }
+    async *extract() {
+        if (!this.db) {
+            throw new Error('Database not initialized');
+        }
+        const limit = this.getEffectiveLimit();
+        const { conditions, values } = timeRangeConditions('task.userModificationDate', this.config, {
+            sinceOp: '>=',
+            untilOp: '<=',
+        });
+        let sql = `SELECT task.*, group_concat(DISTINCT tag.uuid) AS tag_ids,
+      group_concat(DISTINCT tag.title) AS tag_titles FROM TMTask task
+      LEFT JOIN TMTaskTag tagging ON task.uuid = tagging.tasks
+      LEFT JOIN TMTag tag ON tagging.tags = tag.uuid
+      WHERE task.type IN (0, 1, 2)`;
+        if (conditions.length > 0)
+            sql += ' AND ' + conditions.join(' AND ');
+        sql += ' GROUP BY task.uuid ORDER BY task.userModificationDate DESC, task.uuid';
+        if (limit !== null) {
+            sql += ' LIMIT ?';
+            values.push(limit);
+        }
+        const rows = this.db.prepare(sql).all(...values);
+        // Get enriched areas and projects with nested data
+        const areaIds = [...new Set(rows.map(row => row.area))].filter(Boolean);
+        const enrichedAreas = await this.getEnrichedAreas(areaIds);
+        // Get both direct projects and headings (which can also be projects)
+        const directProjectIds = [...new Set(rows.map(row => row.project))].filter(Boolean);
+        const headingIds = [...new Set(rows.map(row => row.heading))].filter(Boolean);
+        const allProjectIds = [...new Set([...directProjectIds, ...headingIds])];
+        const enrichedProjects = this.getEnrichedProjects(allProjectIds);
+        // Get tag hierarchies for all tags used
+        const allTagIds = rows
+            .map(row => row.tag_ids)
+            .filter(Boolean)
+            .join(',')
+            .split(',')
+            .filter(Boolean);
+        const tagHierarchies = this.getTagHierarchies([...new Set(allTagIds)]);
+        for (const row of rows) {
+            const recordType = row.type === 1 || row.type === 2 ? 'projects' : 'tasks';
+            // Convert timestamps to dates
+            const timeline = {
+                createdAt: row.creationDate ? new Date(row.creationDate * 1000) : null,
+                startedAt: row.startDate ? new Date(row.startDate * 1000) : null,
+                completedAt: row.stopDate ? new Date(row.stopDate * 1000) : null,
+                status: this.getStatusLabel(row.status),
+                lastModifiedAt: row.userModificationDate ? new Date(row.userModificationDate * 1000) : null,
+            };
+            // Build enriched tags array with hierarchies
+            const taskTagIds = row.tag_ids ? row.tag_ids.split(',') : [];
+            const taskTagTitles = row.tag_titles ? row.tag_titles.split(',') : [];
+            const enrichedTags = taskTagIds.map((tagId, index) => {
+                const hierarchy = tagHierarchies.get(tagId);
+                return {
+                    uuid: tagId,
+                    title: taskTagTitles[index] || null,
+                    shortcut: hierarchy?.shortcut || null,
+                    hierarchy: hierarchy
+                        ? {
+                            parent: hierarchy.parent,
+                            children: hierarchy.children,
+                            path: hierarchy.path,
+                            level: hierarchy.level,
+                        }
+                        : null,
+                    lastUsedAt: hierarchy?.lastUsedAt || null,
+                };
+            });
+            // Get user's real name for Person object deduplication
+            const realName = this.config.agentName;
+            // Determine the project relationship
+            let projectRelation = null;
+            let headingRelation = null;
+            // If task has a direct project, use that
+            if (row.project) {
+                projectRelation = enrichedProjects.get(row.project);
+            }
+            // If task has a heading, the heading might belong to a project
+            else if (row.heading) {
+                const heading = enrichedProjects.get(row.heading);
+                if (heading) {
+                    headingRelation = {
+                        uuid: heading.uuid,
+                        title: heading.title,
+                        type: heading.type,
+                    };
+                    // If the heading belongs to a project, use that project
+                    if (heading.project) {
+                        projectRelation = enrichedProjects.get(heading.project);
+                    }
+                }
+            }
+            yield this.createRecord(row, {
+                recordType,
+                timeline,
+                project: projectRelation,
+                heading: headingRelation,
+                area: row.area ? enrichedAreas.get(row.area) || null : null,
+                tags: enrichedTags,
+                agent: {
+                    name: realName, // Just the real name for Person [@type, title, source] deduplication
+                },
+            });
+        }
+    }
+    async getEnrichedAreas(areaIds) {
+        const enrichedAreas = new Map();
+        if (areaIds.length === 0)
+            return enrichedAreas;
+        const areas = this.db.prepare(`SELECT area.*,
+      group_concat(DISTINCT area_tag.tags) AS area_tag_ids,
+      group_concat(DISTINCT tag.title) AS area_tag_titles,
+      COUNT(DISTINCT task.uuid) AS task_count,
+      COUNT(DISTINCT project.uuid) AS project_count
+      FROM TMArea area
+      LEFT JOIN TMAreaTag area_tag ON area.uuid = area_tag.areas
+      LEFT JOIN TMTag tag ON area_tag.tags = tag.uuid
+      LEFT JOIN TMTask task ON area.uuid = task.area AND task.type IN (0, 1)
+      LEFT JOIN TMTask project ON area.uuid = project.area AND project.type = 2
+      WHERE area.uuid IN (${areaIds.map(() => '?').join(',')}) GROUP BY area.uuid
+    `).all(...areaIds);
+        for (const area of areas) {
+            const areaData = area;
+            const areaTagIds = areaData.area_tag_ids ? areaData.area_tag_ids.split(',') : [];
+            const areaTagTitles = areaData.area_tag_titles ? areaData.area_tag_titles.split(',') : [];
+            const tags = areaTagIds.map((id, index) => ({
+                uuid: id,
+                title: areaTagTitles[index] || null,
+            }));
+            enrichedAreas.set(areaData.uuid, {
+                ...areaData,
+                tags,
+                metrics: {
+                    taskCount: Number.parseInt(areaData.task_count) || 0,
+                    projectCount: Number.parseInt(areaData.project_count) || 0,
+                },
+            });
+        }
+        return enrichedAreas;
+    }
+    getEnrichedProjects(projectIds) {
+        const enrichedProjects = new Map();
+        if (projectIds.length === 0)
+            return enrichedProjects;
+        const query = `
+      SELECT 
+        project.*,
+        area.title as area_title,
+        area.uuid as area_uuid,
+        COUNT(DISTINCT task.uuid) as task_count,
+        COUNT(DISTINCT completed_task.uuid) as completed_task_count
+      FROM TMTask project
+      LEFT JOIN TMArea area ON project.area = area.uuid
+      LEFT JOIN TMTask task ON (project.uuid = task.project OR project.uuid = task.heading) AND task.type IN (0, 1)
+      LEFT JOIN TMTask completed_task ON (project.uuid = completed_task.project OR project.uuid = completed_task.heading) AND completed_task.type IN (0, 1) AND completed_task.status = 3
+      WHERE project.uuid IN (${projectIds.map(() => '?').join(',')}) AND project.type IN (1, 2)
+      GROUP BY project.uuid
+    `;
+        const projects = this.db.prepare(query).all(...projectIds);
+        for (const project of projects) {
+            const projectData = project;
+            enrichedProjects.set(projectData.uuid, {
+                ...projectData,
+                area: projectData.area_uuid
+                    ? {
+                        uuid: projectData.area_uuid,
+                        title: projectData.area_title,
+                    }
+                    : null,
+                metrics: {
+                    totalTasks: Number.parseInt(projectData.task_count) || 0,
+                    completedTasks: Number.parseInt(projectData.completed_task_count) || 0,
+                    progress: projectData.task_count > 0
+                        ? projectData.completed_task_count / projectData.task_count
+                        : 0,
+                },
+            });
+        }
+        return enrichedProjects;
+    }
+    getTagHierarchies(tagIds) {
+        const tagHierarchies = new Map();
+        if (tagIds.length === 0)
+            return tagHierarchies;
+        // Get all tags with their parent relationships
+        const query = `
+      SELECT 
+        tag.*,
+        parent.title as parent_title,
+        group_concat(DISTINCT child.uuid) as child_ids,
+        group_concat(DISTINCT child.title) as child_titles
+      FROM TMTag tag
+      LEFT JOIN TMTag parent ON tag.parent = parent.uuid
+      LEFT JOIN TMTag child ON tag.uuid = child.parent
+      WHERE tag.uuid IN (${tagIds.map(() => '?').join(',')})
+      GROUP BY tag.uuid
+      ORDER BY tag.title
+    `;
+        const tags = this.db.prepare(query).all(...tagIds);
+        // Build hierarchical paths
+        const buildPath = (tagId, visited = new Set()) => {
+            if (visited.has(tagId))
+                return ''; // Prevent cycles
+            visited.add(tagId);
+            const tag = tags.find((t) => t.uuid === tagId);
+            if (!tag)
+                return '';
+            const tagData = tag;
+            if (tagData.parent) {
+                const parentPath = buildPath(tagData.parent, visited);
+                return parentPath ? `${parentPath} > ${tagData.title}` : tagData.title;
+            }
+            return tagData.title;
+        };
+        for (const tag of tags) {
+            const tagData = tag;
+            const childIds = tagData.child_ids ? tagData.child_ids.split(',') : [];
+            const childTitles = tagData.child_titles ? tagData.child_titles.split(',') : [];
+            const children = childIds.map((id, index) => ({
+                uuid: id,
+                title: childTitles[index] || null,
+            }));
+            const path = buildPath(tagData.uuid);
+            const level = path.split(' > ').length - 1;
+            tagHierarchies.set(tagData.uuid, {
+                uuid: tagData.uuid,
+                title: tagData.title,
+                shortcut: tagData.shortcut,
+                lastUsedAt: tagData.usedDate ? new Date(tagData.usedDate * 1000) : null,
+                parent: tagData.parent
+                    ? {
+                        uuid: tagData.parent,
+                        title: tagData.parent_title,
+                    }
+                    : null,
+                children,
+                path,
+                level,
+            });
+        }
+        return tagHierarchies;
+    }
+}

package/dist/connectors/ThingsTodoTransformer.d.ts

@@ -0,0 +1,13 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class ThingsTodoTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildTaskActions;
+    private buildAction;
+    private buildUser;
+    private buildTask;
+    private buildProject;
+    private buildHeading;
+    private buildArea;
+}
+//# sourceMappingURL=ThingsTodoTransformer.d.ts.map

package/dist/connectors/ThingsTodoTransformer.js

@@ -0,0 +1,166 @@
+import { ChronicleTransformer } from '@chronicle.app/etl';
+export default class ThingsTodoTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'tasks') {
+            actions.push(...this.buildTaskActions(record));
+        }
+        return actions;
+    }
+    buildTaskActions(record) {
+        const actions = [];
+        const task = this.buildTask({
+            task: record.data,
+            project: record.context.project,
+            area: record.context.area,
+            heading: record.context.heading,
+            tags: record.context.tags,
+        });
+        const user = this.buildUser(record.context.agent.name);
+        // Always create the initial PlanAction with creation timestamp
+        actions.push(this.buildAction({
+            data: record.data,
+            timestamp: record.data.creationDate,
+            type: 'PlanAction',
+            agentObj: user,
+            taskObj: task,
+        }));
+        // If task was edited (modification date differs significantly from creation), create UpdateAction
+        const timeDifferenceSeconds = Math.abs(record.data.userModificationDate - record.data.creationDate);
+        const wasEdited = timeDifferenceSeconds > 60; // More than 60 seconds difference indicates an edit
+        // Completing/cancelling/trashing a task bumps userModificationDate, which would
+        // otherwise emit a redundant UpdateAction alongside the terminal action. Skip the
+        // update when the modification just reflects that terminal event.
+        const terminalTimestamp = record.data.status == 3 || record.data.status == 2
+            ? record.data.stopDate
+            : record.data.trashed == 1
+                ? record.data.userModificationDate
+                : undefined;
+        const modificationIsTerminal = terminalTimestamp !== undefined &&
+            Math.abs(record.data.userModificationDate - terminalTimestamp) <= 60;
+        if (wasEdited && !modificationIsTerminal) {
+            const updateAction = {
+                '@type': 'UpdateAction',
+                timestamp: new Date(record.data.userModificationDate * 1000),
+                '@key': ['@type', 'source', 'sourceId'],
+                source: 'things-todo',
+                sourceId: record.data.uuid,
+                agent: user,
+                object: task,
+            };
+            actions.push(updateAction);
+        }
+        if (record.data.status == 3) {
+            actions.push(this.buildAction({
+                data: record.data,
+                timestamp: record.data.stopDate,
+                type: 'CompleteAction',
+                agentObj: user,
+                taskObj: task,
+            }));
+        }
+        else if (record.data.status == 2) {
+            actions.push(this.buildAction({
+                data: record.data,
+                timestamp: record.data.stopDate,
+                type: 'CancelAction',
+                agentObj: user,
+                taskObj: task,
+            }));
+        }
+        if (record.data.trashed == 1) {
+            actions.push(this.buildAction({
+                data: record.data,
+                timestamp: record.data.userModificationDate,
+                type: 'DeleteAction',
+                agentObj: user,
+                taskObj: task,
+            }));
+        }
+        return actions;
+    }
+    buildAction({ data, timestamp, type, agentObj, taskObj, }) {
+        return {
+            '@type': type,
+            timestamp: new Date(timestamp * 1000),
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'things-todo',
+            sourceId: data.uuid,
+            agent: agentObj,
+            object: taskObj,
+        };
+    }
+    buildUser(realName) {
+        return {
+            '@type': 'Agent',
+            '@key': ['@type', 'source'],
+            source: 'things-todo',
+            name: realName,
+            sameAs: ['@me'],
+        };
+    }
+    buildTask({ task, project, area, heading, tags, }) {
+        const obj = {
+            '@type': 'Task',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'things-todo',
+            sourceId: task.uuid,
+            name: task.title,
+        };
+        if (task.notes) {
+            obj.description = task.notes;
+        }
+        const isPartOf = [];
+        if (project) {
+            isPartOf.push(this.buildProject(project));
+        }
+        if (heading) {
+            isPartOf.push(this.buildHeading(heading)); // Headings are organizational sections
+        }
+        if (area) {
+            isPartOf.push(this.buildArea(area));
+        }
+        if (isPartOf.length > 0) {
+            obj.isPartOf = isPartOf;
+        }
+        // Add tags as 'about' entities (representing what the task is about)
+        if (tags && tags.length > 0) {
+            obj.about = tags.map(tag => ({
+                '@type': 'Tag',
+                '@key': ['@type', 'source', 'sourceId'],
+                source: 'things-todo',
+                sourceId: tag.uuid,
+                handle: tag.title,
+                name: tag.title,
+            }));
+        }
+        return obj;
+    }
+    buildProject(project) {
+        return {
+            '@type': 'Project',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'things-todo',
+            sourceId: project.uuid,
+            name: project.title,
+        };
+    }
+    buildHeading(heading) {
+        return {
+            '@type': 'Collection',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'things-todo',
+            sourceId: heading.uuid,
+            name: heading.title,
+        };
+    }
+    buildArea(area) {
+        return {
+            '@type': 'Collection',
+            '@key': ['@type', 'source', 'sourceId'],
+            source: 'things-todo',
+            sourceId: area.uuid,
+            name: area.title,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ThingsTodoExtractor } from './connectors/ThingsTodoExtractor.js';
+export { default as ThingsTodoTransformer } from './connectors/ThingsTodoTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+// Export extractors for plugin scanning
+export { ThingsTodoExtractor } from './connectors/ThingsTodoExtractor.js';
+export { default as ThingsTodoTransformer } from './connectors/ThingsTodoTransformer.js';

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@chronicle.app/things-todo",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle things-todo extraction plugin",
+  "devDependencies": {
+    "@chronicle.app/tsconfig": "0.1.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/things-todo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@chronicle.app/etl": "0.1.0",
+    "@chronicle.app/schema": "0.1.0",
+    "zod": "^3.24.1",
+    "@chronicle.app/etl-sqlite": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true
+  },
+  "oclif": {}
+}