@nightkatana/kronosys-app 1.0.0-beta.0

package/server/actionTaskSession.ts

@@ -0,0 +1,717 @@
+import { randomUUID } from "node:crypto";
+
+import type { KronosysUpdatePayload } from "@/lib/kronosysApi";
+import {
+  normalizeProjectKey,
+  normalizeTagKey,
+  normalizeTaskTagsForStorage,
+  type TaskTagsStorageNormalizeOpts,
+} from "@/lib/taskParsing";
+
+export function asRecord(v: unknown): Record<string, unknown> | undefined {
+  return v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+
+export type ResolvedTaskSession = { session: Record<string, unknown>; isLive: boolean };
+
+/**
+ * Résout la session cible pour les mutations de tâches.
+ * Sans `sessionId` : session live (`current`) uniquement.
+ */
+export function resolveTaskSession(p: KronosysUpdatePayload, sessionId: unknown): ResolvedTaskSession | null {
+  const sid = typeof sessionId === "string" ? sessionId.trim() : "";
+  const cur = asRecord(p.current);
+  if (!sid) {
+    if (!cur) {
+      return null;
+    }
+    return { session: cur, isLive: true };
+  }
+  if (cur && String(cur.sessionId ?? "") === sid) {
+    return { session: cur, isLive: true };
+  }
+  const hist = (p.history || []) as Record<string, unknown>[];
+  const row = hist.find((h) => String(h.sessionId ?? "") === sid);
+  if (row) {
+    return { session: row, isLive: false };
+  }
+  const arch = (p.historyArchived || []) as Record<string, unknown>[];
+  const ar = arch.find((h) => String(h.sessionId ?? "") === sid);
+  return ar ? { session: ar, isLive: false } : null;
+}
+
+export function getActiveTasksArray(sess: Record<string, unknown>): Record<string, unknown>[] {
+  return Array.isArray(sess.activeTasks) ? ([...sess.activeTasks] as Record<string, unknown>[]) : [];
+}
+
+export function getTasksArray(sess: Record<string, unknown>): Record<string, unknown>[] {
+  return Array.isArray(sess.tasks) ? ([...sess.tasks] as Record<string, unknown>[]) : [];
+}
+
+/** Repère une tâche : pile active (`activeTasks` / `activeTask`) puis liste `tasks`. */
+export function findTaskRecord(sess: Record<string, unknown>, taskId: string): Record<string, unknown> | null {
+  const id = taskId;
+  for (const t of getActiveTasksArray(sess)) {
+    if (String(t.id) === id) {
+      return t;
+    }
+  }
+  const at = asRecord(sess.activeTask);
+  if (at && String(at.id) === id) {
+    return at;
+  }
+  return getTasksArray(sess).find((t) => String(t.id) === id) ?? null;
+}
+
+/**
+ * Parcourt toutes les tâches d’une session sans doublon (même tâche dans `activeTasks` + `activeTask` + `tasks`).
+ */
+export function forEachTaskRecordInSession(
+  sess: Record<string, unknown>,
+  fn: (task: Record<string, unknown>, taskId: string) => void
+): void {
+  const seen = new Set<string>();
+  for (const t of getActiveTasksArray(sess)) {
+    const id = String(t.id ?? "");
+    if (!id || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    fn(t, id);
+  }
+  const at = asRecord(sess.activeTask);
+  if (at) {
+    const id = String(at.id ?? "");
+    if (id && !seen.has(id)) {
+      seen.add(id);
+      fn(at, id);
+    }
+  }
+  for (const t of getTasksArray(sess)) {
+    const id = String(t.id ?? "");
+    if (!id || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    fn(t, id);
+  }
+}
+
+export function flushAllSubtaskTimersInSession(sess: Record<string, unknown>): void {
+  forEachTaskRecordInSession(sess, (task) => {
+    flushSubtaskTimerOnTask(task);
+  });
+}
+
+/**
+ * Avant de laisser une tâche au minuteur principal (non en pause) : seule tâche « en cours »
+ * (minuteries parentes ailleurs en pause ; tous les minuteurs sous-tâches arrêtés en accumulant le temps).
+ */
+export function prepareSessionForExclusiveMainTimerUnpaused(
+  sess: Record<string, unknown>,
+  mainTaskIdToUnpause: string
+): void {
+  flushAllSubtaskTimersInSession(sess);
+  const idKeep = String(mainTaskIdToUnpause);
+  forEachTaskRecordInSession(sess, (task, id) => {
+    if (task.isDone === true) {
+      return;
+    }
+    if (id !== idKeep && task.manualTaskTimerPaused !== true) {
+      flushMainTimerSegmentOnTask(task);
+    }
+  });
+  forEachTaskRecordInSession(sess, (task, id) => {
+    if (task.isDone === true) {
+      return;
+    }
+    task.manualTaskTimerPaused = id !== idKeep;
+  });
+  forEachTaskRecordInSession(sess, (task, id) => {
+    if (id === idKeep && task.isDone !== true && task.manualTaskTimerPaused !== true) {
+      ensureMainTimerSegmentForRunningTask(task);
+    }
+  });
+}
+
+/**
+ * Avant de démarrer le suivi d’une sous-tâche : arrêt des suivi sous-tâches sur les autres tâches,
+ * puis toutes les **autres** tâches non terminées en pause (minuteur parent) — la tâche ciblée reste
+ * gérée par l’appelant (`manualTaskTimerPaused = false` sur le parent, en parallèle du suivi).
+ */
+export function prepareSessionForSubtaskTimer(sess: Record<string, unknown>, focusTaskId: string): void {
+  const idFocus = String(focusTaskId);
+  forEachTaskRecordInSession(sess, (task, id) => {
+    if (id === idFocus) {
+      return;
+    }
+    if (task.isDone === true) {
+      return;
+    }
+    if (task.manualTaskTimerPaused !== true) {
+      flushMainTimerSegmentOnTask(task);
+    }
+    flushSubtaskTimerOnTask(task);
+  });
+  forEachTaskRecordInSession(sess, (task, id) => {
+    if (task.isDone === true) {
+      return;
+    }
+    if (id === idFocus) {
+      return;
+    }
+    task.manualTaskTimerPaused = true;
+  });
+}
+
+function ensureSubtasks(task: Record<string, unknown>): Record<string, unknown>[] {
+  if (!Array.isArray(task.subtasks)) {
+    task.subtasks = [];
+  }
+  return task.subtasks as Record<string, unknown>[];
+}
+
+/** Somme des `durationMs` enregistrées sur les sous-tâches (entiers non négatifs). */
+export function sumSubtasksDurationMsStored(task: Record<string, unknown>): number {
+  let sum = 0;
+  for (const st of ensureSubtasks(task)) {
+    if (!st || typeof st !== "object" || Array.isArray(st)) {
+      continue;
+    }
+    const row = st as Record<string, unknown>;
+    const d = row.durationMs;
+    const v = typeof d === "number" && Number.isFinite(d) ? d : 0;
+    sum += Math.max(0, Math.floor(v));
+  }
+  return sum;
+}
+
+/**
+ * Règle métier : le total parent (`durationMs`) peut dépasser la somme des points (travail sans
+ * suivi par sous-tâche), jamais l’inverse. Si des données contredisent cela, on élève le parent.
+ */
+export function ensureTaskParentDurationCoversSubtasksMs(task: Record<string, unknown>): void {
+  const sumSub = sumSubtasksDurationMsStored(task);
+  const raw = task.durationMs;
+  const parent = typeof raw === "number" && Number.isFinite(raw) ? Math.max(0, Math.floor(raw)) : 0;
+  if (sumSub > parent) {
+    task.durationMs = sumSub;
+  }
+}
+
+/** Clé ISO : début du segment de minuteur courant sur une sous-tâche (tâche parente). */
+const SUBTASK_TIMER_STARTED_AT = "subtaskTimerStartedAt";
+
+/** Clé ISO : début du segment du minuteur principal (hors sous-tâche) — persisté pour ne pas perdre le temps hors tableau de bord. */
+export const MAIN_TIMER_SEGMENT_STARTED_AT = "mainTimerSegmentStartedAt";
+
+/**
+ * Vide le segment de minuteur principal en cours : ajoute le temps écoulé à `durationMs`.
+ * Sans effet s’un suivi sous-tâche est actif (le parent ne cumule pas en parallèle).
+ */
+export function flushMainTimerSegmentOnTask(task: Record<string, unknown>): void {
+  if (String(task.activeSubtaskTimerId ?? "").trim() !== "") {
+    return;
+  }
+  const raw = task[MAIN_TIMER_SEGMENT_STARTED_AT];
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return;
+  }
+  const startedMs = Date.parse(raw);
+  if (!Number.isFinite(startedMs)) {
+    delete task[MAIN_TIMER_SEGMENT_STARTED_AT];
+    return;
+  }
+  const elapsed = Math.max(0, Math.floor(Date.now() - startedMs));
+  const parentPrev =
+    typeof task.durationMs === "number" && Number.isFinite(task.durationMs) ? Number(task.durationMs) : 0;
+  task.durationMs = Math.floor(parentPrev + elapsed);
+  delete task[MAIN_TIMER_SEGMENT_STARTED_AT];
+  ensureTaskParentDurationCoversSubtasksMs(task);
+}
+
+/** Démarre un segment de minuteur principal si la tâche est au suivi (hors sous-tâche). */
+export function ensureMainTimerSegmentForRunningTask(task: Record<string, unknown>): void {
+  if (task.isDone === true) {
+    return;
+  }
+  if (task.manualTaskTimerPaused === true) {
+    return;
+  }
+  if (String(task.activeSubtaskTimerId ?? "").trim() !== "") {
+    return;
+  }
+  const raw = task[MAIN_TIMER_SEGMENT_STARTED_AT];
+  if (typeof raw === "string" && raw.trim() !== "") {
+    return;
+  }
+  task[MAIN_TIMER_SEGMENT_STARTED_AT] = new Date().toISOString();
+}
+
+/**
+ * Ajoute le segment de minuteur sous-tâche en cours à `durationMs` de la sous-tâche active
+ * et le même segment à la tâche parente (répartition par point + total tâche ; les rapports ne lisent que le parent).
+ * Le total parent peut rester supérieur à la somme des points (travail sans sous-tâches), jamais l’inverse
+ * — rattrapage via `ensureTaskParentDurationCoversSubtasksMs` en fin de flush.
+ * Efface ensuite `activeSubtaskTimerId` et l’horodatage de segment.
+ */
+export function flushSubtaskTimerOnTask(task: Record<string, unknown>): void {
+  const activeId = String(task.activeSubtaskTimerId ?? "").trim();
+  if (!activeId) {
+    return;
+  }
+  const raw = task[SUBTASK_TIMER_STARTED_AT];
+  const startedMs =
+    typeof raw === "string" && raw.trim() !== ""
+      ? Date.parse(raw)
+      : typeof raw === "number" && Number.isFinite(raw)
+        ? raw
+        : Number.NaN;
+  if (!Number.isFinite(startedMs)) {
+    task.activeSubtaskTimerId = null;
+    delete task[SUBTASK_TIMER_STARTED_AT];
+    return;
+  }
+  const elapsed = Math.max(0, Date.now() - startedMs);
+  const st = ensureSubtasks(task).find((s) => String(s.id) === activeId);
+  if (st && typeof st === "object" && !Array.isArray(st)) {
+    const row = st as Record<string, unknown>;
+    const prev = typeof row.durationMs === "number" && Number.isFinite(row.durationMs) ? row.durationMs : 0;
+    row.durationMs = Math.floor(Number(prev) + elapsed);
+  }
+  const parentPrev =
+    typeof task.durationMs === "number" && Number.isFinite(task.durationMs) ? Number(task.durationMs) : 0;
+  task.durationMs = Math.floor(parentPrev + elapsed);
+  task.activeSubtaskTimerId = null;
+  delete task[SUBTASK_TIMER_STARTED_AT];
+  ensureTaskParentDurationCoversSubtasksMs(task);
+}
+
+export function finishTaskInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  shouldCommit: boolean,
+  tagNormOpts?: TaskTagsStorageNormalizeOpts
+): boolean {
+  const id = taskId;
+  let task: Record<string, unknown> | null = null;
+  let fromActiveStack = false;
+
+  const activeArr = getActiveTasksArray(sess);
+  const idx = activeArr.findIndex((t) => String(t.id) === id);
+  const at = asRecord(sess.activeTask);
+
+  if (idx >= 0) {
+    task = activeArr[idx] as Record<string, unknown>;
+    const sameAsActive = Boolean(at && String(at.id) === id);
+    activeArr.splice(idx, 1);
+    sess.activeTasks = activeArr;
+    if (sameAsActive) {
+      sess.activeTask = activeArr[0] ?? null;
+    }
+    fromActiveStack = true;
+  } else if (at && String(at.id) === id) {
+    task = at;
+    sess.activeTask = null;
+    sess.activeTasks = activeArr;
+    fromActiveStack = true;
+  } else {
+    task = getTasksArray(sess).find((t) => String(t.id) === id) ?? null;
+    if (!task || task.isDone === true) {
+      return false;
+    }
+  }
+
+  flushSubtaskTimerOnTask(task);
+  flushMainTimerSegmentOnTask(task);
+  task.isDone = true;
+  task.endTime = new Date().toISOString();
+  task.shouldCommit = shouldCommit;
+  task.manualTaskTimerPaused = false;
+  for (const st of ensureSubtasks(task)) {
+    if (st && typeof st === "object" && !Array.isArray(st)) {
+      (st as Record<string, unknown>).done = true;
+    }
+  }
+
+  task.tags = normalizeTaskTagsForStorage((task.tags as string[] | undefined) ?? [], tagNormOpts);
+  ensureTaskParentDurationCoversSubtasksMs(task);
+
+  const tasks = getTasksArray(sess);
+  const existingIdx = tasks.findIndex((t) => String(t.id) === id);
+  if (existingIdx >= 0) {
+    tasks[existingIdx] = task;
+  } else {
+    tasks.push(task);
+  }
+  sess.tasks = tasks;
+
+  if (fromActiveStack) {
+    const after = getActiveTasksArray(sess);
+    const curAt = asRecord(sess.activeTask);
+    if (curAt && String(curAt.id) === id) {
+      sess.activeTask = after[0] ?? null;
+    }
+    if (!sess.activeTask && after.length > 0) {
+      sess.activeTask = after[0] ?? null;
+    }
+  }
+  return true;
+}
+
+export function deleteTaskInSession(sess: Record<string, unknown>, taskId: string): boolean {
+  const id = taskId;
+  const before = findTaskRecord(sess, id);
+  if (!before) {
+    return false;
+  }
+  flushSubtaskTimerOnTask(before);
+  flushMainTimerSegmentOnTask(before);
+  sess.activeTasks = getActiveTasksArray(sess).filter((t) => String(t.id) !== id);
+  sess.tasks = getTasksArray(sess).filter((t) => String(t.id) !== id);
+  const curAt = asRecord(sess.activeTask);
+  if (curAt && String(curAt.id) === id) {
+    const next = (sess.activeTasks as Record<string, unknown>[])[0] ?? null;
+    sess.activeTask = next;
+  }
+  return true;
+}
+
+export function updateTaskInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  patch: { name?: string; tags?: string[]; project?: string | null },
+  tagNormOpts?: TaskTagsStorageNormalizeOpts
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  if (typeof patch.name === "string") {
+    task.name = patch.name;
+  }
+  if (Array.isArray(patch.tags)) {
+    task.tags = normalizeTaskTagsForStorage(patch.tags, tagNormOpts);
+  }
+  if (patch.project !== undefined) {
+    task.project = patch.project;
+  }
+  return true;
+}
+
+export function updateTaskStartTimeInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  startTimeIso: string
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  const startMs = Date.parse(startTimeIso);
+  if (!Number.isFinite(startMs)) {
+    return false;
+  }
+  const nowMs = Date.now();
+  task.startTime = new Date(startMs).toISOString();
+  const endRaw = typeof task.endTime === "string" ? task.endTime : "";
+  const endMs = Date.parse(endRaw);
+  if (Number.isFinite(endMs) && endMs >= startMs) {
+    task.durationMs = Math.max(0, Math.floor(endMs - startMs));
+    return true;
+  }
+  task.durationMs = Math.max(0, Math.floor(nowMs - startMs));
+  const subtaskRunning = String(task.activeSubtaskTimerId ?? "").trim() !== "";
+  if (!subtaskRunning && task.manualTaskTimerPaused !== true && task.isDone !== true) {
+    task[MAIN_TIMER_SEGMENT_STARTED_AT] = new Date(nowMs).toISOString();
+  }
+  ensureTaskParentDurationCoversSubtasksMs(task);
+  return true;
+}
+
+/**
+ * Corrige l’heure de fin d’une tâche **terminée** ; recalcule `durationMs`.
+ * Les tâches encore ouvertes utilisent le flux habituel (terminer / minuteur).
+ */
+export function updateTaskEndTimeInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  endTimeIso: string
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task || task.isDone !== true) {
+    return false;
+  }
+  const endMs = Date.parse(endTimeIso);
+  if (!Number.isFinite(endMs)) {
+    return false;
+  }
+  const startRaw = typeof task.startTime === "string" ? task.startTime : "";
+  const startMs = Date.parse(startRaw);
+  if (!Number.isFinite(startMs) || endMs < startMs) {
+    return false;
+  }
+  task.endTime = new Date(endMs).toISOString();
+  task.durationMs = Math.max(0, Math.floor(endMs - startMs));
+  ensureTaskParentDurationCoversSubtasksMs(task);
+  return true;
+}
+
+export function setTaskPausedInSession(sess: Record<string, unknown>, taskId: string, paused: boolean): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task || task.isDone === true) {
+    return false;
+  }
+  if (paused) {
+    flushSubtaskTimerOnTask(task);
+    flushMainTimerSegmentOnTask(task);
+    task.manualTaskTimerPaused = true;
+  } else {
+    flushSubtaskTimerOnTask(task);
+    prepareSessionForExclusiveMainTimerUnpaused(sess, taskId);
+  }
+  return true;
+}
+
+export function toggleSubtaskInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  subtaskId: string
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  const st = ensureSubtasks(task).find((s) => String(s.id) === subtaskId);
+  if (!st) {
+    return false;
+  }
+  const sid = String(subtaskId);
+  const wasTracking = String(task.activeSubtaskTimerId ?? "") === sid;
+  const nextDone = !Boolean(st.done);
+  if (wasTracking && nextDone) {
+    flushSubtaskTimerOnTask(task);
+  }
+  st.done = nextDone;
+  return true;
+}
+
+export function updateSubtaskTitleInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  subtaskId: string,
+  title: string
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  const st = ensureSubtasks(task).find((s) => String(s.id) === subtaskId);
+  if (!st) {
+    return false;
+  }
+  st.title = title;
+  return true;
+}
+
+export function setActiveSubtaskTimerInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  subtaskId: string | null
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  if (subtaskId === null || subtaskId === undefined) {
+    flushSubtaskTimerOnTask(task);
+    return true;
+  }
+  const sid = String(subtaskId);
+  const st = ensureSubtasks(task).find((s) => String(s.id) === sid);
+  if (!st) {
+    return false;
+  }
+  flushMainTimerSegmentOnTask(task);
+  prepareSessionForSubtaskTimer(sess, String(taskId));
+  flushSubtaskTimerOnTask(task);
+  task.activeSubtaskTimerId = sid;
+  task[SUBTASK_TIMER_STARTED_AT] = new Date().toISOString();
+  task.manualTaskTimerPaused = false;
+  return true;
+}
+
+export function deleteSubtaskInSession(sess: Record<string, unknown>, taskId: string, subtaskId: string): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  const sid = String(subtaskId);
+  if (String(task.activeSubtaskTimerId ?? "") === sid) {
+    flushSubtaskTimerOnTask(task);
+  }
+  const list = ensureSubtasks(task);
+  const next = list.filter((s) => String(s.id) !== sid);
+  task.subtasks = next;
+  ensureTaskParentDurationCoversSubtasksMs(task);
+  return true;
+}
+
+/**
+ * Réordonne les sous-tâches selon une liste complète d’identifiants (permutation exacte attendue).
+ */
+export function reorderSubtasksInSession(
+  sess: Record<string, unknown>,
+  taskId: string,
+  orderedSubtaskIds: string[]
+): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task) {
+    return false;
+  }
+  const list = ensureSubtasks(task);
+  if (list.length <= 1) {
+    return false;
+  }
+  const currentIds = new Set(list.map((s) => String(s.id)));
+  if (orderedSubtaskIds.length !== currentIds.size) {
+    return false;
+  }
+  const seen = new Set<string>();
+  for (const raw of orderedSubtaskIds) {
+    const id = String(raw);
+    if (!currentIds.has(id) || seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+  }
+  const byId = new Map(list.map((s) => [String(s.id), s]));
+  task.subtasks = orderedSubtaskIds.map((raw) => byId.get(String(raw))!);
+  return true;
+}
+
+export function addSubtaskInSession(sess: Record<string, unknown>, taskId: string, title: string): boolean {
+  const task = findTaskRecord(sess, taskId);
+  if (!task || task.isDone === true) {
+    return false;
+  }
+  const list = ensureSubtasks(task);
+  list.push({
+    id: randomUUID(),
+    title,
+    done: false,
+    durationMs: 0,
+  });
+  task.subtasks = list;
+  return true;
+}
+
+export function addHistoricalTaskToSession(
+  sess: Record<string, unknown>,
+  input: {
+    name: string;
+    tags: string[];
+    project?: string | null;
+    durationMs: number;
+    startTime: string;
+    endTime: string;
+  },
+  newId: string,
+  tagNormOpts?: TaskTagsStorageNormalizeOpts
+): void {
+  const task: Record<string, unknown> = {
+    id: newId,
+    name: input.name.trim(),
+    startTime: input.startTime,
+    endTime: input.endTime,
+    durationMs: input.durationMs,
+    isDone: true,
+    kronoFocusCycles: 0,
+    tags: normalizeTaskTagsForStorage(input.tags, tagNormOpts),
+    project: input.project ?? null,
+    subtasks: [],
+  };
+  const tasks = getTasksArray(sess);
+  tasks.push(task);
+  sess.tasks = tasks;
+}
+
+function eachSessionRecord(p: KronosysUpdatePayload, fn: (sess: Record<string, unknown>) => void): void {
+  const cur = asRecord(p.current);
+  if (cur) {
+    fn(cur);
+  }
+  for (const h of (p.history || []) as Record<string, unknown>[]) {
+    fn(h);
+  }
+  for (const h of (p.historyArchived || []) as Record<string, unknown>[]) {
+    fn(h);
+  }
+}
+
+function stripTagFromTaskTags(
+  task: Record<string, unknown>,
+  tagLower: string,
+  tagNormOpts?: TaskTagsStorageNormalizeOpts
+): void {
+  if (!Array.isArray(task.tags)) {
+    return;
+  }
+  const tags = task.tags as string[];
+  task.tags = normalizeTaskTagsForStorage(
+    tags.filter((x) => normalizeTagKey(x).toLowerCase() !== tagLower),
+    tagNormOpts
+  );
+}
+
+export function purgeTagEverywhere(
+  p: KronosysUpdatePayload,
+  rawTag: string,
+  tagNormOpts?: TaskTagsStorageNormalizeOpts
+): void {
+  const nk = normalizeTagKey(rawTag).toLowerCase();
+  p.knownTags = ((p.knownTags || []) as string[]).filter((t) => normalizeTagKey(t).toLowerCase() !== nk);
+  p.userKnownTags = ((p.userKnownTags || []) as string[]).filter((t) => normalizeTagKey(t).toLowerCase() !== nk);
+  p.excludedSuggestionTags = ((p.excludedSuggestionTags || []) as string[]).filter(
+    (t) => normalizeTagKey(t).toLowerCase() !== nk
+  );
+  const td = { ...(asRecord(p.tagDescriptions) ?? {}) } as Record<string, string>;
+  delete td[nk];
+  p.tagDescriptions = td;
+
+  eachSessionRecord(p, (sess) => {
+    for (const t of [...getActiveTasksArray(sess), ...getTasksArray(sess)]) {
+      stripTagFromTaskTags(t, nk, tagNormOpts);
+    }
+    const at = asRecord(sess.activeTask);
+    if (at) {
+      stripTagFromTaskTags(at, nk, tagNormOpts);
+    }
+  });
+}
+
+export function purgeProjectEverywhere(p: KronosysUpdatePayload, rawName: string): void {
+  const pk = normalizeProjectKey(rawName).toLowerCase();
+  p.knownProjects = ((p.knownProjects || []) as string[]).filter(
+    (n) => normalizeProjectKey(n).toLowerCase() !== pk
+  );
+  const pd = { ...(asRecord(p.projectDescriptions) ?? {}) } as Record<string, string>;
+  delete pd[pk];
+  p.projectDescriptions = pd;
+
+  eachSessionRecord(p, (sess) => {
+    for (const t of [...getActiveTasksArray(sess), ...getTasksArray(sess)]) {
+      const proj = t.project;
+      if (typeof proj === "string" && normalizeProjectKey(proj).toLowerCase() === pk) {
+        t.project = null;
+      }
+    }
+    const at = asRecord(sess.activeTask);
+    if (at) {
+      const proj = at.project;
+      if (typeof proj === "string" && normalizeProjectKey(proj).toLowerCase() === pk) {
+        at.project = null;
+      }
+    }
+  });
+}