codetrail-cli 1.4.1__py3-none-any.whl

codetrail/web/static/js/shortcuts.js

@@ -0,0 +1,87 @@
+// Keyboard shortcuts (design section 16.4). None of them spends anything: Ask and Update only open the panel or the
+// estimate dialog. Single keys are ignored while typing and whenever Command, Control or Alt is held.
+import { closeAsk, isAskOpen, openAsk } from "./ask.js";
+import { toggleRead } from "./learning.js";
+import { openPalette } from "./palette.js";
+import { dismissPeek, isPeeking, toggleSidebar } from "./sidebar.js";
+import { hideUpdatePanel, isUpdatePanelOpen, startUpdate } from "./update.js";
+
+const PLACES = { h: "/", p: "/progress", y: "/system", s: "/answers", d: "/digests", r: "/decisions", o: "/documentation", t: "/repository" };
+let awaitingPlace = null;
+
+function typing(element) {
+  return element instanceof Element && Boolean(element.closest("input, textarea, select, [contenteditable]"));
+}
+
+function follow(selector) {
+  const link = document.querySelector(selector);
+  if (link instanceof HTMLAnchorElement) window.location.href = link.href;
+}
+
+export function closeMenu() {
+  document.body.classList.remove("menu-open");
+  document.querySelector("[data-menu]")?.setAttribute("aria-expanded", "false");
+}
+
+export function setUpShortcuts() {
+  const help = document.querySelector("[data-shortcuts]");
+  for (const button of document.querySelectorAll("[data-shortcuts-open]")) {
+    button.addEventListener("click", () => help?.showModal());
+  }
+  help?.querySelector("[data-shortcuts-close]")?.addEventListener("click", () => help.close());
+  const menu = document.querySelector("[data-menu]");
+  menu?.addEventListener("click", () => {
+    const open = document.body.classList.toggle("menu-open");
+    menu.setAttribute("aria-expanded", String(open));
+  });
+
+  document.addEventListener("keydown", (event) => {
+    if (event.isComposing || event.defaultPrevented) return;
+    const key = event.key;
+    if ((event.metaKey || event.ctrlKey) && !event.altKey && !event.shiftKey && key.toLowerCase() === "k") {
+      event.preventDefault();
+      openPalette();
+      return;
+    }
+    if (event.metaKey || event.ctrlKey || event.altKey) return;
+    if (document.querySelector("dialog[open]")) return; // an open dialog handles its own keys
+    if (key === "Escape") {
+      if (isPeeking()) dismissPeek();
+      else if (document.body.classList.contains("menu-open")) closeMenu();
+      else if (isUpdatePanelOpen()) hideUpdatePanel(); // it sits over the Ask panel
+      else if (isAskOpen()) closeAsk();
+      return;
+    }
+    if (typing(event.target)) return;
+    if (awaitingPlace) {
+      clearTimeout(awaitingPlace);
+      awaitingPlace = null;
+      const place = PLACES[key.toLowerCase()];
+      if (place) {
+        event.preventDefault();
+        window.location.href = place;
+      }
+      return;
+    }
+    const actions = {
+      "/": () => openPalette(),
+      a: () => openAsk(),
+      g: () => {
+        awaitingPlace = setTimeout(() => {
+          awaitingPlace = null;
+        }, 1000);
+      },
+      "[": () => follow("[data-pager-previous]"),
+      "]": () => follow("[data-pager-next]"),
+      "\\": () => toggleSidebar(),
+      m: () => toggleRead(),
+      u: () => startUpdate(),
+      "?": () => help?.showModal(),
+    };
+    const action = actions[key.length === 1 && key !== "?" ? key.toLowerCase() : key];
+    if (action) {
+      event.preventDefault();
+      action();
+    }
+  });
+}

codetrail/web/static/js/sidebar.js

@@ -0,0 +1,194 @@
+// The sidebar (design section 22): hiding and showing it, peeking at it while hidden, folding its sections and
+// pinning pages. Hidden and folded are remembered in this browser; pins are kept by Codetrail. Titles are only ever
+// moved with textContent and attributes.
+import { post, remember } from "./api.js";
+
+const root = document.documentElement;
+const SECTIONS = ["paths", "areas", "concepts", "answers", "more"];
+const PEEK_DELAY = 150; // ms the pointer rests on the edge before the sidebar slides out
+const LEAVE_DELAY = 300; // ms after the pointer leaves before it slides away
+const narrow = window.matchMedia("(max-width: 900px)");
+let peekTimer = 0;
+
+const panel = () => document.querySelector("#sidebar");
+const edge = () => document.querySelector("[data-sidebar-edge]");
+const isHidden = () => root.dataset.sidebar === "hidden";
+export const isPeeking = () => document.body.classList.contains("sidebar-peek");
+
+function syncToggle() {
+  const button = document.querySelector("[data-sidebar-toggle]");
+  if (!button) return;
+  button.setAttribute("aria-expanded", String(!isHidden()));
+  button.setAttribute("aria-label", isHidden() ? button.dataset.labelShow : button.dataset.labelHide);
+}
+
+export function closePeek(returnFocus = false) {
+  clearTimeout(peekTimer);
+  if (!isPeeking()) return;
+  document.body.classList.remove("sidebar-peek");
+  edge()?.setAttribute("aria-expanded", "false");
+  if (returnFocus) edge()?.focus();
+}
+
+function openPeek(focusFirst) {
+  clearTimeout(peekTimer);
+  if (!isHidden() || narrow.matches) return;
+  document.body.classList.add("sidebar-peek");
+  edge()?.setAttribute("aria-expanded", "true");
+  if (focusFirst) panel()?.querySelector("a[href]")?.focus();
+}
+
+function closeSoon() {
+  clearTimeout(peekTimer);
+  peekTimer = setTimeout(() => closePeek(), LEAVE_DELAY);
+}
+
+// Esc: the focus goes back to the edge only when it was in the sidebar; elsewhere it stays where the reader is.
+export function dismissPeek() {
+  closePeek(Boolean(panel()?.contains(document.activeElement)));
+}
+
+export function toggleSidebar() {
+  if (narrow.matches) return;
+  const hide = !isHidden(); // while peeking it is hidden, so this docks it
+  const focusWasInside = Boolean(panel()?.contains(document.activeElement));
+  if (hide) root.dataset.sidebar = "hidden";
+  else delete root.dataset.sidebar;
+  remember("localStorage", "codetrail.sidebar", hide ? "hidden" : null);
+  closePeek();
+  syncToggle();
+  if (hide && focusWasInside) document.querySelector("[data-sidebar-toggle]")?.focus();
+}
+
+function setUpPeek() {
+  const strip = edge();
+  const sidebar = panel();
+  if (!strip || !sidebar) return;
+  // The card slides in under the pointer resting on the edge: moving between the two isn't leaving.
+  const inside = (node) => node instanceof Node && (node === strip || sidebar.contains(node));
+  strip.addEventListener("pointerenter", (event) => {
+    clearTimeout(peekTimer);
+    // Only a pointer arriving from the page peeks: the card sliding away under it after Esc mustn't reopen it.
+    if (!isPeeking() && !inside(event.relatedTarget)) peekTimer = setTimeout(() => openPeek(false), PEEK_DELAY);
+  });
+  strip.addEventListener("pointerleave", (event) => {
+    if (!isPeeking()) clearTimeout(peekTimer);
+    else if (!inside(event.relatedTarget)) closeSoon();
+  });
+  strip.addEventListener("click", () => openPeek(true)); // open, or already open: either way, into the sidebar
+  strip.addEventListener("focusout", (event) => {
+    const next = event.relatedTarget;
+    if (isPeeking() && next instanceof Node && !sidebar.contains(next)) closePeek(); // tabbed on into the page
+  });
+  sidebar.addEventListener("pointerenter", () => clearTimeout(peekTimer));
+  sidebar.addEventListener("pointerleave", (event) => isPeeking() && !inside(event.relatedTarget) && closeSoon());
+  narrow.addEventListener("change", () => closePeek()); // the drawer takes over below 900 px
+  sidebar.addEventListener("focusout", (event) => {
+    const next = event.relatedTarget;
+    if (isPeeking() && next instanceof Node && !sidebar.contains(next) && next !== strip) closePeek();
+  });
+  sidebar.addEventListener("click", (event) => {
+    if (isPeeking() && event.target instanceof Element && event.target.closest("a[href]")) closePeek();
+  });
+}
+
+function folded() {
+  return (root.dataset.folded ?? "").split(" ").filter((name) => SECTIONS.includes(name));
+}
+
+function setUpFolding() {
+  for (const button of document.querySelectorAll("[data-fold]")) {
+    const name = button.dataset.fold;
+    button.setAttribute("aria-expanded", String(!folded().includes(name)));
+    button.addEventListener("click", () => {
+      const now = folded();
+      const next = now.includes(name) ? now.filter((other) => other !== name) : [...now, name];
+      if (next.length) root.dataset.folded = next.join(" ");
+      else delete root.dataset.folded;
+      remember("localStorage", "codetrail.sidebar-folded", next.length ? next.join(" ") : null);
+      button.setAttribute("aria-expanded", String(!next.includes(name)));
+    });
+  }
+}
+
+const pageHref = (id) => `/pages/${id.split("/").map(encodeURIComponent).join("/")}`;
+
+function setUpPins() {
+  const sidebar = panel();
+  const list = sidebar?.querySelector("[data-pins]");
+  const template = sidebar?.querySelector("[data-pin-template]");
+  if (!sidebar || !list || !template) return;
+  const limit = Number(sidebar.dataset.maxPins) || 1;
+  // The drawn tiles are the list: a pinned page the guide dropped isn't drawn, so it isn't sent back.
+  const pinned = () => [...list.querySelectorAll("[data-unpin]")].map((button) => button.dataset.unpin);
+
+  function sync(ids) {
+    list.hidden = ids.length === 0;
+    for (const button of sidebar.querySelectorAll("[data-pin]")) {
+      const on = ids.includes(button.dataset.pin);
+      button.setAttribute("aria-pressed", String(on));
+      button.disabled = ids.length >= limit && !on;
+      if (button.disabled) button.title = sidebar.dataset.labelFull;
+      else button.removeAttribute("title");
+    }
+  }
+
+  function tile(button) {
+    const id = button.dataset.pin;
+    const title = button.closest("li")?.querySelector(".label")?.textContent.trim() || id;
+    const item = template.content.firstElementChild.cloneNode(true);
+    const link = item.querySelector("a");
+    const href = pageHref(id);
+    link.href = href;
+    link.title = title;
+    link.setAttribute("aria-label", title);
+    link.textContent = button.dataset.initials;
+    // The guide's pages are English; a saved answer is in whatever language it was asked in.
+    if (button.dataset.kind === "answer") link.dir = "auto";
+    else Object.assign(link, { lang: "en", dir: "ltr" });
+    // Compared as written: the template's link has no base to resolve against until it joins the page.
+    if (window.location.pathname === href) link.setAttribute("aria-current", "page");
+    const remove = item.querySelector("button");
+    remove.dataset.unpin = id;
+    remove.setAttribute("aria-label", sidebar.dataset.labelUnpin.replace("{title}", () => title)); // no $ patterns
+    return item;
+  }
+
+  async function save(ids) {
+    try {
+      return (await post("/settings/pins", { pages: ids })).ok;
+    } catch {
+      return false; // the sidebar stays as it was
+    }
+  }
+
+  let saving = false; // one change at a time, so a quick second click can't work from a stale list
+  sidebar.addEventListener("click", async (event) => {
+    const target = event.target instanceof Element ? event.target : null;
+    const pin = target?.closest("[data-pin]");
+    const unpin = target?.closest("[data-unpin]");
+    if ((!pin && !unpin) || saving) return;
+    saving = true;
+    try {
+      const id = pin ? pin.dataset.pin : unpin.dataset.unpin;
+      const ids = pinned();
+      const next = ids.includes(id) ? ids.filter((other) => other !== id) : [...ids, id];
+      if (!(await save(next))) return;
+      if (next.includes(id)) list.append(tile(pin));
+      else list.querySelector(`[data-unpin="${CSS.escape(id)}"]`)?.closest("li")?.remove();
+      sync(next);
+      if (unpin) sidebar.querySelector("a[href]")?.focus();
+    } finally {
+      saving = false;
+    }
+  });
+  for (const button of sidebar.querySelectorAll("[data-pin], [data-unpin]")) button.hidden = false;
+}
+
+export function setUpSidebar() {
+  document.querySelector("[data-sidebar-toggle]")?.addEventListener("click", toggleSidebar);
+  syncToggle();
+  setUpPeek();
+  setUpFolding();
+  setUpPins();
+}

codetrail/web/static/js/theme-init.js

@@ -0,0 +1,27 @@
+// Applies the reader's theme, panel widths and sidebar state before the page is drawn, so nothing flashes or jumps
+// (design 16.1, 16.2, 22). A classic script, loaded in <head> from Codetrail itself: the security policy allows no
+// inline script. resize.js fits the widths to the window once the page has loaded; sidebar.js runs the sidebar.
+(function () {
+  "use strict";
+  var root = document.documentElement;
+  var widths = [
+    ["codetrail.sidebar-width", "--sidebar-width", 200, 420],
+    ["codetrail.panel-width", "--panel-width", 320, 720],
+  ];
+  var sections = ["paths", "areas", "concepts", "answers", "more"];
+  try {
+    var theme = window.localStorage.getItem("codetrail.theme");
+    if (theme === "light" || theme === "dark") root.setAttribute("data-theme", theme);
+    for (var index = 0; index < widths.length; index += 1) {
+      var width = Number(window.localStorage.getItem(widths[index][0]));
+      if (width >= widths[index][2] && width <= widths[index][3]) root.style.setProperty(widths[index][1], width + "px");
+    }
+    if (window.localStorage.getItem("codetrail.sidebar") === "hidden") root.setAttribute("data-sidebar", "hidden");
+    var folded = (window.localStorage.getItem("codetrail.sidebar-folded") || "").split(" ").filter(function (name) {
+      return sections.indexOf(name) >= 0;
+    });
+    if (folded.length) root.setAttribute("data-folded", folded.join(" "));
+  } catch (error) {
+    // storage refused: the system's theme, the default widths and the docked, open sidebar apply
+  }
+})();

codetrail/web/static/js/theme.js

@@ -0,0 +1,42 @@
+// The theme switch: system, light or dark, remembered in localStorage when the browser allows it (design 16.2).
+import { recall, remember } from "./api.js";
+
+const THEMES = ["system", "light", "dark"];
+const button = document.querySelector("[data-theme-toggle]");
+
+function current() {
+  const stored = recall("localStorage", "codetrail.theme");
+  return THEMES.includes(stored) ? stored : "system";
+}
+
+function apply(theme) {
+  if (theme === "system") document.documentElement.removeAttribute("data-theme");
+  else document.documentElement.setAttribute("data-theme", theme);
+  if (button) {
+    const label = button.dataset[`label${theme[0].toUpperCase()}${theme.slice(1)}`] ?? theme;
+    button.setAttribute("aria-label", label);
+    button.title = label;
+    button.dataset.theme = theme;
+  }
+  document.dispatchEvent(new CustomEvent("codetrail:theme"));
+}
+
+export function isDark() {
+  const chosen = document.documentElement.getAttribute("data-theme");
+  if (chosen) return chosen === "dark";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+export function cycleTheme() {
+  const next = THEMES[(THEMES.indexOf(current()) + 1) % THEMES.length];
+  remember("localStorage", "codetrail.theme", next === "system" ? null : next);
+  apply(next);
+}
+
+export function setUpTheme() {
+  apply(current());
+  button?.addEventListener("click", cycleTheme);
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", () => {
+    if (current() === "system") apply("system");
+  });
+}

codetrail/web/static/js/update.js

@@ -0,0 +1,107 @@
+// Updating the guide from the page (design section 15.4): the facts are refreshed for free, then the estimate waits
+// in a dialog; only Go ahead, with the estimate's single-use id, lets paid work start. The update panel shows each
+// step as the server reports it, closes once the update is done, and stays open with the reason when it fails.
+import { getJSON, post } from "./api.js";
+
+const dialog = document.querySelector("[data-estimate-dialog]");
+const panel = document.querySelector("[data-update-panel]");
+const log = panel?.querySelector("[data-update-log]");
+const stateLine = panel?.querySelector("[data-update-state]");
+const ACTIVE = ["preparing", "waiting", "running"];
+const DONE_SHOWN_MS = 1500; // how long "Updated." stays before the panel closes
+let estimateId = null;
+let polling = false;
+let active = false;
+let after = 0; // the number of the last step shown
+
+function say(text, failed = false) {
+  stateLine.textContent = text;
+  stateLine.classList.toggle("failed", failed);
+}
+
+export function showUpdatePanel() {
+  if (panel) panel.hidden = false;
+}
+
+export function hideUpdatePanel() {
+  if (panel) panel.hidden = true;
+}
+
+export function isUpdatePanelOpen() {
+  return Boolean(panel && !panel.hidden);
+}
+
+async function decide(url) {
+  if (!estimateId) return;
+  const id = estimateId;
+  estimateId = null;
+  dialog.close();
+  await post(url, { estimate_id: id });
+  poll();
+}
+
+async function poll(reloadWhenDone = true) {
+  if (polling) return;
+  polling = true;
+  try {
+    const result = await getJSON(`/update/status?after=${after}`);
+    const labels = panel.dataset;
+    const { state, message } = result;
+    active = ACTIVE.includes(state);
+    if (result.log_html) log.insertAdjacentHTML("beforeend", result.log_html); // rendered, escaped on the server
+    after = result.next ?? after;
+    if (active) say(labels.labelRunning);
+    else if (state === "done") say(labels.labelDone);
+    else if (state === "failed") say(`${labels.labelFailed} ${message ?? ""}`, true);
+    else if (state === "declined") say(message ?? "", true);
+    if (state === "waiting" && result.estimate_id && result.estimate_id !== estimateId) {
+      estimateId = result.estimate_id;
+      dialog.querySelector("[data-estimate-body]").innerHTML = result.estimate_html; // rendered, escaped on the server
+      dialog.showModal();
+    }
+    polling = false;
+    if (active) setTimeout(() => poll(reloadWhenDone), 1500);
+    else if (state === "done") setTimeout(reloadWhenDone ? () => window.location.reload() : hideUpdatePanel, DONE_SHOWN_MS);
+  } catch {
+    polling = false;
+  }
+}
+
+export async function startUpdate() {
+  if (!dialog) return;
+  showUpdatePanel();
+  if (active) return; // one runs already: the panel shows it
+  log.replaceChildren();
+  say(panel.dataset.labelRunning);
+  const response = await post("/update", {});
+  if (!response.ok) {
+    const result = await response.json().catch(() => ({}));
+    if (response.status !== 409 && result.message) {
+      say(result.message, true);
+      return;
+    }
+  }
+  poll();
+}
+
+export function setUpUpdate() {
+  if (!dialog) return;
+  dialog.querySelector("[data-estimate-go]").addEventListener("click", () => decide("/update/confirm"));
+  dialog.querySelector("[data-estimate-cancel]").addEventListener("click", () => decide("/update/cancel"));
+  dialog.addEventListener("cancel", () => decide("/update/cancel")); // Escape cancels too
+  for (const button of document.querySelectorAll("[data-update-button]")) {
+    button.addEventListener("click", startUpdate);
+  }
+  panel.querySelector("[data-update-close]").addEventListener("click", hideUpdatePanel);
+  // An update already running or waiting when the page opens shows in the panel, with its steps so far.
+  getJSON("/update/status")
+    .then((result) => {
+      if (ACTIVE.includes(result.state)) {
+        showUpdatePanel();
+        poll(false);
+      } else {
+        after = result.next ?? 0; // the steps of an update that has ended aren't shown again
+      }
+    })
+    .catch(() => {});
+}