@fbdo/smart-agentic-calendar 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# Smart Agentic Calendar
+
+A local-first smart calendar MCP server for AI agents. Inspired by [Reclaim.ai](https://reclaim.ai/) and [Motion](https://www.usemotion.com/), it automatically re-plans tasks, recalculates the schedule, and helps AI agents act as personal scheduling assistants.
+
+## What It Does
+
+- **Time-blocking scheduler** that assigns specific time slots to tasks based on deadlines, durations, and priorities (P1-P4)
+- **Automatic replanning** triggered on any change (create, update, delete, complete) — runs in the background so tool responses are instant
+- **Constraint satisfaction** engine that respects hard constraints (deadlines, availability, events, dependencies) and optimizes soft constraints (priority, focus time, buffer time)
+- **Focus time protection** for deep work blocks with minimum uninterrupted duration enforcement
+- **Task splitting** across multiple time slots when no single slot fits
+- **Recurring tasks** with full RRULE support (daily, weekly, monthly, yearly, custom patterns)
+- **Task dependencies** with cycle detection
+- **Conflict detection** that identifies at-risk tasks and suggests deprioritizations
+- **Analytics** — completion rates, schedule health, estimation accuracy, time allocation by category
+
+## Architecture
+
+```
+src/
+  models/       Domain types (Task, Event, TimeBlock, Config, etc.)
+  common/       Shared utilities (ID generation, time functions, constants)
+  storage/      SQLite database layer (better-sqlite3)
+  engine/       Scheduling engine, replanning, conflict detection, recurrence
+  analytics/    Productivity stats, schedule health, estimation accuracy
+  mcp/          MCP server and tool handlers
+  index.ts      Composition root and entry point
+```
+
+Single-user, single-process, local-first. All data stored in a local SQLite database with no external service dependencies.
+
+## Tech Stack
+
+| Component | Choice |
+|-----------|--------|
+| Language | TypeScript (strict mode) |
+| Runtime | Node.js >= 20 |
+| Storage | SQLite via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) |
+| MCP Transport | stdio |
+| Test Runner | [Vitest](https://vitest.dev/) |
+| Scheduling | Constraint satisfaction algorithm |
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 20
+
+### Install and Build
+
+```bash
+npm install
+npm run build
+```
+
+This compiles TypeScript to `dist/` and produces the runnable server at `dist/index.js`.
+
+### Test
+
+```bash
+npm test              # run all tests (578 tests)
+npm run test:watch    # watch mode
+npm run test:coverage # with coverage
+```
+
+### Quality Checks
+
+```bash
+npm run lint          # eslint
+npm run format:check  # prettier
+npm run quality       # all checks (lint, format, duplication, unused code, dependency rules, security)
+```
+
+## Connecting to an MCP-Compatible Agent
+
+This server communicates over **stdio** using the [Model Context Protocol](https://modelcontextprotocol.io/). Any MCP-compatible client can connect to it by spawning the server as a subprocess.
+
+### Configuration
+
+The server accepts one environment variable:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CALENDAR_DB_PATH` | `./calendar.db` | Path to the SQLite database file |
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "smart-agentic-calendar": {
+      "command": "npx",
+      "args": ["-y", "smart-agentic-calendar"],
+      "env": {
+        "CALENDAR_DB_PATH": "/absolute/path/to/calendar.db"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+Add to your project's `.mcp.json` or global `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "smart-agentic-calendar": {
+      "command": "npx",
+      "args": ["-y", "smart-agentic-calendar"],
+      "env": {
+        "CALENDAR_DB_PATH": "/absolute/path/to/calendar.db"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "smart-agentic-calendar": {
+      "command": "npx",
+      "args": ["-y", "smart-agentic-calendar"],
+      "env": {
+        "CALENDAR_DB_PATH": "/absolute/path/to/calendar.db"
+      }
+    }
+  }
+}
+```
+
+### Any MCP Client (Generic)
+
+Spawn the server as a child process with stdio transport:
+
+```bash
+npx -y smart-agentic-calendar
+```
+
+Or with a custom database path:
+
+```bash
+CALENDAR_DB_PATH=/path/to/calendar.db npx -y smart-agentic-calendar
+```
+
+The server reads JSON-RPC messages from stdin and writes responses to stdout. Diagnostic messages go to stderr.
+
+## MCP Tools
+
+### Task Management
+- `create_task` — create a task with title, duration, deadline, priority, category, tags
+- `get_task` — retrieve a task by ID
+- `update_task` — update any task field (triggers background replan)
+- `delete_task` — soft-delete a task (triggers background replan)
+- `complete_task` — mark a task done, optionally record actual duration
+- `list_tasks` — query tasks with filters (status, priority, deadline range, category)
+
+### Event Management
+- `create_event` — create a fixed calendar event that blocks time
+- `update_event` — modify an event
+- `delete_event` — remove an event
+- `list_events` — query events by date range
+
+### Schedule & Conflicts
+- `get_schedule` — view scheduled time blocks for a date range (returns `schedule_status`: "up_to_date" or "replan_in_progress")
+- `replan` — force a synchronous replan (the only blocking replan path)
+- `get_conflicts` — view at-risk tasks and deadline conflicts
+
+### Analytics
+- `get_productivity_stats` — completion rates, on-time rates by period
+- `get_schedule_health` — composite health score, utilization, overdue/at-risk counts
+- `get_time_allocation` — hours breakdown by category
+- `get_estimation_accuracy` — estimated vs. actual duration analysis
+
+### Configuration
+- `set_availability` — define work hours per day of week
+- `set_focus_time` — define focus/deep-work blocks
+- `set_preferences` — buffer time, default priority, scheduling horizon, minimum block size
+- `get_preferences` — retrieve current configuration
+
+## Development
+
+This project follows **test-driven development** (red-green-refactor) with a healthy test pyramid and dependency injection for testability. Property-based tests are used for pure scheduling functions and serialization round-trips.
+
+## License
+
+MIT

package/dist/analytics/allocation.d.ts

@@ -0,0 +1,9 @@
+import type { AnalyticsRepository } from "../storage/analytics-repository.js";
+import type { TimeAllocation } from "../models/analytics.js";
+import type { Period } from "./period.js";
+export declare class AllocationCalculator {
+    private readonly analyticsRepo;
+    constructor(analyticsRepo: AnalyticsRepository);
+    compute(period: Period, referenceDate?: Date): TimeAllocation;
+}
+//# sourceMappingURL=allocation.d.ts.map

package/dist/analytics/allocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocation.d.ts","sourceRoot":"","sources":["../../src/analytics/allocation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAsB,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;gBAExC,aAAa,EAAE,mBAAmB;IAI9C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,cAAc;CAoB9D"}

package/dist/analytics/allocation.js

@@ -0,0 +1,27 @@
+import { resolvePeriod } from "./period.js";
+export class AllocationCalculator {
+    analyticsRepo;
+    constructor(analyticsRepo) {
+        this.analyticsRepo = analyticsRepo;
+    }
+    compute(period, referenceDate) {
+        const range = resolvePeriod(period, referenceDate);
+        const summaries = this.analyticsRepo.getTasksByCategory(range.start, range.end);
+        if (summaries.length === 0) {
+            return { period, categories: [] };
+        }
+        const totalMinutes = summaries.reduce((sum, s) => sum + s.totalMinutes, 0);
+        const categories = summaries
+            .map((s) => ({
+            category: s.category,
+            hours: round2(s.totalMinutes / 60),
+            percentage: totalMinutes === 0 ? 0 : round2((s.totalMinutes / totalMinutes) * 100),
+        }))
+            .sort((a, b) => b.hours - a.hours);
+        return { period, categories };
+    }
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=allocation.js.map

package/dist/analytics/allocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocation.js","sourceRoot":"","sources":["../../src/analytics/allocation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,oBAAoB;IACd,aAAa,CAAsB;IAEpD,YAAY,aAAkC;QAC5C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED,OAAO,CAAC,MAAc,EAAE,aAAoB;QAC1C,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QAEhF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QACpC,CAAC;QAED,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QAE3E,MAAM,UAAU,GAAyB,SAAS;aAC/C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,GAAG,EAAE,CAAC;YAClC,UAAU,EAAE,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,YAAY,CAAC,GAAG,GAAG,CAAC;SACnF,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAErC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAChC,CAAC;CACF;AAED,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC"}

package/dist/analytics/analytics-engine.d.ts

@@ -0,0 +1,17 @@
+import type { AnalyticsRepository } from "../storage/analytics-repository.js";
+import type { TaskRepository } from "../storage/task-repository.js";
+import type { ScheduleRepository } from "../storage/schedule-repository.js";
+import type { ConfigRepository } from "../storage/config-repository.js";
+import type { ProductivityStats, ScheduleHealth, EstimationAccuracy, TimeAllocation } from "../models/analytics.js";
+export declare class AnalyticsEngine {
+    private readonly productivity;
+    private readonly health;
+    private readonly estimation;
+    private readonly allocation;
+    constructor(analyticsRepo: AnalyticsRepository, taskRepo: TaskRepository, scheduleRepo: ScheduleRepository, configRepo: ConfigRepository);
+    getProductivityStats(period: string, referenceDate?: Date): ProductivityStats;
+    getScheduleHealth(referenceDate?: Date): ScheduleHealth;
+    getEstimationAccuracy(period: string, referenceDate?: Date): EstimationAccuracy;
+    getTimeAllocation(period: string, referenceDate?: Date): TimeAllocation;
+}
+//# sourceMappingURL=analytics-engine.d.ts.map

package/dist/analytics/analytics-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-engine.d.ts","sourceRoot":"","sources":["../../src/analytics/analytics-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACf,MAAM,wBAAwB,CAAC;AAOhC,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;gBAGhD,aAAa,EAAE,mBAAmB,EAClC,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,kBAAkB,EAChC,UAAU,EAAE,gBAAgB;IAQ9B,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,iBAAiB;IAK7E,iBAAiB,CAAC,aAAa,CAAC,EAAE,IAAI,GAAG,cAAc;IAIvD,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,kBAAkB;IAK/E,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,cAAc;CAIxE"}

package/dist/analytics/analytics-engine.js

@@ -0,0 +1,33 @@
+import { validatePeriod } from "./period.js";
+import { ProductivityCalculator } from "./productivity.js";
+import { HealthCalculator } from "./health.js";
+import { EstimationCalculator } from "./estimation.js";
+import { AllocationCalculator } from "./allocation.js";
+export class AnalyticsEngine {
+    productivity;
+    health;
+    estimation;
+    allocation;
+    constructor(analyticsRepo, taskRepo, scheduleRepo, configRepo) {
+        this.productivity = new ProductivityCalculator(analyticsRepo);
+        this.health = new HealthCalculator(analyticsRepo, taskRepo, scheduleRepo, configRepo);
+        this.estimation = new EstimationCalculator(analyticsRepo);
+        this.allocation = new AllocationCalculator(analyticsRepo);
+    }
+    getProductivityStats(period, referenceDate) {
+        validatePeriod(period);
+        return this.productivity.compute(period, referenceDate);
+    }
+    getScheduleHealth(referenceDate) {
+        return this.health.compute(referenceDate);
+    }
+    getEstimationAccuracy(period, referenceDate) {
+        validatePeriod(period);
+        return this.estimation.compute(period, referenceDate);
+    }
+    getTimeAllocation(period, referenceDate) {
+        validatePeriod(period);
+        return this.allocation.compute(period, referenceDate);
+    }
+}
+//# sourceMappingURL=analytics-engine.js.map

package/dist/analytics/analytics-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-engine.js","sourceRoot":"","sources":["../../src/analytics/analytics-engine.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,OAAO,eAAe;IACT,YAAY,CAAyB;IACrC,MAAM,CAAmB;IACzB,UAAU,CAAuB;IACjC,UAAU,CAAuB;IAElD,YACE,aAAkC,EAClC,QAAwB,EACxB,YAAgC,EAChC,UAA4B;QAE5B,IAAI,CAAC,YAAY,GAAG,IAAI,sBAAsB,CAAC,aAAa,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,GAAG,IAAI,gBAAgB,CAAC,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;QACtF,IAAI,CAAC,UAAU,GAAG,IAAI,oBAAoB,CAAC,aAAa,CAAC,CAAC;QAC1D,IAAI,CAAC,UAAU,GAAG,IAAI,oBAAoB,CAAC,aAAa,CAAC,CAAC;IAC5D,CAAC;IAED,oBAAoB,CAAC,MAAc,EAAE,aAAoB;QACvD,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1D,CAAC;IAED,iBAAiB,CAAC,aAAoB;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5C,CAAC;IAED,qBAAqB,CAAC,MAAc,EAAE,aAAoB;QACxD,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxD,CAAC;IAED,iBAAiB,CAAC,MAAc,EAAE,aAAoB;QACpD,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxD,CAAC;CACF"}

package/dist/analytics/estimation.d.ts

@@ -0,0 +1,9 @@
+import type { AnalyticsRepository } from "../storage/analytics-repository.js";
+import type { EstimationAccuracy } from "../models/analytics.js";
+import type { Period } from "./period.js";
+export declare class EstimationCalculator {
+    private readonly analyticsRepo;
+    constructor(analyticsRepo: AnalyticsRepository);
+    compute(period: Period, referenceDate?: Date): EstimationAccuracy;
+}
+//# sourceMappingURL=estimation.d.ts.map

package/dist/analytics/estimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimation.d.ts","sourceRoot":"","sources":["../../src/analytics/estimation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;gBAExC,aAAa,EAAE,mBAAmB;IAI9C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,kBAAkB;CAkDlE"}

package/dist/analytics/estimation.js

@@ -0,0 +1,74 @@
+import { resolvePeriod } from "./period.js";
+export class EstimationCalculator {
+    analyticsRepo;
+    constructor(analyticsRepo) {
+        this.analyticsRepo = analyticsRepo;
+    }
+    compute(period, referenceDate) {
+        const range = resolvePeriod(period, referenceDate);
+        const records = this.analyticsRepo.getDurationRecords(range.start, range.end);
+        if (records.length === 0) {
+            return {
+                averageAccuracyPercentage: null,
+                overestimateCount: 0,
+                underestimateCount: 0,
+                averageOverestimateMinutes: null,
+                averageUnderestimateMinutes: null,
+                accuracyByCategory: null,
+            };
+        }
+        const accuracies = records.map((r) => perTaskAccuracy(r.estimatedMinutes, r.actualMinutes));
+        const averageAccuracyPercentage = round2(accuracies.reduce((sum, a) => sum + a, 0) / accuracies.length);
+        const overestimates = records.filter((r) => r.actualMinutes < r.estimatedMinutes);
+        const underestimates = records.filter((r) => r.actualMinutes > r.estimatedMinutes);
+        const averageOverestimateMinutes = overestimates.length === 0
+            ? null
+            : round1(overestimates.reduce((sum, r) => sum + (r.estimatedMinutes - r.actualMinutes), 0) /
+                overestimates.length);
+        const averageUnderestimateMinutes = underestimates.length === 0
+            ? null
+            : round1(underestimates.reduce((sum, r) => sum + (r.actualMinutes - r.estimatedMinutes), 0) /
+                underestimates.length);
+        const accuracyByCategory = computeCategoryAccuracy(records);
+        return {
+            averageAccuracyPercentage,
+            overestimateCount: overestimates.length,
+            underestimateCount: underestimates.length,
+            averageOverestimateMinutes,
+            averageUnderestimateMinutes,
+            accuracyByCategory,
+        };
+    }
+}
+function perTaskAccuracy(estimated, actual) {
+    if (estimated === 0)
+        return 0;
+    const deviation = (Math.abs(actual - estimated) / estimated) * 100;
+    return Math.max(0, 100 - deviation);
+}
+function computeCategoryAccuracy(records) {
+    const groups = new Map();
+    for (const record of records) {
+        const category = record.category ?? "uncategorized";
+        const accuracy = perTaskAccuracy(record.estimatedMinutes, record.actualMinutes);
+        if (!groups.has(category)) {
+            groups.set(category, []);
+        }
+        const group = groups.get(category);
+        if (group) {
+            group.push(accuracy);
+        }
+    }
+    const result = {};
+    for (const [category, accuracies] of groups) {
+        result[category] = round2(accuracies.reduce((sum, a) => sum + a, 0) / accuracies.length);
+    }
+    return result;
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}
+//# sourceMappingURL=estimation.js.map

package/dist/analytics/estimation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimation.js","sourceRoot":"","sources":["../../src/analytics/estimation.ts"],"names":[],"mappings":"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"}

package/dist/analytics/health.d.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsRepository } from "../storage/analytics-repository.js";
+import type { TaskRepository } from "../storage/task-repository.js";
+import type { ScheduleRepository } from "../storage/schedule-repository.js";
+import type { ConfigRepository } from "../storage/config-repository.js";
+import type { ScheduleHealth } from "../models/analytics.js";
+export declare class HealthCalculator {
+    private readonly analyticsRepo;
+    private readonly taskRepo;
+    private readonly scheduleRepo;
+    private readonly configRepo;
+    constructor(analyticsRepo: AnalyticsRepository, taskRepo: TaskRepository, scheduleRepo: ScheduleRepository, configRepo: ConfigRepository);
+    compute(referenceDate?: Date): ScheduleHealth;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/analytics/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/analytics/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAe7D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;gBAG5C,aAAa,EAAE,mBAAmB,EAClC,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,kBAAkB,EAChC,UAAU,EAAE,gBAAgB;IAQ9B,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,GAAG,cAAc;CAyC9C"}

package/dist/analytics/health.js

@@ -0,0 +1,146 @@
+import { resolvePeriod } from "./period.js";
+import { diffMinutes } from "../common/time.js";
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const OVERDUE_WEIGHT = 15;
+const AT_RISK_WEIGHT = 10;
+const OVER_UTILIZATION_THRESHOLD = 90;
+const OVER_UTILIZATION_MULTIPLIER = 2;
+const UNDER_UTILIZATION_THRESHOLD = 20;
+const UNDER_UTILIZATION_MULTIPLIER = 1;
+export class HealthCalculator {
+    analyticsRepo;
+    taskRepo;
+    scheduleRepo;
+    configRepo;
+    constructor(analyticsRepo, taskRepo, scheduleRepo, configRepo) {
+        this.analyticsRepo = analyticsRepo;
+        this.taskRepo = taskRepo;
+        this.scheduleRepo = scheduleRepo;
+        this.configRepo = configRepo;
+    }
+    compute(referenceDate) {
+        const ref = referenceDate ?? new Date();
+        const weekRange = resolvePeriod("week", ref);
+        const config = this.configRepo.getFullConfig();
+        const timeBlocks = this.scheduleRepo.getSchedule(weekRange.start, weekRange.end);
+        const overdueTasks = this.analyticsRepo.getOverdueTasks(ref.toISOString());
+        const atRiskTasks = this.taskRepo.findAll({ status: "at_risk" });
+        const overdueCount = overdueTasks.length;
+        const atRiskCount = atRiskTasks.length;
+        const availablePerDay = computeAvailableMinutesPerDay(config.availability, weekRange.start);
+        const scheduledPerDay = computeScheduledMinutesPerDay(timeBlocks, weekRange.start);
+        const totalAvailable = sumValues(availablePerDay);
+        const totalScheduled = sumValues(scheduledPerDay);
+        const utilizationPercentage = totalAvailable === 0 ? 0 : round2((totalScheduled / totalAvailable) * 100);
+        const freeHoursThisWeek = totalAvailable === 0 ? 0 : round1(Math.max(0, (totalAvailable - totalScheduled) / 60));
+        const { busiestDay, lightestDay } = findBusiestLightestDay(scheduledPerDay, availablePerDay, weekRange.start);
+        const healthScore = computeHealthScore(overdueCount, atRiskCount, utilizationPercentage);
+        return {
+            healthScore,
+            utilizationPercentage,
+            overdueCount,
+            atRiskCount,
+            freeHoursThisWeek,
+            busiestDay,
+            lightestDay,
+        };
+    }
+}
+function computeHealthScore(overdueCount, atRiskCount, utilizationPercentage) {
+    let score = 100;
+    score -= overdueCount * OVERDUE_WEIGHT;
+    score -= atRiskCount * AT_RISK_WEIGHT;
+    if (utilizationPercentage > OVER_UTILIZATION_THRESHOLD) {
+        score -= (utilizationPercentage - OVER_UTILIZATION_THRESHOLD) * OVER_UTILIZATION_MULTIPLIER;
+    }
+    else if (utilizationPercentage < UNDER_UTILIZATION_THRESHOLD) {
+        score -= (UNDER_UTILIZATION_THRESHOLD - utilizationPercentage) * UNDER_UTILIZATION_MULTIPLIER;
+    }
+    return Math.round(Math.max(0, Math.min(100, score)));
+}
+function computeAvailableMinutesPerDay(availability, weekStart) {
+    const result = new Map();
+    const startDate = new Date(weekStart);
+    for (let dayOffset = 0; dayOffset < 7; dayOffset++) {
+        const date = new Date(startDate);
+        date.setUTCDate(date.getUTCDate() + dayOffset);
+        const dayOfWeek = date.getUTCDay(); // 0=Sun..6=Sat
+        let minutes = 0;
+        for (const window of availability.windows) {
+            if (window.day === dayOfWeek) {
+                const [startH, startM] = window.startTime.split(":").map(Number);
+                const [endH, endM] = window.endTime.split(":").map(Number);
+                minutes += endH * 60 + endM - (startH * 60 + startM);
+            }
+        }
+        result.set(dayOffset, minutes);
+    }
+    return result;
+}
+function computeScheduledMinutesPerDay(timeBlocks, weekStart) {
+    const result = new Map();
+    const startMs = new Date(weekStart).getTime();
+    for (const block of timeBlocks) {
+        const blockDate = new Date(block.startTime);
+        const dayOffset = Math.floor((blockDate.getTime() - startMs) / (24 * 60 * 60 * 1000));
+        if (dayOffset >= 0 && dayOffset < 7) {
+            const minutes = diffMinutes(block.startTime, block.endTime);
+            result.set(dayOffset, (result.get(dayOffset) ?? 0) + minutes);
+        }
+    }
+    return result;
+}
+function findBusiestLightestDay(scheduledPerDay, availablePerDay, weekStart) {
+    // Check if any time blocks exist
+    let hasScheduled = false;
+    for (const minutes of scheduledPerDay.values()) {
+        if (minutes > 0) {
+            hasScheduled = true;
+            break;
+        }
+    }
+    if (!hasScheduled) {
+        return { busiestDay: null, lightestDay: null };
+    }
+    const startDate = new Date(weekStart);
+    let busiestOffset = -1;
+    let busiestMinutes = -1;
+    let lightestOffset = -1;
+    let lightestMinutes = Infinity;
+    for (let dayOffset = 0; dayOffset < 7; dayOffset++) {
+        const scheduled = scheduledPerDay.get(dayOffset) ?? 0;
+        const available = availablePerDay.get(dayOffset) ?? 0;
+        // Busiest: any day with scheduled time
+        if (scheduled > busiestMinutes) {
+            busiestMinutes = scheduled;
+            busiestOffset = dayOffset;
+        }
+        // Lightest: only days with availability > 0
+        if (available > 0 && scheduled < lightestMinutes) {
+            lightestMinutes = scheduled;
+            lightestOffset = dayOffset;
+        }
+    }
+    const busiestDay = busiestOffset >= 0 ? getDayName(startDate, busiestOffset) : null;
+    const lightestDay = lightestOffset >= 0 ? getDayName(startDate, lightestOffset) : null;
+    return { busiestDay, lightestDay };
+}
+function getDayName(weekStart, dayOffset) {
+    const date = new Date(weekStart);
+    date.setUTCDate(date.getUTCDate() + dayOffset);
+    return DAY_NAMES[date.getUTCDay()];
+}
+function sumValues(map) {
+    let sum = 0;
+    for (const v of map.values()) {
+        sum += v;
+    }
+    return sum;
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+function round1(value) {
+    return Math.round(value * 10) / 10;
+}
+//# sourceMappingURL=health.js.map

package/dist/analytics/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/analytics/health.ts"],"names":[],"mappings":"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"}

package/dist/analytics/period.d.ts

@@ -0,0 +1,9 @@
+export type Period = "day" | "week" | "month";
+interface DateRange {
+    start: string;
+    end: string;
+}
+export declare function validatePeriod(period: string): asserts period is Period;
+export declare function resolvePeriod(period: Period, referenceDate?: Date): DateRange;
+export {};
+//# sourceMappingURL=period.d.ts.map

package/dist/analytics/period.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"period.d.ts","sourceRoot":"","sources":["../../src/analytics/period.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAIvE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,IAAI,GAAG,SAAS,CAW7E"}

package/dist/analytics/period.js

@@ -0,0 +1,41 @@
+import { ValidationError } from "../models/errors.js";
+const VALID_PERIODS = new Set(["day", "week", "month"]);
+export function validatePeriod(period) {
+    if (!VALID_PERIODS.has(period)) {
+        throw new ValidationError("invalid period: must be day, week, or month");
+    }
+}
+export function resolvePeriod(period, referenceDate) {
+    const ref = referenceDate ?? new Date();
+    switch (period) {
+        case "day":
+            return resolveDay(ref);
+        case "week":
+            return resolveWeek(ref);
+        case "month":
+            return resolveMonth(ref);
+    }
+}
+function resolveDay(ref) {
+    const start = new Date(Date.UTC(ref.getUTCFullYear(), ref.getUTCMonth(), ref.getUTCDate()));
+    const end = new Date(start);
+    end.setUTCDate(end.getUTCDate() + 1);
+    return { start: start.toISOString(), end: end.toISOString() };
+}
+function resolveWeek(ref) {
+    const start = new Date(Date.UTC(ref.getUTCFullYear(), ref.getUTCMonth(), ref.getUTCDate()));
+    // getUTCDay(): 0=Sunday, 1=Monday, ..., 6=Saturday
+    // We want Monday as start of week
+    const dayOfWeek = start.getUTCDay();
+    const daysFromMonday = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+    start.setUTCDate(start.getUTCDate() - daysFromMonday);
+    const end = new Date(start);
+    end.setUTCDate(end.getUTCDate() + 7);
+    return { start: start.toISOString(), end: end.toISOString() };
+}
+function resolveMonth(ref) {
+    const start = new Date(Date.UTC(ref.getUTCFullYear(), ref.getUTCMonth(), 1));
+    const end = new Date(Date.UTC(ref.getUTCFullYear(), ref.getUTCMonth() + 1, 1));
+    return { start: start.toISOString(), end: end.toISOString() };
+}
+//# sourceMappingURL=period.js.map

package/dist/analytics/period.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"period.js","sourceRoot":"","sources":["../../src/analytics/period.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAStD,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7E,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,eAAe,CAAC,6CAA6C,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,aAAoB;IAChE,MAAM,GAAG,GAAG,aAAa,IAAI,IAAI,IAAI,EAAE,CAAC;IAExC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK;YACR,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,KAAK,MAAM;YACT,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,GAAS;IAC3B,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC5F,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;AAChE,CAAC;AAED,SAAS,WAAW,CAAC,GAAS;IAC5B,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC5F,mDAAmD;IACnD,kCAAkC;IAClC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;IACpC,MAAM,cAAc,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3D,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,cAAc,CAAC,CAAC;IAEtD,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5B,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;AAChE,CAAC;AAED,SAAS,YAAY,CAAC,GAAS;IAC7B,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;AAChE,CAAC"}

package/dist/analytics/productivity.d.ts

@@ -0,0 +1,9 @@
+import type { AnalyticsRepository } from "../storage/analytics-repository.js";
+import type { ProductivityStats } from "../models/analytics.js";
+import type { Period } from "./period.js";
+export declare class ProductivityCalculator {
+    private readonly analyticsRepo;
+    constructor(analyticsRepo: AnalyticsRepository);
+    compute(period: Period, referenceDate?: Date): ProductivityStats;
+}
+//# sourceMappingURL=productivity.d.ts.map