@chronova/pi-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NX Solutions UG (haftungsbeschränkt)
+
+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,88 @@
+# chronova-pi-plugin
+
+Chronova heartbeat tracking extension for [oh-my-pi](https://omp.sh).
+
+Automatically sends coding activity heartbeats to your [Chronova](https://chronova.dev) dashboard via `chronova-cli` — a drop-in replacement for `wakatime-cli`.
+
+## Features
+
+- **Automatic tracking** — Monitors `read`, `edit`, `write`, and `ast_edit` tool results from oh-my-pi
+- **AI line changes** — Reports net AI-written lines (`--ai-line-changes`) for edit and write operations
+- **Rate limiting** — 1 heartbeat per minute per project, persisted to disk across restarts
+- **Force flush on exit** — All pending changes are flushed when the session shuts down
+- **Fire-and-forget** — Heartbeat invocations never block the agent loop
+
+## Prerequisites
+
+- [oh-my-pi](https://omp.sh) (pi-coding-agent v15+)
+- [chronova-cli](https://github.com/nx-solutions-ug/chronova-cli) installed at `~/.local/bin/chronova-cli`
+- A Chronova account with API key configured in `~/.chronova.cfg`
+
+## Installation
+
+### Option 1: Clone and build
+
+```bash
+git clone https://github.com/nx-solutions-ug/chronova-pi-plugin.git ~/.projects/chronova-pi-plugin
+cd ~/.projects/chronova-pi-plugin
+npm install
+npm run build
+ln -s ~/.projects/chronova-pi-plugin ~/.omp/agent/extensions/chronova-pi-plugin
+```
+
+### Option 2: Direct symlink (requires Node.js for build)
+
+```bash
+git clone https://github.com/nx-solutions-ug/chronova-pi-plugin.git /tmp/chronova-pi-plugin
+cd /tmp/chronova-pi-plugin
+npm install && npm run build
+mkdir -p ~/.omp/agent/extensions/chronova-pi-plugin
+cp dist/*.js package.json ~/.omp/agent/extensions/chronova-pi-plugin/
+```
+
+## Configuration
+
+The plugin reads the API key from `~/.chronova.cfg` automatically (same as `chronova-cli`). No separate configuration is needed.
+
+### Debug Logging
+
+Set `CHRONOVA_PI_DEBUG=1` or add `debug = true` to `~/.chronova.cfg` to enable verbose logging to `~/.chronova-pi-plugin/plugin.log`.
+
+## How It Works
+
+1. On `session_start`, the plugin records the project directory
+2. On `tool_result` events, it extracts file paths and line changes:
+   - **read** → tracked as view (no line changes)
+   - **edit** → diff parsed for additions/deletions
+   - **write** → tracked as write operation
+   - **ast_edit** → tracked from `fileReplacements` count
+3. When the rate limit allows (1/min/project), pending changes are flushed to `chronova-cli`
+4. On `session_shutdown`, all remaining changes are force-flushed
+
+### chronova-cli Arguments
+
+```bash
+chronova-cli \
+  --entity <absolute-file-path> \
+  --entity-type file \
+  --project-folder <project-directory> \
+  --plugin "oh-my-pi/1.0.0 chronova-pi-plugin/1.0.0" \
+  --category "ai coding" \
+  --write \                        # for write operations
+  --ai-line-changes <net-lines>    # additions - deletions
+```
+
+## Project Structure
+
+```
+src/
+  index.ts      Extension factory: registers event handlers on ExtensionAPI
+  heartbeat.ts  chronova-cli invocation (fire-and-forget via execFile)
+  tracker.ts    File-change extraction from tool_result events
+  state.ts      Per-project rate-limit state (persisted to disk)
+  logger.ts     Debug logger writing to ~/.chronova-pi-plugin/plugin.log
+```
+
+## License
+
+MIT © NX Solutions UG

package/dist/heartbeat.js

@@ -0,0 +1,79 @@
+import { execFile } from "node:child_process";
+import * as path from "node:path";
+import { logger } from "./logger.js";
+import { shouldSendHeartbeat, updateLastHeartbeat } from "./state.js";
+const PLUGIN_VERSION = "1.0.0";
+const CLI_PATH = path.join(process.env.HOME ?? "/home/dev", ".local/bin/chronova-cli");
+/**
+ * Send a heartbeat via chronova-cli. Fire-and-forget — never blocks
+ * the agent loop. Resolves after the process is spawned (not after it exits).
+ */
+export function sendHeartbeat(payload) {
+    if (!shouldSendHeartbeat(payload.projectFolder)) {
+        logger.debug("Heartbeat rate-limited, skipping", { projectFolder: payload.projectFolder });
+        return;
+    }
+    const args = [
+        "--entity", payload.entity,
+        "--entity-type", "file",
+        "--project-folder", payload.projectFolder,
+        "--plugin", `oh-my-pi/1.0.0 chronova-pi-plugin/${PLUGIN_VERSION}`,
+        "--category", "ai coding",
+    ];
+    if (payload.isWrite) {
+        args.push("--write");
+    }
+    if (payload.aiLineChanges !== 0) {
+        args.push("--ai-line-changes", String(payload.aiLineChanges));
+    }
+    logger.debug("Spawning chronova-cli", { args });
+    const child = execFile(CLI_PATH, args, (err, stdout, stderr) => {
+        if (err) {
+            logger.error("chronova-cli error", { error: String(err) });
+            return;
+        }
+        if (stderr) {
+            logger.warn("chronova-cli stderr", { stderr: stderr.trim() });
+        }
+        if (stdout) {
+            logger.debug("chronova-cli stdout", { stdout: stdout.trim() });
+        }
+    });
+    child.unref();
+    updateLastHeartbeat(payload.projectFolder);
+}
+/**
+ * Force-send a heartbeat, bypassing rate limits.
+ * Used for session shutdown flush.
+ */
+export function sendHeartbeatForce(payload) {
+    if (!shouldSendHeartbeat(payload.projectFolder, true)) {
+        // Always true with force, but keep the guard for type safety
+        return;
+    }
+    const args = [
+        "--entity", payload.entity,
+        "--entity-type", "file",
+        "--project-folder", payload.projectFolder,
+        "--plugin", `oh-my-pi/1.0.0 chronova-pi-plugin/${PLUGIN_VERSION}`,
+        "--category", "ai coding",
+    ];
+    if (payload.isWrite) {
+        args.push("--write");
+    }
+    if (payload.aiLineChanges !== 0) {
+        args.push("--ai-line-changes", String(payload.aiLineChanges));
+    }
+    logger.debug("Spawning chronova-cli (forced)", { args });
+    const child = execFile(CLI_PATH, args, (err, stdout, stderr) => {
+        if (err) {
+            logger.error("chronova-cli error (forced)", { error: String(err) });
+            return;
+        }
+        if (stderr) {
+            logger.warn("chronova-cli stderr (forced)", { stderr: stderr.trim() });
+        }
+    });
+    child.unref();
+    updateLastHeartbeat(payload.projectFolder);
+}

package/dist/index.js

@@ -0,0 +1,101 @@
+import { logger } from "./logger.js";
+import { sendHeartbeat, sendHeartbeatForce } from "./heartbeat.js";
+import { trackRead, trackWrite, trackEdit, flushPending, pendingCount, resolvePath } from "./tracker.js";
+import { shouldSendHeartbeat } from "./state.js";
+export default function chronovaPiPlugin(pi) {
+    pi.setLabel("Chronova Heartbeat");
+    let projectFolder = "";
+    // --- session_start: set up project folder ---
+    pi.on("session_start", async (_event, ctx) => {
+        projectFolder = ctx.cwd;
+        logger.info("Chronova tracking active", { projectFolder });
+    });
+    // --- tool_result: extract file changes and flush heartbeats ---
+    pi.on("tool_result", async (event, _ctx) => {
+        if (!projectFolder)
+            return;
+        const input = event.input;
+        switch (event.toolName) {
+            case "read": {
+                const filePath = input.path;
+                if (filePath) {
+                    trackRead(resolvePath(projectFolder, filePath));
+                    tryFlush();
+                }
+                break;
+            }
+            case "edit": {
+                const details = event.details;
+                if (details) {
+                    const resolvedDetails = {
+                        ...details,
+                        path: details.path ? resolvePath(projectFolder, details.path) : undefined,
+                        perFileResults: details.perFileResults?.map(r => ({
+                            ...r,
+                            path: resolvePath(projectFolder, r.path),
+                        })),
+                    };
+                    trackEdit(resolvedDetails);
+                    tryFlush();
+                }
+                break;
+            }
+            case "write": {
+                const filePath = input.path;
+                if (filePath) {
+                    trackWrite(resolvePath(projectFolder, filePath));
+                    tryFlush();
+                }
+                break;
+            }
+            case "ast_edit": {
+                const details = event.details;
+                if (details) {
+                    trackEdit({
+                        files: details.files?.map(f => resolvePath(projectFolder, f)),
+                        fileReplacements: details.fileReplacements?.map(r => ({
+                            ...r,
+                            path: resolvePath(projectFolder, r.path),
+                        })),
+                    });
+                    tryFlush();
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    });
+    // --- session_shutdown: force-flush pending heartbeats ---
+    pi.on("session_shutdown", async () => {
+        if (!projectFolder)
+            return;
+        const count = pendingCount();
+        if (count > 0) {
+            logger.info("Flushing pending heartbeats on shutdown", { count });
+            const payloads = flushPending(projectFolder);
+            for (const payload of payloads) {
+                sendHeartbeatForce(payload);
+            }
+        }
+    });
+    // --- internal ---
+    /**
+     * Only flush pending changes when the rate limit allows.
+     * If rate-limited, changes stay in the pending map for the next opportunity.
+     */
+    function tryFlush() {
+        if (!projectFolder || pendingCount() === 0)
+            return;
+        if (!shouldSendHeartbeat(projectFolder)) {
+            logger.debug("Rate-limited, keeping pending changes", {
+                pendingCount: pendingCount(),
+            });
+            return;
+        }
+        const payloads = flushPending(projectFolder);
+        for (const payload of payloads) {
+            sendHeartbeat(payload);
+        }
+    }
+}

package/dist/logger.js

@@ -0,0 +1,44 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const LOG_DIR = path.join(os.homedir(), ".chronova-pi-plugin");
+const LOG_FILE = path.join(LOG_DIR, "plugin.log");
+let debugEnabled;
+function isDebugEnabled() {
+    if (debugEnabled !== undefined)
+        return debugEnabled;
+    if (process.env.CHRONOVA_PI_DEBUG === "1") {
+        debugEnabled = true;
+        return true;
+    }
+    try {
+        const cfgPath = path.join(os.homedir(), ".chronova.cfg");
+        const content = fs.readFileSync(cfgPath, "utf-8");
+        debugEnabled = /debug\s*=\s*true/i.test(content);
+    }
+    catch {
+        debugEnabled = false;
+    }
+    return debugEnabled;
+}
+function write(level, msg, data) {
+    if (level === "DEBUG" && !isDebugEnabled())
+        return;
+    try {
+        fs.mkdirSync(LOG_DIR, { recursive: true });
+        const ts = new Date().toISOString();
+        const line = data !== undefined
+            ? `[${ts}] [${level}] ${msg} ${JSON.stringify(data)}\n`
+            : `[${ts}] [${level}] ${msg}\n`;
+        fs.appendFileSync(LOG_FILE, line);
+    }
+    catch {
+        // Swallow log write failures — never crash the extension
+    }
+}
+export const logger = {
+    debug(msg, data) { write("DEBUG", msg, data); },
+    info(msg, data) { write("INFO", msg, data); },
+    warn(msg, data) { write("WARN", msg, data); },
+    error(msg, data) { write("ERROR", msg, data); },
+};

package/dist/state.js

@@ -0,0 +1,45 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import { logger } from "./logger.js";
+const STATE_DIR = path.join(os.homedir(), ".chronova-pi-plugin", "state");
+const RATE_LIMIT_SECONDS = 60;
+function projectStateFile(projectFolder) {
+    const hash = crypto.createHash("sha256").update(projectFolder).digest("hex").slice(0, 16);
+    return path.join(STATE_DIR, `${hash}.json`);
+}
+function readState(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeState(filePath, state) {
+    try {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(state));
+    }
+    catch (err) {
+        logger.error("Failed to write state file", { filePath, error: String(err) });
+    }
+}
+export function shouldSendHeartbeat(projectFolder, force = false) {
+    if (force)
+        return true;
+    const stateFile = projectStateFile(projectFolder);
+    const state = readState(stateFile);
+    if (!state)
+        return true;
+    const elapsed = Math.floor(Date.now() / 1000) - state.lastHeartbeatAt;
+    return elapsed >= RATE_LIMIT_SECONDS;
+}
+export function updateLastHeartbeat(projectFolder) {
+    const stateFile = projectStateFile(projectFolder);
+    const now = Math.floor(Date.now() / 1000);
+    writeState(stateFile, { lastHeartbeatAt: now });
+    logger.debug("Updated heartbeat state", { projectFolder, lastHeartbeatAt: now });
+}

package/dist/tracker.js

@@ -0,0 +1,154 @@
+import * as path from "node:path";
+import { logger } from "./logger.js";
+const pending = new Map();
+/**
+ * Record a file view (read-only). Zero line changes.
+ */
+export function trackRead(filePath) {
+    const absPath = resolveAbs(filePath);
+    if (!absPath)
+        return;
+    const existing = pending.get(absPath);
+    if (!existing) {
+        pending.set(absPath, { additions: 0, deletions: 0, isWrite: false });
+        logger.debug("Tracked read", { path: absPath });
+    }
+}
+/**
+ * Record a file write. Marked as isWrite=true.
+ */
+export function trackWrite(filePath) {
+    const absPath = resolveAbs(filePath);
+    if (!absPath)
+        return;
+    const existing = pending.get(absPath);
+    if (existing) {
+        existing.isWrite = true;
+    }
+    else {
+        pending.set(absPath, { additions: 0, deletions: 0, isWrite: true });
+    }
+    logger.debug("Tracked write", { path: absPath });
+}
+/**
+ * Record an edit with line changes.
+ * If perFileResults is available, extract per-file diffs.
+ * Otherwise use the top-level diff for a single-file edit.
+ */
+export function trackEdit(details) {
+    if (details.perFileResults && details.perFileResults.length > 0) {
+        for (const result of details.perFileResults) {
+            if (result.isError)
+                continue;
+            const absPath = resolveAbs(result.path);
+            if (!absPath)
+                continue;
+            const lineChanges = result.diff ? countLineChanges(result.diff) : { additions: 0, deletions: 0 };
+            mergeChange(absPath, { ...lineChanges, isWrite: true });
+            logger.debug("Tracked edit (perFile)", { path: absPath, ...lineChanges });
+        }
+        return;
+    }
+    // ast_edit reports touched files + per-file replacement counts
+    if (details.files && details.files.length > 0) {
+        for (const filePath of details.files) {
+            const absPath = resolveAbs(filePath);
+            if (!absPath)
+                continue;
+            const count = details.fileReplacements?.find(r => r.path === filePath)?.count ?? 1;
+            mergeChange(absPath, { additions: count, deletions: 0, isWrite: true });
+            logger.debug("Tracked ast_edit", { path: absPath, count });
+        }
+        return;
+    }
+    // Single-file edit with top-level diff
+    const filePath = details.path;
+    if (!filePath) {
+        logger.debug("Skipped edit: no path in details");
+        return;
+    }
+    const absPath = resolveAbs(filePath);
+    if (!absPath)
+        return;
+    const lineChanges = details.diff ? countLineChanges(details.diff) : { additions: 1, deletions: 0 };
+    mergeChange(absPath, { ...lineChanges, isWrite: true });
+    logger.debug("Tracked edit (single)", { path: absPath, ...lineChanges });
+}
+/**
+ * Flush all pending file changes into heartbeat payloads.
+ * Clears the pending map after extraction.
+ */
+export function flushPending(projectFolder) {
+    if (pending.size === 0)
+        return [];
+    const payloads = [];
+    for (const [entity, change] of pending) {
+        payloads.push({
+            entity,
+            projectFolder,
+            isWrite: change.isWrite,
+            aiLineChanges: change.additions - change.deletions,
+        });
+    }
+    pending.clear();
+    logger.debug("Flushed pending heartbeats", { count: payloads.length });
+    return payloads;
+}
+/**
+ * Get the number of pending file changes (for debugging/force-flush).
+ */
+export function pendingCount() {
+    return pending.size;
+}
+// --- internal helpers ---
+function resolveAbs(filePath) {
+    if (!filePath)
+        return null;
+    // Already absolute
+    if (path.isAbsolute(filePath))
+        return filePath;
+    // Resolve relative to cwd — but we don't know cwd here.
+    // The extension context provides cwd; we'll resolve in the entry point.
+    // For now, just return as-is; the caller should pass absolute paths.
+    return filePath;
+}
+/**
+ * Resolve a possibly-relative path against a base directory.
+ */
+export function resolvePath(base, filePath) {
+    if (path.isAbsolute(filePath))
+        return filePath;
+    return path.resolve(base, filePath);
+}
+function mergeChange(absPath, change) {
+    const existing = pending.get(absPath);
+    if (existing) {
+        existing.additions += change.additions;
+        existing.deletions += change.deletions;
+        if (change.isWrite)
+            existing.isWrite = true;
+    }
+    else {
+        pending.set(absPath, { ...change });
+    }
+}
+/**
+ * Count additions and deletions from a unified diff string.
+ * Lines starting with '+' (after the diff header) are additions.
+ * Lines starting with '-' are deletions.
+ * Ignore the '+++' and '---' header lines.
+ */
+function countLineChanges(diff) {
+    let additions = 0;
+    let deletions = 0;
+    const lines = diff.split("\n");
+    for (const line of lines) {
+        if (line.startsWith("+++ ") || line.startsWith("--- "))
+            continue;
+        if (line.startsWith("+"))
+            additions++;
+        else if (line.startsWith("-"))
+            deletions++;
+    }
+    return { additions, deletions };
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@chronova/pi-plugin",
+  "version": "1.0.0",
+  "description": "Chronova heartbeat tracking extension for oh-my-pi — sends coding activity to your Chronova dashboard via chronova-cli",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "private": false,
+  "omp": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "type-check": "tsc --noEmit",
+    "semantic-release": "semantic-release"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "chronova",
+    "oh-my-pi",
+    "omp",
+    "pi-plugin",
+    "wakatime",
+    "heartbeat",
+    "coding-analytics",
+    "developer-analytics",
+    "ai-coding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nx-solutions-ug/chronova-pi-plugin.git"
+  },
+  "homepage": "https://github.com/nx-solutions-ug/chronova-pi-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/nx-solutions-ug/chronova-pi-plugin/issues"
+  },
+  "devDependencies": {
+    "@oh-my-pi/pi-coding-agent": "^15.1.8",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.3",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "semantic-release": "^24.2.3",
+    "typescript": "^5.9.0"
+  }
+}