@nightkatana/kronosys-app 1.0.0-beta.0

package/lib/taskParsing.ts

@@ -0,0 +1,737 @@
+/**
+ * Détection des `#token` dans un titre ou brouillon :
+ * - après un espace ou en début : `… #release`, `#seul`
+ * - collé au mot précédent : `mot#tag`, `issue#123`
+ */
+const AUTO_TAG_COMBINED = /(?:^|\s)#([^\s#]+)|(?<=[^\s#])#([^\s#]+)/g;
+
+/**
+ * Détection des `@projet` (mêmes idées que les `#tags`).
+ */
+const AUTO_PROJECT_COMBINED = /(?:^|\s)@([^\s@]+)|(?<=[^\s@])@([^\s@]+)/g;
+
+/**
+ * `@projet#suffixe` : étiquette liée à un projet (stockée comme `projet#suffixe`, sans `@`).
+ * Traitée avant les `@projet` seuls pour ne pas confondre le corps `projet#…` avec un nom de projet.
+ */
+const PROJECT_SCOPED_AT = /(?:^|\s)@([^\s@#]+)#([^\s#]+)/g;
+
+/** Extrait les jetons `@projet#suffixe` et retourne le texte restant. */
+export function stripScopedProjectAtTokens(raw: string): {
+  core: string;
+  scopedTags: string[];
+  scopedProjectHint?: string;
+} {
+  const scopedTags: string[] = [];
+  let scopedProjectHint: string | undefined;
+  const seen = new Set<string>();
+  const core = raw
+    .replace(PROJECT_SCOPED_AT, (_full, g1: string, g2: string) => {
+      const proj = (g1 || "").trim();
+      const loc = (g2 || "").trim();
+      if (!proj || !loc) {
+        return "";
+      }
+      if (!scopedProjectHint) {
+        scopedProjectHint = proj;
+      }
+      const canon = `${proj}#${loc}`;
+      const k = canon.toLowerCase();
+      if (!seen.has(k)) {
+        seen.add(k);
+        scopedTags.push(canon);
+      }
+      return "";
+    })
+    .replace(/\s+/g, " ")
+    .trim();
+  return { core, scopedTags, scopedProjectHint };
+}
+
+export function parseProjectScopedTag(tag: string): { projectKey: string; localTag: string } | null {
+  const t = tag.trim();
+  const i = t.indexOf("#");
+  if (i <= 0 || i >= t.length - 1) {
+    return null;
+  }
+  const projectKey = t.slice(0, i).trim();
+  const localTag = t.slice(i + 1).trim();
+  if (!projectKey || !localTag || localTag.includes("#")) {
+    return null;
+  }
+  return { projectKey, localTag };
+}
+
+export function isProjectScopedTag(tag: string): boolean {
+  return parseProjectScopedTag(tag) !== null;
+}
+
+/** Étiquette « globale » (sans `#` de portée) ou étiquette `@projet#code` compatible avec le projet courant. */
+export function isTagAllowedForProject(tag: string, project: string | null | undefined): boolean {
+  const scoped = parseProjectScopedTag(tag);
+  if (!scoped) {
+    return true;
+  }
+  const p = project?.trim();
+  if (!p) {
+    return false;
+  }
+  return scoped.projectKey.toLowerCase() === normalizeProjectKey(p).toLowerCase();
+}
+
+export function filterKnownTagsForProject(knownTags: string[], project: string | null | undefined): string[] {
+  return knownTags.filter((t) => isTagAllowedForProject(t, project));
+}
+
+/** Retire les étiquettes `@projet#code` incompatibles avec le projet assigné (ou sans projet). */
+export function filterTaskTagsForProject(tags: string[], project: string | null | undefined): string[] {
+  const p = project?.trim();
+  if (!p) {
+    return tags.filter((t) => !isProjectScopedTag(t));
+  }
+  return tags.filter((t) => isTagAllowedForProject(t, p));
+}
+
+/** Retire les `@projet` simples et retient le premier projet (une seule assignation par tâche). */
+function stripPlainProjectsAndTakeFirst(raw: string): { core: string; project?: string } {
+  let first: string | undefined;
+  const core = raw
+    .replace(AUTO_PROJECT_COMBINED, (_full, g1: string, g2: string) => {
+      const body = (g1 || g2 || "").trim();
+      if (body && !body.includes("#") && !first) {
+        first = normalizeProjectKey(body);
+      }
+      return "";
+    })
+    .replace(/\s+/g, " ")
+    .trim();
+  return { core, project: first };
+}
+
+/** Retire `@projet#suffixe` puis `@projet` ; fusionne l’indice de projet issu des jetons liés. */
+export function stripProjectsAndTakeFirst(raw: string): { core: string; project?: string; scopedTags: string[] } {
+  const { core: c0, scopedTags, scopedProjectHint } = stripScopedProjectAtTokens(raw);
+  const { core, project: plainProject } = stripPlainProjectsAndTakeFirst(c0);
+  const project = plainProject ?? scopedProjectHint;
+  return { core, project, scopedTags };
+}
+
+export function normalizeProjectKey(s: string): string {
+  return s.replace(/^@+/, "").trim();
+}
+
+/**
+ * Si le brouillon contient au moins un `@`, met à jour le projet (ou null si aucun jeton valide).
+ * Sinon ne pas modifier le champ projet côté API (`undefined`).
+ */
+export function resolveProjectForTaskUpdate(rawTitle: string): string | null | undefined {
+  if (!/@/.test(rawTitle)) {
+    return undefined;
+  }
+  const { project } = stripProjectsAndTakeFirst(rawTitle);
+  return project ?? null;
+}
+
+/**
+ * Projet à enregistrer à partir d’une ligne de tâche complète (champ unique avec `#`, `@`, `@p#t`).
+ * Aucun `@` dans la chaîne ⇒ aucun projet (`null`). Sinon, premier projet déduit comme à la saisie.
+ */
+export function resolveProjectFromFullTaskLine(rawTitle: string): string | null {
+  const t = rawTitle.replace(/\s+/g, " ").trim();
+  if (!/@/.test(t)) {
+    return null;
+  }
+  const { project } = stripProjectsAndTakeFirst(t);
+  return project ? normalizeProjectKey(project) : null;
+}
+
+/** Découpe le titre brut pour afficher le texte et les segments `#tag` comme pastilles (mêmes règles que {@link parseTaskWithAutoTags}). */
+export function splitTaskTitleSegments(raw: string): Array<{ kind: "text" | "tag"; value: string }> {
+  const re = new RegExp(AUTO_TAG_COMBINED.source, "g");
+  const out: Array<{ kind: "text" | "tag"; value: string }> = [];
+  let last = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(raw)) !== null) {
+    if (m.index > last) {
+      const text = raw.slice(last, m.index);
+      if (text.length > 0) {
+        out.push({ kind: "text", value: text });
+      }
+    }
+    const body = (m[1] || m[2] || "").trim();
+    if (body.length > 0) {
+      out.push({ kind: "tag", value: `#${body}` });
+    }
+    last = m.index + m[0].length;
+  }
+  if (last < raw.length) {
+    const text = raw.slice(last);
+    if (text.length > 0) {
+      out.push({ kind: "text", value: text });
+    }
+  }
+  if (out.length === 0 && raw.trim().length > 0) {
+    out.push({ kind: "text", value: raw });
+  }
+  return out;
+}
+
+/**
+ * Étiquettes détectées dans `raw`, dans l’ordre d’apparition (gauche → droite),
+ * sans doublon (insensible à la casse) — aligné sur {@link splitTaskTitleSegments}.
+ */
+function mergeDedupedTagLists(primary: string[], secondary: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const add = (t: string) => {
+    const n = normalizeTagKey(t).trim();
+    if (!n) {
+      return;
+    }
+    const k = n.toLowerCase();
+    if (seen.has(k)) {
+      return;
+    }
+    seen.add(k);
+    out.push(n);
+  };
+  for (const t of primary) {
+    add(t);
+  }
+  for (const t of secondary) {
+    add(t);
+  }
+  return out;
+}
+
+function collectAutoTagsFromRaw(raw: string): string[] {
+  const { core: afterScoped, scopedTags } = stripScopedProjectAtTokens(raw);
+  const fromHash: string[] = [];
+  const seen = new Set<string>();
+  for (const segment of splitTaskTitleSegments(afterScoped)) {
+    if (segment.kind !== "tag") {
+      continue;
+    }
+    const body = segment.value.replace(/^#/, "").trim();
+    if (body.length === 0) {
+      continue;
+    }
+    const key = body.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    fromHash.push(body);
+  }
+  return mergeDedupedTagLists(scopedTags, fromHash);
+}
+
+function parseNameAndTagsFromCore(core: string): { name: string; tags: string[] } {
+  const tags = collectAutoTagsFromRaw(core);
+  const name = core
+    .replace(new RegExp(AUTO_TAG_COMBINED.source, "g"), "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return { name, tags };
+}
+
+export function parseTaskWithAutoTags(raw: string): { name: string; tags: string[]; project?: string } {
+  const { core, project, scopedTags } = stripProjectsAndTakeFirst(raw);
+  const { name, tags } = parseNameAndTagsFromCore(core);
+  const merged = mergeDedupedTagLists(scopedTags, tags);
+  return { name, tags: filterTaskTagsForProject(merged, project ?? null), project };
+}
+
+/**
+ * Interprète une ligne de saisie rapide sous une tâche (`#tag`, `@projet`, `@p#code`, texte seul comme étiquette).
+ * Les étiquettes retournées sont déjà filtrées par projet si un `@projet` est détecté dans la même chaîne.
+ */
+export function parseQuickAddTagOrProjectLine(input: string): { tags: string[]; project?: string | null } {
+  const v = input.trim();
+  if (!v) {
+    return { tags: [] };
+  }
+  /** Seul `@` : retirer le projet (équivalent d’un clic « désactiver » sur la pastille projet enregistrée). */
+  if (v === "@") {
+    return { tags: [], project: null };
+  }
+  const parsed = parseTaskWithAutoTags(v);
+  const name = parsed.name.replace(/\s+/g, "").trim();
+  if (parsed.tags.length === 0 && parsed.project === undefined && name.length > 0) {
+    return { tags: [normalizeTagKey(name)], project: undefined };
+  }
+  if (parsed.project === undefined) {
+    return { tags: parsed.tags, project: undefined };
+  }
+  const proj = parsed.project ? normalizeProjectKey(parsed.project) : null;
+  return { tags: parsed.tags, project: proj };
+}
+
+/**
+ * Fusionne plusieurs lignes choisies (ex. valeurs d’un `<select multiple>` : `#tag`, `@projet`, `@`).
+ * Les étiquettes sont dédupliquées (casse ignorée). Le dernier jeton qui fixe le projet l’emporte ; `@` seul retire le projet.
+ */
+export function mergeQuickAddFromOptionValues(values: string[]): { tags: string[]; project?: string | null } {
+  const seen = new Set<string>();
+  const tags: string[] = [];
+  let project: string | null | undefined = undefined;
+  let projectTouched = false;
+
+  for (const raw of values) {
+    const r = parseQuickAddTagOrProjectLine(raw);
+    for (const tg of r.tags) {
+      const nk = normalizeTagKey(tg);
+      if (!nk) {
+        continue;
+      }
+      const k = nk.toLowerCase();
+      if (seen.has(k)) {
+        continue;
+      }
+      seen.add(k);
+      tags.push(nk);
+    }
+    if (r.project !== undefined) {
+      projectTouched = true;
+      project = r.project;
+    }
+  }
+
+  const out: { tags: string[]; project?: string | null } = { tags };
+  if (projectTouched) {
+    out.project = project;
+  }
+  return out;
+}
+
+/**
+ * Texte de titre pour l’UI : sans segments `#tag` ni `@projet` (pastilles séparées).
+ */
+export function taskTitleForDisplay(raw: string): string {
+  const { name, tags } = parseTaskWithAutoTags(raw);
+  const n = name.trim();
+  if (n.length > 0) {
+    return n;
+  }
+  if (tags.length > 0) {
+    return "—";
+  }
+  return raw.trim() || "—";
+}
+
+/**
+ * Valeur initiale du champ d’édition du titre (sans `#tags` ni `@projet` : pastilles en dessous).
+ * Chaîne vide lorsqu’il n’y a pas de libellé textuel (équivalent du « — » en lecture seule).
+ */
+export function taskTitleEditBaseline(storedName: string): string {
+  const { name, tags } = parseTaskWithAutoTags(storedName);
+  const n = name.trim();
+  if (n.length > 0) {
+    return n;
+  }
+  if (tags.length > 0) {
+    return "";
+  }
+  return storedName.trim();
+}
+
+/**
+ * Même extraction que {@link parseTaskWithAutoTags}, mais sans rogner le titre :
+ * nécessaire pour le champ de saisie contrôlé.
+ */
+export function parseTaskDraftParts(raw: string): { name: string; tags: string[]; project?: string } {
+  const { core, project, scopedTags } = stripProjectsAndTakeFirst(raw);
+  const fromCore = collectAutoTagsFromRaw(core);
+  const tags = mergeDedupedTagLists(scopedTags, fromCore);
+  const name = core.replace(new RegExp(AUTO_TAG_COMBINED.source, "g"), "");
+  return { name, tags, project };
+}
+
+function appendTagTokenToDraft(s: string, tag: string): string {
+  const t = normalizeTagKey(tag).trim();
+  if (!t) {
+    return s;
+  }
+  const scoped = parseProjectScopedTag(t);
+  if (scoped) {
+    const piece = `@${scoped.projectKey}#${scoped.localTag}`;
+    const trimmed = s.replace(/\s+$/, "");
+    return trimmed ? `${trimmed}${piece}` : piece;
+  }
+  const trimmedEnd = s.replace(/\s+$/, "");
+  return trimmedEnd ? `${trimmedEnd}#${t}` : `#${t}`;
+}
+
+/** Reconstruit le brouillon (titre + #tags + `@projet#code` + @projet optionnel). */
+export function rebuildTaskDraftCore(name: string, tags: string[], project?: string): string {
+  let s = name;
+  for (const t of tags) {
+    s = appendTagTokenToDraft(s, t);
+  }
+  const p = project?.trim();
+  if (p) {
+    const pk = normalizeProjectKey(p);
+    const implied = tags.some((tg) => {
+      const sc = parseProjectScopedTag(normalizeTagKey(tg));
+      return sc && sc.projectKey.toLowerCase() === pk.toLowerCase();
+    });
+    if (!implied) {
+      const trimmed = s.replace(/\s+$/, "");
+      s = trimmed ? `${trimmed}@${pk}` : `@${pk}`;
+    }
+  }
+  return s;
+}
+
+/** Reconstruit la chaîne « titre + #tags + `@p#t` [+ @projet] » alignée sur {@link parseTaskWithAutoTags}. */
+export function rebuildTaskRawString(name: string, tags: string[], project?: string | null): string {
+  const n = name.replace(/\s+/g, " ").trim();
+  let tagPart = n;
+  for (const t of tags) {
+    tagPart = appendTagTokenToDraft(tagPart, t);
+  }
+  const p = project?.trim();
+  if (!p) {
+    return tagPart;
+  }
+  const pk = normalizeProjectKey(p);
+  const implied = tags.some((tg) => {
+    const sc = parseProjectScopedTag(normalizeTagKey(tg));
+    return sc && sc.projectKey.toLowerCase() === pk.toLowerCase();
+  });
+  if (implied) {
+    return tagPart;
+  }
+  const trimmed = tagPart.replace(/\s+$/, "");
+  return trimmed ? `${trimmed}@${pk}` : `@${pk}`;
+}
+
+/**
+ * Chaîne pour le champ d’édition : nom stocké sans `#` / `@` + pastilles fusionnées + projet.
+ */
+export function displayRawTaskTitle(
+  storedName: string,
+  mergedTags: string[],
+  mergedProject?: string | null
+): string {
+  const { name: stripped } = parseTaskWithAutoTags(storedName);
+  const base = stripped.replace(/\s+/g, " ").trim();
+  const baseKey = base.toLowerCase();
+  const suffixTags = mergedTags.filter((t) => normalizeTagKey(t).toLowerCase() !== baseKey);
+  const suffix = suffixTags
+    .map((t) => {
+      const tk = normalizeTagKey(t);
+      const sc = parseProjectScopedTag(tk);
+      if (sc) {
+        return `@${sc.projectKey}#${sc.localTag}`;
+      }
+      return `#${tk}`;
+    })
+    .join(" ");
+  let out: string;
+  if (!suffix) {
+    out = base || storedName.trim();
+  } else if (!base) {
+    out = suffix;
+  } else {
+    out = `${base} ${suffix}`;
+  }
+  const p = mergedProject?.trim();
+  if (p) {
+    const pk = normalizeProjectKey(p);
+    const implied = suffixTags.some((tg) => {
+      const sc = parseProjectScopedTag(normalizeTagKey(tg));
+      return sc && sc.projectKey.toLowerCase() === pk.toLowerCase();
+    });
+    if (!implied) {
+      const trimmed = out.replace(/\s+$/, "");
+      out = trimmed ? `${trimmed}@${pk}` : `@${pk}`;
+    }
+  }
+  return out;
+}
+
+/** Ajoute un tag enregistré à la fin du brouillon (`#tag` ou `@projet#code`). */
+export function appendSavedTagToDraft(current: string, tag: string): string {
+  const token = normalizeTagKey(tag);
+  if (!token) {
+    return current;
+  }
+  const parsed = parseTaskDraftParts(current);
+  const nextTags = mergeDedupedTagLists(parsed.tags, [token]);
+  const prevCore = rebuildTaskDraftCore(parsed.name, parsed.tags, parsed.project);
+  const suff = current.startsWith(prevCore) ? current.slice(prevCore.length) : "";
+  const core = rebuildTaskDraftCore(parsed.name, nextTags, parsed.project);
+  return core + suff;
+}
+
+/** Retire une étiquette du brouillon (titre + jetons parsés), sans toucher au projet implicite. */
+export function removeSavedTagFromDraft(current: string, tag: string): string {
+  const token = normalizeTagKey(tag);
+  if (!token) {
+    return current;
+  }
+  const key = token.toLowerCase();
+  const parsed = parseTaskDraftParts(current);
+  const nextTags = parsed.tags.filter((t) => normalizeTagKey(t).toLowerCase() !== key);
+  return rebuildTaskRawString(parsed.name, nextTags, parsed.project ?? null);
+}
+
+/** Retire le projet (`@projet`) du brouillon sans modifier le libellé ni les étiquettes. */
+export function removeProjectFromDraft(current: string): string {
+  const parsed = parseTaskDraftParts(current);
+  return rebuildTaskRawString(parsed.name, parsed.tags, null);
+}
+
+/** Ajoute un projet connu à la fin du brouillon (`@nom`, sans espace avant `@` si le cœur se termine déjà par du texte). */
+export function appendSavedProjectToDraft(current: string, project: string): string {
+  const token = normalizeProjectKey(project);
+  if (!token) {
+    return current;
+  }
+  const parsed = parseTaskDraftParts(current);
+  if (parsed.project && parsed.project.toLowerCase() === token.toLowerCase()) {
+    return current;
+  }
+  const core = rebuildTaskDraftCore(parsed.name, parsed.tags, token);
+  const suff = current.startsWith(core) ? current.slice(core.length) : "";
+  return core + suff;
+}
+
+export function buildStartTaskFromInput(raw: string): { name: string; tags: string[]; project?: string } {
+  const trimmed = raw.trim();
+  const { name, tags, project } = parseTaskWithAutoTags(trimmed);
+  const displayName = name || tags[0] || trimmed;
+  return { name: displayName, tags, project };
+}
+
+/**
+ * Brouillon « en focus » : texte du champ + étiquettes / projet choisis via pastilles (sans les coller dans le titre).
+ */
+export function buildStartTaskFromDraft(
+  titleLine: string,
+  pickerTags: string[],
+  /** `undefined` : projet issu du titre ; chaîne vide : aucun projet (pastille désactivée). */
+  pickerProject: string | undefined
+): { name: string; tags: string[]; project?: string } {
+  const trimmed = titleLine.trim();
+  const parsed = parseTaskWithAutoTags(trimmed);
+  const allTags = mergeTagsForDisplay(trimmed, pickerTags);
+  const project =
+    pickerProject === undefined ? parsed.project : pickerProject.trim() ? pickerProject : undefined;
+  const tags = filterTaskTagsForProject(allTags, project ?? null);
+  const displayName =
+    parsed.name.trim() ||
+    (tags.length > 0 ? tags[0] : "") ||
+    trimmed ||
+    (project ? normalizeProjectKey(project) : "");
+  return {
+    name: displayName,
+    tags,
+    ...(project ? { project } : {}),
+  };
+}
+
+export function normalizeTagKey(s: string): string {
+  return s.replace(/^#/, "");
+}
+
+/** Étiquette canonique pour une tâche sans aucune étiquette explicite (stable, indépendante de la langue d’affichage). */
+export const DEFAULT_FALLBACK_TASK_TAG = "default";
+
+/** Options pour {@link normalizeTaskTagsForStorage}. */
+export type TaskTagsStorageNormalizeOpts = {
+  /**
+   * Lorsque `false`, une tâche sans étiquette valide après nettoyage reste avec `tags: []`.
+   * Lorsque `true` ou absent : comportement historique (`["default"]`).
+   */
+  assignDefaultTagBucket?: boolean;
+};
+
+/** Lit `cfg.taskDefaultTagBucketEnabled` du payload : `false` désactive le compartiment réservé ; défaut `true`. */
+export function readTaskDefaultTagBucketEnabled(cfg: unknown): boolean {
+  const o =
+    cfg && typeof cfg === "object" && !Array.isArray(cfg) ? (cfg as Record<string, unknown>) : undefined;
+  if (o && o.taskDefaultTagBucketEnabled === false) {
+    return false;
+  }
+  return true;
+}
+
+export function isFallbackTaskTagKey(tagKey: string): boolean {
+  const t = tagKey.trim();
+  if (t === "") {
+    return true;
+  }
+  return normalizeTagKey(t).toLowerCase() === DEFAULT_FALLBACK_TASK_TAG;
+}
+
+/**
+ * Déduplique les étiquettes ; si aucune ne subsiste après nettoyage, renvoie `[{@link DEFAULT_FALLBACK_TASK_TAG}]`
+ * sauf si {@link TaskTagsStorageNormalizeOpts.assignDefaultTagBucket} vaut `false` (tableau vide).
+ */
+export function normalizeTaskTagsForStorage(
+  tags: string[] | null | undefined,
+  opts?: TaskTagsStorageNormalizeOpts
+): string[] {
+  const raw = Array.isArray(tags) ? tags : [];
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+  for (const t of raw) {
+    const token = normalizeTagKey(String(t)).trim();
+    if (!token) {
+      continue;
+    }
+    const k = token.toLowerCase();
+    if (seen.has(k)) {
+      continue;
+    }
+    seen.add(k);
+    normalized.push(token);
+  }
+  if (normalized.length === 0) {
+    if (opts?.assignDefaultTagBucket === false) {
+      return [];
+    }
+    return [DEFAULT_FALLBACK_TASK_TAG];
+  }
+  return normalized;
+}
+
+/**
+ * Fusionne les étiquettes du titre et celles du tableau `tags`, sans doublon (insensible à la casse).
+ */
+export function mergeTagsForDisplay(rawName: string, storedTags?: string[] | null): string[] {
+  const fromTitle = collectAutoTagsFromRaw(rawName);
+  const fromArray = storedTags ?? [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const add = (t: string) => {
+    const n = normalizeTagKey(t);
+    const k = n.toLowerCase();
+    if (!n || seen.has(k)) {
+      return;
+    }
+    seen.add(k);
+    out.push(n);
+  };
+  for (const t of fromTitle) {
+    add(t);
+  }
+  for (const t of fromArray) {
+    add(t);
+  }
+  return out;
+}
+
+export function formatTagDisplay(tag: string): string {
+  const trimmed = tag.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  const scoped = parseProjectScopedTag(trimmed.replace(/^#/, ""));
+  if (scoped) {
+    return `@${scoped.projectKey}#${scoped.localTag}`;
+  }
+  const noHash = trimmed.replace(/^#/, "");
+  return trimmed.startsWith("#") ? trimmed : `#${noHash}`;
+}
+
+/** Libellé lisible pour une pastille d’étiquette ; `defaultBucketLabel` remplace l’affichage de l’étiquette réservée {@link DEFAULT_FALLBACK_TASK_TAG}. */
+export function formatTagDisplayForTask(tag: string, defaultBucketLabel?: string): string {
+  const trimmed = normalizeTagKey(String(tag)).trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed.toLowerCase() === DEFAULT_FALLBACK_TASK_TAG && defaultBucketLabel?.trim()) {
+    return defaultBucketLabel.trim();
+  }
+  return formatTagDisplay(tag);
+}
+
+export function formatProjectDisplay(project: string): string {
+  const trimmed = project.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  return trimmed.startsWith("@") ? trimmed : `@${normalizeProjectKey(trimmed)}`;
+}
+
+/**
+ * Durée lisible à partir d’une valeur en **minutes** (souvent fractionnaire, ex. agrégats reporting).
+ * Les secondes non nulles sont affichées dès qu’elles apparaissent après arrondi à la seconde la plus proche.
+ */
+export function formatDuration(minutes: number): string {
+  const m = Math.max(0, minutes);
+  if (m === 0) {
+    return "0 min";
+  }
+  const totalSec = Math.round(m * 60);
+  if (totalSec === 0) {
+    return "1 s";
+  }
+  const h = Math.floor(totalSec / 3600);
+  const remH = totalSec % 3600;
+  const mi = Math.floor(remH / 60);
+  const s = remH % 60;
+
+  if (h > 0) {
+    if (mi > 0 && s > 0) {
+      return `${h}h ${mi}m ${s} s`;
+    }
+    if (mi > 0) {
+      return `${h}h ${mi}m`;
+    }
+    if (s > 0) {
+      return `${h}h ${s} s`;
+    }
+    return `${h}h`;
+  }
+  if (mi > 0) {
+    return s > 0 ? `${mi} min ${s} s` : `${mi} min`;
+  }
+  return `${s} s`;
+}
+
+/**
+ * Durée murale affichée à partir de **millisecondes** : secondes obtenues par `floor(ms/1000)` pour que
+ * l’affichage progresse chaque seconde (ex. minuteur de session live entre deux rafraîchissements API).
+ * Toujours inclure les secondes lorsqu’il y a au moins une minute (`5 min 0 s`, `5 min 1 s`, …).
+ */
+export function formatWallDurationMs(ms: number): string {
+  const m = Math.max(0, ms);
+  const totalSec = Math.floor(m / 1000);
+  if (totalSec === 0) {
+    return "0 s";
+  }
+  const h = Math.floor(totalSec / 3600);
+  const rem = totalSec % 3600;
+  const mi = Math.floor(rem / 60);
+  const s = rem % 60;
+  if (h > 0) {
+    return `${h}h ${mi}m ${s} s`;
+  }
+  if (mi > 0) {
+    return `${mi} min ${s} s`;
+  }
+  return `${s} s`;
+}
+
+/**
+ * Chronomètre à partir de millisecondes : minutes (non padées) : secondes . centièmes,
+ * ou heures : minutes : secondes . centièmes au-delà d’une heure.
+ */
+export function formatStopwatchMs(ms: number): string {
+  const m = Math.max(0, Math.floor(ms));
+  const hours = Math.floor(m / 3600000);
+  const remH = m % 3600000;
+  const minutes = Math.floor(remH / 60000);
+  const remM = remH % 60000;
+  const seconds = Math.floor(remM / 1000);
+  const centis = Math.floor((remM % 1000) / 10);
+  const pad2 = (n: number) => String(n).padStart(2, "0");
+  if (hours > 0) {
+    return `${hours}:${pad2(minutes)}:${pad2(seconds)}.${pad2(centis)}`;
+  }
+  return `${minutes}:${pad2(seconds)}.${pad2(centis)}`;
+}