dayhand 0.0.0-stage → 0.14.0

package/backend/convex/lib/env.ts

@@ -0,0 +1,19 @@
+// The deployment's DAYHAND_* environment variables. Deployments set up before
+// the rename to Dayhand have them as HELM_*: those are still read, with one
+// warning per variable in the deployment's logs, until DAYHAND_* is set
+// (docs/deploy.md#renamed-variables).
+
+const warned = new Set<string>();
+
+/** DAYHAND_<name>, else the deprecated HELM_<name>; empty values count as unset. */
+export function serverEnv(name: string): string | undefined {
+  const value = process.env[`DAYHAND_${name}`];
+  if (value) return value;
+  const old = process.env[`HELM_${name}`];
+  if (!old) return undefined;
+  if (!warned.has(name)) {
+    warned.add(name);
+    console.warn(`HELM_${name} is deprecated; set DAYHAND_${name} to the same value (docs/deploy.md#renamed-variables)`);
+  }
+  return old;
+}

package/backend/convex/lib/exportPlan.ts

@@ -0,0 +1,98 @@
+// Export of the whole plan: Markdown to read, JSON as a full copy, iCalendar
+// (lib/ical.ts) for a calendar app.
+import type { ObjectType } from "convex/values";
+import type { Doc } from "../_generated/dataModel";
+import type { QueryCtx } from "../_generated/server";
+import type { args } from "./args";
+import { loadSettings, toTask, type Identity } from "./core";
+import { isOverdue, localDate } from "./dates";
+import { renderCalendar } from "./ical";
+import { toRRule } from "./rrule";
+import type { Reminder } from "./validators";
+
+export const EXPORT_VERSION = 1;
+
+function taskLine(task: Doc<"tasks">, timezone: string): string {
+  const box = task.status === "done" ? "[x]" : "[ ]";
+  const when = [task.dueDate, task.dueTime].filter(Boolean).join(" ");
+  const parts = [`- ${box}`, when, task.title].filter(Boolean);
+  if (task.status === "doing") parts.push("(in progress)");
+  if (task.completedAt) parts.push(`(done ${localDate(task.completedAt, timezone)})`);
+  if (task.repeat) {
+    const from = task.repeat.from === "completion" ? ", counted from completion" : "";
+    parts.push(`(repeats ${toRRule(task.repeat, task.dueDate)}${from})`);
+  }
+  parts.push(...task.labels.map((label) => `#${label.replace(/\s+/g, "-")}`));
+  const lines = [parts.join(" ")];
+  if (task.resumeNote) lines.push(`  - Next step: ${task.resumeNote}`);
+  for (const item of task.checklist ?? []) lines.push(`  - ${item.done ? "[x]" : "[ ]"} ${item.title}`);
+  if (task.reminders) lines.push(`  - Reminders: ${task.reminders.length ? task.reminders.map(reminderText).join(", ") : "none"}`);
+  if (task.note) lines.push(...task.note.split("\n").map((line) => `  > ${line}`));
+  for (const link of task.links) lines.push(`  - [${link.title ?? link.url}](${link.url})`);
+  return lines.join("\n");
+}
+
+function reminderText(reminder: Reminder): string {
+  if ("minutesBefore" in reminder) return reminder.minutesBefore === 0 ? "at the due time" : `${reminder.minutesBefore} min before`;
+  const days = reminder.daysBefore ?? 0;
+  return days === 0 ? `${reminder.time} on the day` : `${reminder.time}, ${days} day${days === 1 ? "" : "s"} before`;
+}
+
+function section(title: string, tasks: Doc<"tasks">[], timezone: string): string[] {
+  if (tasks.length === 0) return [];
+  return [`## ${title}`, "", ...tasks.map((t) => taskLine(t, timezone)), ""];
+}
+
+function byDue(a: Doc<"tasks">, b: Doc<"tasks">) {
+  const key = (t: Doc<"tasks">) => `${t.dueDate ?? "9999-99-99"} ${t.dueTime ?? "99:99"}`;
+  return key(a).localeCompare(key(b)) || a.createdAt - b.createdAt;
+}
+
+export function renderMarkdown(tasks: Doc<"tasks">[], timezone: string, at: number): string {
+  const today = localDate(at, timezone);
+  const live = tasks.filter((t) => t.deletedAt === undefined).sort(byDue);
+  const active = live.filter((t) => t.archivedAt === undefined);
+  const open = active.filter((t) => t.status !== "done");
+  return [
+    `# Dayhand plan`,
+    "",
+    `Exported ${new Date(at).toISOString()} (today is ${today}, ${timezone}).`,
+    "",
+    ...section("Now", open.filter((t) => t.isNow), timezone),
+    ...section("Overdue", open.filter((t) => isOverdue(t, today)), timezone),
+    ...section(`Today (${today})`, open.filter((t) => t.dueDate === today), timezone),
+    ...section("Upcoming", open.filter((t) => t.dueDate !== undefined && t.dueDate > today), timezone),
+    ...section("No date", open.filter((t) => t.dueDate === undefined), timezone),
+    ...section("Done", active.filter((t) => t.status === "done"), timezone),
+    ...section("Archived", live.filter((t) => t.archivedAt !== undefined), timezone),
+  ].join("\n");
+}
+
+export async function exportPlan(ctx: QueryCtx, identity: Identity, input: Args) {
+  const at = input.at ?? Date.now();
+  const settings = await loadSettings(ctx, identity.userId);
+  const tasks = await ctx.db
+    .query("tasks")
+    .withIndex("by_user", (q) => q.eq("userId", identity.userId))
+    .collect();
+  if (input.format === "markdown") {
+    return { format: "markdown" as const, content: renderMarkdown(tasks, settings.timezone, at) };
+  }
+  if (input.format === "ics") return { format: "ics" as const, content: renderCalendar(tasks, { ...settings, at }) };
+  const events = await ctx.db
+    .query("taskEvents")
+    .withIndex("by_user", (q) => q.eq("userId", identity.userId))
+    .collect();
+  return {
+    format: "json" as const,
+    content: {
+      version: EXPORT_VERSION,
+      exportedAt: at,
+      settings,
+      tasks: tasks.map(toTask),
+      events: events.map(({ _id, _creationTime, userId, ...event }) => event),
+    },
+  };
+}
+
+type Args = ObjectType<(typeof args)["exportPlan"]>;

package/backend/convex/lib/findTasks.ts

@@ -0,0 +1,119 @@
+// list_all through MCP: search, filters and pages over the user's tasks.
+// Without `limit` every match is returned, as list_all did before 0.4.0.
+import type { ObjectType } from "convex/values";
+import type { Doc } from "../_generated/dataModel";
+import type { QueryCtx } from "../_generated/server";
+import type { args } from "./args";
+import { isReady } from "./agentWork";
+import { fail, loadSettings, toTask, type Identity } from "./core";
+import { isOverdue, localDate, resolveDate } from "./dates";
+
+type Args = ObjectType<(typeof args)["findTasks"]>;
+
+export const MAX_PAGE = 200;
+const MAX_QUERY = 200;
+
+// Sort key: due day (undated first), timed before untimed, time, creation, id.
+// The cursor is the key of the last task of a page, so pages stay stable
+// when tasks are added or removed between calls.
+type SortKey = [string, number, string, number, string];
+
+const sortKey = (t: Doc<"tasks">): SortKey => [t.dueDate ?? "", t.dueTime ? 0 : 1, t.dueTime ?? "", t.createdAt, t._id];
+
+function compareKeys(a: SortKey, b: SortKey): number {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i]! < b[i]!) return -1;
+    if (a[i]! > b[i]!) return 1;
+  }
+  return 0;
+}
+
+function encodeCursor(key: SortKey): string {
+  return btoa(JSON.stringify(key)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function decodeCursor(cursor: string): SortKey {
+  try {
+    const key = JSON.parse(atob(cursor.replace(/-/g, "+").replace(/_/g, "/")));
+    const types = ["string", "number", "string", "number", "string"];
+    if (Array.isArray(key) && key.length === types.length && key.every((part, i) => typeof part === types[i])) {
+      return key as SortKey;
+    }
+  } catch {
+    // reported below
+  }
+  return fail("invalid_argument", "cursor is not valid; start again without it");
+}
+
+function checkLimit(limit: number | undefined): number | undefined {
+  if (limit === undefined) return undefined;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE) {
+    fail("invalid_argument", `limit must be a whole number from 1 to ${MAX_PAGE}`);
+  }
+  return limit;
+}
+
+function checkDay(field: "dueBefore" | "dueAfter", value: string | undefined, today: string): string | undefined {
+  if (value === undefined) return undefined;
+  const day = resolveDate(value, today);
+  if (!day) fail("invalid_argument", `${field} must be YYYY-MM-DD, "today" or "tomorrow", got "${value}"`);
+  return day;
+}
+
+function checkQuery(query: string | undefined): string | undefined {
+  if (query === undefined) return undefined;
+  if (query.length > MAX_QUERY) fail("invalid_argument", `query is longer than ${MAX_QUERY} characters`);
+  const needle = query.trim().toLowerCase();
+  return needle === "" ? undefined : needle;
+}
+
+/**
+ * A predicate for the filters; `status`, when given, decides alone whether done
+ * tasks count. `ready` looks the dependencies up among the user's tasks.
+ */
+function matcher(input: Args, today: string, byId: Map<string, Doc<"tasks">>) {
+  const wanted = (input.labels ?? []).map((l) => l.trim()).filter((l) => l !== "");
+  const needle = checkQuery(input.query);
+  const before = checkDay("dueBefore", input.dueBefore, today);
+  const after = checkDay("dueAfter", input.dueAfter, today);
+  const statuses = input.status;
+  // Proposals (since 0.11.0) wait in the inbox: only `proposed: true` lists them.
+  const proposed = input.proposed ?? false;
+  return (t: Doc<"tasks">) =>
+    t.deletedAt === undefined &&
+    (t.proposedAt !== undefined) === proposed &&
+    (input.includeArchived || t.archivedAt === undefined) &&
+    (statuses ? statuses.includes(t.status) : input.includeDone !== false || t.status !== "done") &&
+    wanted.every((label) => t.labels.includes(label)) &&
+    (input.overdue === undefined || isOverdue(t, today) === input.overdue) &&
+    (input.ready === undefined || isReady(t, byId) === input.ready) &&
+    (before === undefined || (t.dueDate !== undefined && t.dueDate < before)) &&
+    (after === undefined || (t.dueDate !== undefined && t.dueDate > after)) &&
+    (needle === undefined ||
+      [t.title, t.note, t.resumeNote, ...t.labels].some((text) => text?.toLowerCase().includes(needle)));
+}
+
+/** One page of matching tasks, oldest due first; `total` counts every match. */
+export async function findTasks(ctx: QueryCtx, identity: Identity, input: Args) {
+  const at = input.at ?? Date.now();
+  const today = localDate(at, (await loadSettings(ctx, identity.userId)).timezone);
+  const limit = checkLimit(input.limit);
+  const after = input.cursor === undefined ? undefined : decodeCursor(input.cursor);
+  const tasks = await ctx.db
+    .query("tasks")
+    .withIndex("by_user", (q) => q.eq("userId", identity.userId))
+    .collect();
+  const matches = matcher(input, today, new Map(tasks.map((t) => [t._id as string, t])));
+  const found = tasks
+    .filter(matches)
+    .map((t) => ({ task: t, key: sortKey(t) }))
+    .sort((a, b) => compareKeys(a.key, b.key));
+  const rest = after === undefined ? found : found.filter((f) => compareKeys(f.key, after) > 0);
+  const page = limit === undefined ? rest : rest.slice(0, limit);
+  const more = page.length < rest.length;
+  return {
+    result: page.map(({ task }) => ({ ...toTask(task), overdue: isOverdue(task, today) })),
+    nextCursor: more ? encodeCursor(page[page.length - 1]!.key) : null,
+    total: found.length,
+  };
+}

package/backend/convex/lib/frontmatter.ts

@@ -0,0 +1,165 @@
+// The YAML header of a Markdown file ("frontmatter", between two "---" lines),
+// as Backlog.md task files use it (docs/backlog-md.md): keys with plain or
+// quoted scalars, flow lists ([a, "b"]) and block lists ("- a"), and block
+// text (| and >). Not a full YAML reader: nested maps, anchors and tags are
+// not part of that header and are read as text. Pure functions.
+
+export type FrontValue = string | string[] | null;
+export type Front = Record<string, FrontValue>;
+
+export class FrontmatterError extends Error {}
+
+const KEY = /^([A-Za-z_][\w.-]*)\s*:(?:\s+(.*))?$/;
+const LIST_ITEM = /^\s*-(?:\s+(.*))?$/;
+
+/** The header and the text after it; a file without a header has `front` null. */
+export function splitFrontmatter(content: string): { front: string | null; body: string } {
+  const text = content.replace(/^/, "").replace(/\r\n?/g, "\n");
+  if (!text.startsWith("---\n")) return { front: null, body: text };
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) throw new FrontmatterError("The YAML header has no closing --- line");
+  const after = text.indexOf("\n", end + 4);
+  return { front: text.slice(4, end + 1), body: after === -1 ? "" : text.slice(after + 1) };
+}
+
+/** Removes a trailing comment (" # …") outside quotes. */
+function stripComment(value: string): string {
+  let quote: string | null = null;
+  for (let i = 0; i < value.length; i++) {
+    const c = value[i]!;
+    if (quote) {
+      if (quote === "'" && c === "'" && value[i + 1] === "'") i++;
+      else if (quote === '"' && c === "\\") i++;
+      else if (c === quote) quote = null;
+    } else if (c === '"' || c === "'") {
+      if (i === 0 || /[\s,[]/.test(value[i - 1]!)) quote = c;
+    } else if (c === "#" && (i === 0 || /\s/.test(value[i - 1]!))) {
+      return value.slice(0, i).trimEnd();
+    }
+  }
+  return value.trimEnd();
+}
+
+const ESCAPES: Record<string, string> = { n: "\n", t: "\t", r: "\r", '"': '"', "\\": "\\", "/": "/", "0": "\0" };
+
+/** One scalar: quoted ('it''s', "a \"b\"") or plain; ~ and null are no value. */
+function scalar(raw: string): string | null {
+  const value = raw.trim();
+  if (value === "" || value === "~" || value === "null" || value === "Null" || value === "NULL") return null;
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) return value.slice(1, -1).replace(/''/g, "'");
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return value.slice(1, -1).replace(/\\(u[0-9a-fA-F]{4}|.)/g, (_, e: string) => (e.length === 5 ? String.fromCharCode(parseInt(e.slice(1), 16)) : (ESCAPES[e] ?? e)));
+  }
+  return value;
+}
+
+/** The items of a flow list "[a, 'b, c', \"d\"]". */
+function flowList(raw: string): string[] {
+  const inner = raw.trim().slice(1, -1);
+  const items: string[] = [];
+  let current = "";
+  let quote: string | null = null;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i]!;
+    if (quote) {
+      current += c;
+      if (c === quote) {
+        if (quote === "'" && inner[i + 1] === "'") current += inner[++i];
+        else quote = null;
+      } else if (quote === '"' && c === "\\" && i + 1 < inner.length) {
+        current += inner[++i];
+      }
+    } else if ((c === "'" || c === '"') && current.trim() === "") {
+      quote = c;
+      current += c;
+    } else if (c === ",") {
+      items.push(current);
+      current = "";
+    } else current += c;
+  }
+  if (current.trim() !== "" || items.length > 0) items.push(current);
+  return items.map(scalar).filter((item): item is string => item !== null);
+}
+
+const indentOf = (line: string) => line.length - line.trimStart().length;
+
+/** Block text after "key: |" or "key: >": the more indented lines that follow. */
+function blockText(lines: string[], start: number, folded: boolean): { value: string; next: number } {
+  let i = start;
+  const taken: string[] = [];
+  while (i < lines.length && (lines[i]!.trim() === "" || indentOf(lines[i]!) > 0)) taken.push(lines[i++]!);
+  while (taken.length && taken[taken.length - 1]!.trim() === "") taken.pop();
+  const indent = Math.min(...taken.filter((l) => l.trim() !== "").map(indentOf));
+  const body = taken.map((l) => l.slice(Number.isFinite(indent) ? indent : 0));
+  const value = folded ? body.join("\n").replace(/([^\n])\n(?=[^\n])/g, "$1 ") : body.join("\n");
+  return { value, next: i };
+}
+
+/** Reads the header's keys. A key given twice keeps its last value, as YAML readers do. */
+export function parseFrontmatter(front: string): Front {
+  const lines = front.split("\n");
+  const result: Front = {};
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i]!;
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      i++;
+      continue;
+    }
+    const match = indentOf(line) === 0 ? KEY.exec(line) : null;
+    if (!match) throw new FrontmatterError(`Line ${i + 1} of the YAML header is not "key: value": ${line.trim().slice(0, 80)}`);
+    const key = match[1]!;
+    const raw = stripComment(match[2] ?? "");
+    i++;
+    if (raw === "|" || raw === "|-" || raw === ">" || raw === ">-") {
+      const block = blockText(lines, i, raw.startsWith(">"));
+      result[key] = block.value;
+      i = block.next;
+    } else if (raw.startsWith("[") && raw.endsWith("]")) {
+      result[key] = flowList(raw);
+    } else if (raw === "") {
+      // A block list follows, or the key has no value.
+      const items: string[] = [];
+      while (i < lines.length && (lines[i]!.trim() === "" || LIST_ITEM.test(lines[i]!))) {
+        const item = LIST_ITEM.exec(lines[i]!);
+        if (item) {
+          const value = scalar(stripComment(item[1] ?? ""));
+          if (value !== null) items.push(value);
+        }
+        i++;
+      }
+      result[key] = items.length > 0 ? items : null;
+    } else {
+      // A plain scalar may continue on more indented lines.
+      let value = raw;
+      while (i < lines.length && lines[i]!.trim() !== "" && indentOf(lines[i]!) > 0 && !LIST_ITEM.test(lines[i]!)) value += ` ${lines[i++]!.trim()}`;
+      result[key] = scalar(value);
+    }
+  }
+  return result;
+}
+
+// ---- Writing ----
+
+const PLAIN = /^[A-Za-z0-9_/.()+-][^:#\n]*$/;
+const RESERVED = /^(?:true|false|yes|no|on|off|null|~|[-+]?(?:\d[\d_]*)?(?:\.\d+)?(?:e[-+]?\d+)?|0x[0-9a-f]+)$/i;
+
+/** A scalar as YAML: plain when that reads back as the same text, else single-quoted. */
+export function yamlScalar(value: string): string {
+  if (value !== "" && PLAIN.test(value) && value === value.trim() && !RESERVED.test(value) && !value.startsWith("- ")) return value;
+  return `'${value.replace(/'/g, "''").replace(/\n/g, " ")}'`;
+}
+
+/** The header lines for the keys in order; a list is written as a block list, an empty one as []. */
+export function writeFrontmatter(entries: [string, string | string[] | undefined][]): string {
+  const lines: string[] = ["---"];
+  for (const [key, value] of entries) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) lines.push(`${key}: []`);
+      else lines.push(`${key}:`, ...value.map((item) => `  - ${yamlScalar(item)}`));
+    } else lines.push(`${key}: ${yamlScalar(value)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}