daily-focus 0.1.0

package/schema/items.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/watson/daily-focus/schema/items.schema.json",
+  "title": "Daily Focus brief",
+  "description": "The payload the briefing agent writes to items.json. The morning briefing prompt covers rules a schema can't express, including stable ids across runs.",
+  "type": "object",
+  "required": ["version", "generatedAt", "items"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the run that produced this file."
+    },
+    "generatedBy": {
+      "type": "string",
+      "description": "Free-form label naming whichever agent produced this brief. The dashboard shows it, and does not care which agent it is."
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "The local date this brief is for."
+    },
+    "headline": {
+      "type": "string",
+      "description": "One or two sentences at the top of the page. Inline Markdown: **bold**, `code`, [text](url)."
+    },
+    "dayStart": {
+      "type": "string",
+      "pattern": "^\\d{2}:\\d{2}$",
+      "description": "Local time today's working day starts, derived from the calendar. Overrides the dashboard default."
+    },
+    "dayEnd": {
+      "type": "string",
+      "pattern": "^\\d{2}:\\d{2}$",
+      "description": "Local time today's working day ends. Set this when the day is short — free windows and remaining focus time are computed from it."
+    },
+    "items": { "type": "array", "items": { "$ref": "#/$defs/item" } }
+  },
+  "$defs": {
+    "item": {
+      "type": "object",
+      "required": ["id", "title", "source", "kind"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable across runs — actions are keyed on this. Derive it from upstream identity, never from the title or the date. e.g. \"github:pr:acme/webapp#3421\".",
+          "examples": ["github:pr:acme/webapp#3421", "email:thread:18f2a9c4b7", "jira:PROJ-8842"]
+        },
+        "title": { "type": "string", "minLength": 1 },
+        "source": {
+          "enum": ["github", "email", "calendar", "jira", "slack", "workday", "tasks", "atlassian", "reminders", "messages", "eboks", "other"],
+          "description": "Aliases such as gmail, gh, google-tasks, confluence, imessage and e-boks are normalised by the dashboard."
+        },
+        "kind": {
+          "enum": ["task", "event", "info"],
+          "description": "task = completable; event = goes on the agenda; info = context only."
+        },
+        "detail": {
+          "type": "string",
+          "description": "A sentence or two of context. Inline Markdown supported."
+        },
+        "url": {
+          "type": "string",
+          "pattern": "^https?://",
+          "description": "Deep link. Non-http(s) URLs are dropped."
+        },
+        "priority": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Lifts the item into the Top priorities band. Use for at most three items."
+        },
+        "due": { "type": "string", "description": "ISO date or timestamp." },
+        "start": {
+          "type": "string",
+          "description": "Events only. A bare YYYY-MM-DD means all-day."
+        },
+        "end": { "type": "string", "description": "Events only." },
+        "blocking": {
+          "type": "boolean",
+          "description": "Events only. False when the event belongs on the agenda but must not consume time \u2014 a delivery window, a booking, anything you are not sat inside. Absent means blocking; only an explicit false frees the slot."
+        },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "people": { "type": "array", "items": { "type": "string" } },
+        "firstSeen": {
+          "type": "string",
+          "description": "ISO date this item was FIRST raised. Carry it forward across runs so the dashboard can age it."
+        },
+        "advancesObjective": {
+          "type": "boolean",
+          "description": "True only when completing this genuinely moves the objective in focus.md forward. Drives the \"days since objective progress\" metric, so a generous reading makes that number lie."
+        }
+      }
+    }
+  }
+}

package/tools/dfcal/Info.plist

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleExecutable</key><string>dfcal</string>
+  <key>CFBundleIdentifier</key><string>com.daily-focus.dfcal</string>
+  <key>CFBundleName</key><string>Daily Focus Calendar</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>LSUIElement</key><true/>
+  <key>NSCalendarsFullAccessUsageDescription</key>
+  <string>Daily Focus reads today's events to show your agenda and work out your free time.</string>
+  <key>NSCalendarsUsageDescription</key>
+  <string>Daily Focus reads today's events to show your agenda and work out your free time.</string>
+</dict>
+</plist>

package/tools/dfcal/build.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+# Builds the calendar helper as a .app bundle.
+#
+#   sh tools/dfcal/build.sh                # into tools/dfcal/build/, for this Mac
+#   sh tools/dfcal/build.sh --app OUT_DIR  # into OUT_DIR/, for the menu bar app
+#
+# A bundle rather than a plain binary, and this is not stylistic. macOS attributes
+# a calendar-access request to the *responsible process*, so a bare CLI spawned by
+# the server inherits whatever launched the server — a terminal, an editor, launchd —
+# and is refused outright when that process carries no calendar usage description.
+# The refusal is silent: the request returns false with no error and the
+# authorisation status never leaves "not determined". Running the Mach-O inside a
+# bundle directly fails the same way; only launching it *as an app* gives it an
+# identity of its own. Hence `open`, and hence the plist.
+#
+# `--app` builds for the Macs the menu bar app supports, Apple silicon on macOS 13.5
+# and later, because the copy inside the app goes to other Macs. The default stays
+# a build for this Mac, which is all a checkout needs.
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+
+for_app=no
+if [ "${1:-}" = "--app" ]; then
+  for_app=yes
+  shift
+fi
+out=${1:-"$here/build"}
+
+[ "$(uname -s)" = "Darwin" ] || { echo "dfcal is macOS-only; nothing to build" >&2; exit 0; }
+command -v swiftc >/dev/null 2>&1 || { echo "swiftc not found — install the Xcode command line tools" >&2; exit 1; }
+
+mkdir -p "$out"
+app="$(cd "$out" && pwd)/Daily Focus Calendar.app"
+
+rm -rf "$app"
+mkdir -p "$app/Contents/MacOS"
+cp "$here/Info.plist" "$app/Contents/Info.plist"
+if [ "$for_app" = yes ]; then
+  swiftc -O -target arm64-apple-macos13.5 "$here/main.swift" -o "$app/Contents/MacOS/dfcal"
+else
+  swiftc -O "$here/main.swift" -o "$app/Contents/MacOS/dfcal"
+fi
+
+# Ad-hoc signing is enough for TCC to keep a grant against this bundle id, but the
+# grant is keyed to the code as well: rebuilding changes the hash, and macOS may
+# ask again. That is a prompt nobody is watching when the server runs headless, so
+# a rebuild is worth doing while you are at the keyboard. The menu bar app signs
+# its copy again, with its own identity.
+codesign --force --sign - "$app" >/dev/null
+
+echo "built $app"

package/tools/dfcal/main.swift

@@ -0,0 +1,133 @@
+// dfcal — dumps today's calendar facts as JSON, for the dashboard's agenda.
+//
+// Deliberately thin. Everything that can be decided without EventKit — which
+// calendars count, which duplicates to fold, what a declined invitation means —
+// is decided in src/calendar.ts, where it can be tested without a real calendar.
+// What lives here is only what cannot: the framework call, and the reduction of
+// attendees to a single self-status so that no colleague's address is ever
+// written to disk.
+//
+// Usage: dfcal <output.json> [self@example.com,other@example.com]
+//
+// Always exits 0 after writing the output file, including on refusal. A caller
+// reading "denied" from the file can say so; a caller seeing no file at all
+// cannot tell refusal from a crash.
+
+import EventKit
+import Foundation
+
+let args = CommandLine.arguments
+guard args.count > 1 else {
+    FileHandle.standardError.write("usage: dfcal <output.json> [self-addresses]\n".data(using: .utf8)!)
+    exit(64)
+}
+let outPath = args[1]
+let selfAddresses = Set(
+    (args.count > 2 ? args[2] : "")
+        .split(separator: ",")
+        .map { $0.trimmingCharacters(in: .whitespaces).lowercased() }
+        .filter { !$0.isEmpty }
+)
+
+func isoString(_ date: Date?) -> Any {
+    guard let date else { return NSNull() }
+    let f = ISO8601DateFormatter()
+    f.formatOptions = [.withInternetDateTime]
+    f.timeZone = TimeZone.current
+    return f.string(from: date)
+}
+
+func write(_ payload: [String: Any]) -> Never {
+    guard let data = try? JSONSerialization.data(withJSONObject: payload, options: [.sortedKeys]) else {
+        exit(70)
+    }
+    // Sibling temp then rename, so a reader never sees half a file.
+    let tmp = outPath + ".tmp"
+    do {
+        try data.write(to: URL(fileURLWithPath: tmp))
+        _ = try FileManager.default.replaceItemAt(URL(fileURLWithPath: outPath), withItemAt: URL(fileURLWithPath: tmp))
+    } catch {
+        try? data.write(to: URL(fileURLWithPath: outPath))
+    }
+    exit(0)
+}
+
+let store = EKEventStore()
+let gate = DispatchSemaphore(value: 0)
+var granted = false
+var failure: String?
+
+let answered: (Bool, Error?) -> Void = { ok, err in
+    granted = ok
+    if let err { failure = String(describing: err) }
+    gate.signal()
+}
+// Full access is how macOS 14 and later ask. The menu bar app carries this helper
+// down to macOS 13, where the older request is the only one there is.
+if #available(macOS 14.0, *) {
+    store.requestFullAccessToEvents(completion: answered)
+} else {
+    store.requestAccess(to: .event, completion: answered)
+}
+
+// Long enough for a person to answer the TCC prompt the first time, bounded so a
+// launcher that can never show one doesn't hang the poller forever.
+if gate.wait(timeout: .now() + 120) == .timedOut {
+    write(["error": "timeout", "detail": "no answer to the calendar access prompt"])
+}
+guard granted else {
+    write([
+        "error": "denied",
+        "detail": failure ?? "macOS refused calendar access to this binary",
+        "status": EKEventStore.authorizationStatus(for: .event).rawValue,
+    ])
+}
+
+/// The user's own response to an invitation, or nil when it can't be established.
+///
+/// `isCurrentUser` is not usable here: on a Google account synced through
+/// Calendar.app it is false for every attendee of every event, so the only
+/// reliable route is matching the address the caller told us about.
+func selfStatus(_ event: EKEvent) -> Int? {
+    guard let attendees = event.attendees, !attendees.isEmpty else { return nil }
+    for attendee in attendees {
+        let mail = attendee.url.absoluteString
+            .replacingOccurrences(of: "mailto:", with: "", options: .caseInsensitive)
+            .lowercased()
+        if selfAddresses.contains(mail) { return attendee.participantStatus.rawValue }
+    }
+    return nil
+}
+
+let calendars = store.calendars(for: .event).map { calendar -> [String: Any] in
+    [
+        "id": calendar.calendarIdentifier,
+        "title": calendar.title,
+        "source": calendar.source?.title ?? "",
+    ]
+}
+
+let cal = Calendar.current
+let dayStart = cal.startOfDay(for: Date())
+let dayEnd = cal.date(byAdding: .day, value: 1, to: dayStart) ?? dayStart
+let predicate = store.predicateForEvents(withStart: dayStart, end: dayEnd, calendars: nil)
+
+let events = store.events(matching: predicate).map { event -> [String: Any] in
+    var row: [String: Any] = [
+        // Series-level for a recurring event, so it is never unique on its own —
+        // src/calendar.ts pairs it with the start to identify one occurrence.
+        "externalId": event.calendarItemExternalIdentifier ?? event.calendarItemIdentifier,
+        "calendarId": event.calendar?.calendarIdentifier ?? "",
+        "title": event.title ?? "",
+        "start": isoString(event.startDate),
+        "end": isoString(event.endDate),
+        "allDay": event.isAllDay,
+        // EKEventAvailability: notSupported -1, busy 0, free 1, tentative 2, unavailable 3.
+        "availability": event.availability.rawValue,
+    ]
+    if let status = selfStatus(event) { row["selfStatus"] = status }
+    if let url = event.url?.absoluteString, !url.isEmpty { row["url"] = url }
+    return row
+}
+
+write(["generatedAt": isoString(Date()), "calendars": calendars, "events": events])