@chronicle.app/things-todo 0.1.0 → 0.3.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,8 @@ export declare class ThingsTodoExtractor extends SqliteExtractor<typeof ThingsTo
     static default: boolean;
     static schema: any;
     static defaultTransformer: typeof ThingsTodoTransformer;
+    /** 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

@@ -2,6 +2,7 @@ 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.
@@ -44,9 +45,16 @@ 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 owner's name from the local machine, used when `agentName` isn't set. */
+    resolveAgentName() {
+        return localAccountName();
+    }
     getStatusLabel(status) {
         switch (status) {
             case 0:
@@ -81,6 +89,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 +136,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 +165,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.1.0",
+  "version": "0.3.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -19,7 +19,9 @@
   "type": "module",
   "description": "Chronicle things-todo extraction plugin",
   "devDependencies": {
-    "@chronicle.app/tsconfig": "0.1.0",
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -34,10 +36,12 @@
     "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"
+    "@chronicle.app/etl-sqlite": "0.3.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
   },
   "engines": {
     "node": ">=22.13.0"
@@ -49,7 +53,23 @@
     }
   },
   "chronicle": {
-    "plugin": true
-  },
-  "oclif": {}
+    "plugin": true,
+    "sources": {
+      "things-todo": {
+        "strategies": {
+          "app-db": {
+            "delivery": "local",
+            "recordTypes": [
+              "tasks",
+              "projects"
+            ],
+            "default": true
+          }
+        },
+        "platforms": [
+          "darwin"
+        ]
+      }
+    }
+  }
 }