@chronicle.app/things-todo 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+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. The task owner is a source-local `Agent` tagged `@me`, named after the OS account's full name (`id -F` on macOS); set `agentName` to use another name. The name is a label only: the owner is keyed by `['@type', 'source']` and gets no invented identifiers. Elsewhere, or when the account has no full name, the owner has no name.
 
 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.
 

package/dist/connectors/ThingsTodoExtractor.d.ts

@@ -11,6 +11,13 @@ export declare class ThingsTodoExtractor extends SqliteExtractor<typeof ThingsTo
     static default: boolean;
     static schema: any;
     static defaultTransformer: typeof ThingsTodoTransformer;
+    /**
+     * The default database lives in a folder macOS guards: say whether it's
+     * missing or refused before SQLite reports "unable to open database file".
+     */
+    setup(): Promise<void>;
+    /** The owner's name from the local machine, used when `agentName` isn't set. */
+    protected resolveAgentName(): string | undefined;
     private getStatusLabel;
     extract(): AsyncGenerator<Record>;
     private getEnrichedAreas;

package/dist/connectors/ThingsTodoExtractor.js

@@ -1,7 +1,9 @@
+import { fileError } from '@chronicle.app/etl';
 import { SqliteExtractor, timeRangeConditions } from '@chronicle.app/etl-sqlite';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
+import { localAccountName } from './ownerName.js';
 import ThingsTodoTransformer from './ThingsTodoTransformer.js';
 /**
  * Resolve the Things 3 SQLite database path.
@@ -11,11 +13,20 @@ import ThingsTodoTransformer from './ThingsTodoTransformer.js';
  * cannot be hardcoded. Glob the Group Containers directory for the
  * `ThingsData-*` folder and return the database inside it.
  */
+const containerDir = `${process.env.HOME}/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac`;
 function resolveThingsDbPath() {
-    const containerDir = `${process.env.HOME}/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac`;
     const dbSuffix = 'Things Database.thingsdatabase/main.sqlite';
+    // Listing the container needs Full Disk Access; without it, fall through to
+    // the conventional path and let setup() say what's wrong.
     if (existsSync(containerDir)) {
-        const thingsDataDirs = readdirSync(containerDir).filter(name => name.startsWith('ThingsData-'));
+        let entries = [];
+        try {
+            entries = readdirSync(containerDir);
+        }
+        catch {
+            // Reported by setup().
+        }
+        const thingsDataDirs = entries.filter(name => name.startsWith('ThingsData-'));
         for (const dir of thingsDataDirs) {
             const dbPath = join(containerDir, dir, dbSuffix);
             if (existsSync(dbPath)) {
@@ -44,9 +55,32 @@ export class ThingsTodoExtractor extends SqliteExtractor {
             .string()
             .describe('The db file to read from')
             .default(() => resolveThingsDbPath()),
-        agentName: z.string().optional().describe('Name of the task owner, when known'),
+        agentName: z
+            .string()
+            .optional()
+            .describe("Name of the task owner. Defaults to the OS account's full name"),
     });
     static defaultTransformer = ThingsTodoTransformer;
+    /**
+     * The default database lives in a folder macOS guards: say whether it's
+     * missing or refused before SQLite reports "unable to open database file".
+     */
+    async setup() {
+        const { input } = this.config;
+        if (input.startsWith(containerDir)) {
+            try {
+                readdirSync(containerDir);
+            }
+            catch (error) {
+                throw fileError(error, containerDir, 'Things library');
+            }
+        }
+        await super.setup();
+    }
+    /** The owner's name from the local machine, used when `agentName` isn't set. */
+    resolveAgentName() {
+        return localAccountName();
+    }
     getStatusLabel(status) {
         switch (status) {
             case 0:
@@ -81,6 +115,7 @@ export class ThingsTodoExtractor extends SqliteExtractor {
             values.push(limit);
         }
         const rows = this.db.prepare(sql).all(...values);
+        const agentName = this.config.agentName ?? this.resolveAgentName();
         // 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);
@@ -127,8 +162,6 @@ export class ThingsTodoExtractor extends SqliteExtractor {
                     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;
@@ -158,9 +191,7 @@ export class ThingsTodoExtractor extends SqliteExtractor {
                 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
-                },
+                agent: { name: agentName },
             });
         }
     }

package/dist/connectors/ownerName.d.ts

@@ -0,0 +1,11 @@
+export interface OwnerNameOptions {
+    platform?: string;
+    run?: (command: string, args: string[]) => string;
+}
+/**
+ * The full name of the OS account running the extraction, as the owner of the
+ * local Things database. On macOS this is the account's full name from
+ * `id -F`. Returns undefined elsewhere or when the name is unset or unreadable.
+ */
+export declare function localAccountName(options?: OwnerNameOptions): string | undefined;
+//# sourceMappingURL=ownerName.d.ts.map

package/dist/connectors/ownerName.js

@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+/**
+ * The full name of the OS account running the extraction, as the owner of the
+ * local Things database. On macOS this is the account's full name from
+ * `id -F`. Returns undefined elsewhere or when the name is unset or unreadable.
+ */
+export function localAccountName(options = {}) {
+    if ((options.platform ?? process.platform) !== 'darwin')
+        return undefined;
+    const run = options.run ??
+        ((command, args) => execFileSync(command, args, {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }));
+    try {
+        return run('/usr/bin/id', ['-F']).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/things-todo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -19,9 +19,9 @@
   "type": "module",
   "description": "Chronicle things-todo extraction plugin",
   "devDependencies": {
-    "@chronicle.app/etl": "0.2.0",
-    "@chronicle.app/schema": "0.2.0",
-    "@chronicle.app/tsconfig": "0.2.0",
+    "@chronicle.app/etl": "0.4.0",
+    "@chronicle.app/schema": "0.4.0",
+    "@chronicle.app/tsconfig": "0.4.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -36,7 +36,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@chronicle.app/etl-sqlite": "0.2.0",
+    "@chronicle.app/etl-sqlite": "0.4.0",
     "zod": "^3.24.1"
   },
   "peerDependencies": {
@@ -53,7 +53,23 @@
     }
   },
   "chronicle": {
-    "plugin": true
-  },
-  "oclif": {}
+    "plugin": true,
+    "sources": {
+      "things-todo": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "tasks",
+              "projects"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ]
+      }
+    }
+  }
 }