Rename Admin Notes root to index and support labeled file links - PR_26156_186-admin-notes-index-and-custom-links

Author: ToolboxAid

admin/notes.html

@@ -45,9 +45,9 @@ <h1>Admin Notes</h1>
                     <div class="card-body content-stack">
                         <div>
                             <div class="kicker">Project Notes</div>
-                            <h2 id="admin-notes-title" data-admin-notes-title>note.txt</h2>
+                            <h2 id="admin-notes-title" data-admin-notes-title>index.txt</h2>
                         </div>
-                        <a href="admin/notes.html" data-admin-notes-return hidden>Return to note.txt</a>
+                        <a href="admin/notes.html" data-admin-notes-return hidden>Return to index.txt</a>
                         <div class="status" role="status" data-admin-notes-status>Loading admin notes.</div>
                         <div class="content-stack" data-admin-notes-content aria-live="polite"></div>
                     </div>

admin/notes.js

@@ -1,6 +1,8 @@
 const NOTES_DIRECTORY = "docs_build/dev/admin-notes";
-const DEFAULT_NOTE = "note";
+const DEFAULT_NOTE = "index";
+const LINK_CLASS = "btn btn--compact primary";
 const NOTE_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const STATUS_ICON_PATTERN = /^\[([ xX.!?])\]\s*(.*)$/;
 
 class AdminNotesViewer {
   constructor(documentRef = document, historyRef = window.history) {
@@ -15,11 +17,15 @@ class AdminNotesViewer {
 
   bindEvents() {
     this.content?.addEventListener("click", (event) => {
-      const link = event.target.closest("[data-admin-note-link]");
-      if (!link) {
+      const link = event.target.closest("[data-admin-note-link], [data-admin-note-file]");
+      if (!link || !this.content.contains(link)) {
         return;
       }
       event.preventDefault();
+      if (link.dataset.adminNoteFile) {
+        this.openFile(link.dataset.adminNoteFile, true);
+        return;
+      }
       this.openNote(link.dataset.adminNoteLink || DEFAULT_NOTE, true);
     });
 
@@ -30,30 +36,43 @@ class AdminNotesViewer {
   }
 
   start() {
-    this.openNote(this.noteNameFromLocation(window.location), false);
+    this.openFromLocation(window.location, false);
   }
 
-  noteNameFromLocation(locationRef) {
+  openFromLocation(locationRef, pushHistory) {
     const params = new URLSearchParams(locationRef.search);
-    return this.noteNameFromValue(params.get("note") || DEFAULT_NOTE);
+    const filePath = params.get("file");
+    if (filePath) {
+      this.openFile(filePath, pushHistory);
+      return;
+    }
+    this.openNote(this.noteNameFromValue(params.get("note") || DEFAULT_NOTE), pushHistory);
   }
 
   noteNameFromValue(value) {
-    return String(value || DEFAULT_NOTE).replace(/\.txt$/i, "");
+    const normalized = String(value || DEFAULT_NOTE)
+      .trim()
+      .replace(/\\/g, "/")
+      .replace(/\/index(?:\.txt)?$/i, "")
+      .replace(/\.txt$/i, "");
+    return normalized || DEFAULT_NOTE;
   }
 
   validNoteName(noteName) {
     return NOTE_NAME_PATTERN.test(noteName);
   }
 
   notePath(noteName) {
-    return `${NOTES_DIRECTORY}/${noteName}.txt`;
+    return noteName === DEFAULT_NOTE
+      ? `${NOTES_DIRECTORY}/index.txt`
+      : `${NOTES_DIRECTORY}/${noteName}/index.txt`;
   }
 
   async openNote(noteName, pushHistory) {
     const normalizedNoteName = this.noteNameFromValue(noteName);
     this.clearContent();
-    this.setTitle(`${normalizedNoteName || DEFAULT_NOTE}.txt`);
+    const title = normalizedNoteName === DEFAULT_NOTE ? "index.txt" : `${normalizedNoteName}/index.txt`;
+    this.setTitle(title);
     this.setReturnVisible(normalizedNoteName !== DEFAULT_NOTE);
 
     if (!this.validNoteName(normalizedNoteName)) {
@@ -64,27 +83,79 @@ class AdminNotesViewer {
     }
 
     const notePath = this.notePath(normalizedNoteName);
+    await this.loadTextFile({
+      filePath: notePath,
+      title,
+      missingMessage: `Missing note file ${notePath}. Add this file under ${NOTES_DIRECTORY}/ or return to index.txt.`,
+      errorMessage: `Unable to load ${notePath}. Check the note file and reload the page.`,
+      pushHistory,
+      pushUrl: this.hrefForNote(normalizedNoteName)
+    });
+  }
+
+  async openFile(filePath, pushHistory) {
+    const normalizedFilePath = this.rootRelativeTextPathFromValue(filePath);
+    this.clearContent();
+    this.setTitle(normalizedFilePath || "linked file");
+    this.setReturnVisible(true);
+
+    if (!normalizedFilePath) {
+      this.renderError(
+        `Rejected linked file path "${filePath}". Use a repository-root text file path without traversal.`
+      );
+      return;
+    }
+
+    await this.loadTextFile({
+      filePath: normalizedFilePath,
+      title: normalizedFilePath,
+      missingMessage: `Missing linked file ${normalizedFilePath}. Add this text file under the repository root or return to index.txt.`,
+      errorMessage: `Unable to load ${normalizedFilePath}. Check the linked text file and reload the page.`,
+      pushHistory,
+      pushUrl: this.hrefForFile(normalizedFilePath)
+    });
+  }
+
+  async loadTextFile({ filePath, title, missingMessage, errorMessage, pushHistory, pushUrl }) {
     try {
-      const response = await fetch(notePath, { cache: "no-store" });
+      const response = await fetch(filePath, { cache: "no-store" });
       if (!response.ok) {
-        this.renderError(`Missing note file ${notePath}. Add this file under ${NOTES_DIRECTORY}/ or return to note.txt.`);
+        this.renderError(missingMessage);
         return;
       }
       const text = await response.text();
-      this.renderNote(text, normalizedNoteName);
-      this.setStatus(`Loaded ${notePath}.`);
+      this.renderNote(text, title);
+      this.setStatus(`Loaded ${filePath}.`);
       if (pushHistory) {
-        this.historyRef.pushState({}, "", this.hrefForNote(normalizedNoteName));
+        this.historyRef.pushState({}, "", pushUrl);
       }
     } catch {
-      this.renderError(`Unable to load ${notePath}. Check the note file and reload the page.`);
+      this.renderError(errorMessage);
     }
   }
 
   hrefForNote(noteName) {
     return noteName === DEFAULT_NOTE ? "admin/notes.html" : `admin/notes.html?note=${encodeURIComponent(noteName)}`;
   }
 
+  hrefForFile(filePath) {
+    return `admin/notes.html?file=${encodeURIComponent(filePath)}`;
+  }
+
+  rootRelativeTextPathFromValue(value) {
+    const rawValue = String(value || "").trim();
+    if (/^[A-Za-z]:/.test(rawValue) || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(rawValue)) {
+      return null;
+    }
+    const normalizedPath = rawValue.replace(/\\/g, "/").replace(/^\/+/, "");
+    const segments = normalizedPath.split("/");
+    const invalidSegments = segments.some((segment) => !segment || segment === "." || segment === "..");
+    if (!normalizedPath || invalidSegments || !normalizedPath.toLowerCase().endsWith(".txt")) {
+      return null;
+    }
+    return normalizedPath;
+  }
+
   clearContent() {
     this.content?.replaceChildren();
   }
@@ -116,26 +187,104 @@ class AdminNotesViewer {
     this.content?.append(errorMessage);
   }
 
-  renderNote(text, noteName) {
-    this.setTitle(`${noteName}.txt`);
+  renderNote(text, title) {
+    this.setTitle(title);
     const lines = text.split(/\r?\n/);
+    let currentList = null;
+    let lastTopLevelItem = null;
+    let nestedList = null;
+
     lines.forEach((line) => {
       const trimmed = line.trim();
       if (!trimmed) {
+        currentList = null;
+        lastTopLevelItem = null;
+        nestedList = null;
+        return;
+      }
+      const bullet = line.match(/^(\s*)-\s+(.*)$/);
+      if (bullet) {
+        const level = bullet[1].length >= 2 ? 1 : 0;
+        if (level === 0) {
+          currentList = currentList || this.documentRef.createElement("ul");
+          if (!currentList.parentNode) {
+            this.content?.append(currentList);
+          }
+          const item = this.documentRef.createElement("li");
+          this.appendRichText(item, bullet[2].trim());
+          currentList.append(item);
+          lastTopLevelItem = item;
+          nestedList = null;
+          return;
+        }
+        if (!lastTopLevelItem) {
+          currentList = currentList || this.documentRef.createElement("ul");
+          if (!currentList.parentNode) {
+            this.content?.append(currentList);
+          }
+          lastTopLevelItem = this.documentRef.createElement("li");
+          currentList.append(lastTopLevelItem);
+        }
+        nestedList = nestedList || this.documentRef.createElement("ul");
+        if (!nestedList.parentNode) {
+          lastTopLevelItem.append(nestedList);
+        }
+        const item = this.documentRef.createElement("li");
+        this.appendRichText(item, bullet[2].trim());
+        nestedList.append(item);
         return;
       }
+
       const node = this.sectionHeading(trimmed)
         ? this.documentRef.createElement("h3")
         : this.documentRef.createElement("p");
-      this.appendLinkedText(node, trimmed);
+      this.appendRichText(node, trimmed);
       this.content?.append(node);
+      currentList = null;
+      lastTopLevelItem = null;
+      nestedList = null;
     });
   }
 
   sectionHeading(text) {
     return ["Ideas", "Things to Fix", "Undecided Questions"].includes(text);
   }
 
+  appendRichText(parent, text) {
+    const statusMatch = text.match(STATUS_ICON_PATTERN);
+    if (statusMatch) {
+      parent.append(this.statusIcon(statusMatch[1]));
+      parent.append(this.documentRef.createTextNode(" "));
+      this.appendLinkedText(parent, statusMatch[2]);
+      return;
+    }
+    this.appendLinkedText(parent, text);
+  }
+
+  statusIcon(rawStatus) {
+    const icon = this.documentRef.createElement("strong");
+    icon.dataset.adminNotesStatusIcon = this.statusIconName(rawStatus);
+    icon.textContent = `[${rawStatus}]`;
+    return icon;
+  }
+
+  statusIconName(rawStatus) {
+    const normalizedStatus = rawStatus.toLowerCase();
+    if (normalizedStatus === "x") {
+      return "done";
+    }
+    if (normalizedStatus === ".") {
+      return "active";
+    }
+    if (normalizedStatus === "!") {
+      return "blocked";
+    }
+    if (normalizedStatus === "?") {
+      return "question";
+    }
+    return "open";
+  }
+
   appendLinkedText(parent, text) {
     const bracketPattern = /\[([^\]]+)\]/g;
     let cursor = 0;
@@ -149,15 +298,31 @@ class AdminNotesViewer {
     parent.append(this.documentRef.createTextNode(text.slice(cursor)));
   }
 
-  linkOrText(noteName) {
-    const normalizedNoteName = this.noteNameFromValue(noteName);
+  linkOrText(linkText) {
+    const commaIndex = linkText.indexOf(",");
+    if (commaIndex !== -1) {
+      const label = linkText.slice(0, commaIndex).trim();
+      const filePath = this.rootRelativeTextPathFromValue(linkText.slice(commaIndex + 1));
+      if (!label || !filePath) {
+        return this.documentRef.createTextNode(`[${linkText}]`);
+      }
+      const link = this.documentRef.createElement("a");
+      link.href = this.hrefForFile(filePath);
+      link.className = LINK_CLASS;
+      link.dataset.adminNoteFile = filePath;
+      link.textContent = label;
+      return link;
+    }
+
+    const normalizedNoteName = this.noteNameFromValue(linkText);
     if (!this.validNoteName(normalizedNoteName)) {
-      return this.documentRef.createTextNode(`[${noteName}]`);
+      return this.documentRef.createTextNode(`[${linkText}]`);
     }
     const link = this.documentRef.createElement("a");
     link.href = this.hrefForNote(normalizedNoteName);
+    link.className = LINK_CLASS;
     link.dataset.adminNoteLink = normalizedNoteName;
-    link.textContent = `[${noteName}]`;
+    link.textContent = `[${linkText}]`;
     return link;
   }
 }

docs_build/dev/admin-notes/index.txt

@@ -0,0 +1,14 @@
+Ideas
+- [ ] Capture admin-only project ideas here.
+  - [.] Keep nested ideas visible while they are still taking shape.
+- Use bracket links for connected notes, such as [other, /admin/notes/other/index.txt].
+- Review generated achievement prompts at [HERE, docs_build\tools-images-generated\achievements.txt].
+- Review the same generated prompts with a forward slash path at [HERE-FWD, docs_build/tools-images-generated/achievements.txt].
+
+Things to Fix
+- [!] Replace placeholder notes with concrete admin follow-up items.
+- Track fixes that are not ready for a dedicated BUILD_PR yet.
+
+Undecided Questions
+- [?] Decide which project questions need their own subnote files.
+- Keep open decisions visible until they become scoped work.

docs_build/dev/admin-notes/note.txt

@@ -0,0 +1,3 @@
+Other
+- [x] This is a sample linked admin subnote.
+  - Return to index.txt goes back to the main admin note.

docs_build/dev/admin-notes/other.txt

@@ -0,0 +1,38 @@
+# PR_26156_186 Admin Notes Index And Custom Links Report
+
+## Result
+PASS
+
+## Summary
+- Changed the Admin Notes root file from `docs_build/dev/admin-notes/note.txt` to `docs_build/dev/admin-notes/index.txt`.
+- Changed simple subnote routing so `[other]` loads `docs_build/dev/admin-notes/other/index.txt`.
+- Updated return navigation and loaded-file messaging to use `index.txt`.
+- Added custom bracket links with labels and repository-root text file paths, including backslash and forward slash path normalization.
+- Preserved simple `[other]` subnote links while adding status marker, bullet, and sub-bullet parsing.
+
+## Scope Controls
+- No archived V1/V2 files changed.
+- No `start_of_day` files changed.
+- No page-local CSS, inline styles, `<style>` blocks, inline event handlers, or inline `<script>` blocks added.
+- No new CSS was added; note links use existing Theme V2 button classes for the orange treatment.
+- No full samples smoke was run.
+
+## PR_26156_185 Context
+- No local `PR_26156_185` delta ZIP, report, or commit was found in the workspace.
+- The current tracked Admin Notes implementation was used as the available context.
+- The parser now covers the PR_26156_185 behaviors named in the BUILD: status markers and bullet/sub-bullet parsing.
+
+## Runtime Behavior Verified
+- Root page loads `docs_build/dev/admin-notes/index.txt`: PASS.
+- `[other]` opens `docs_build/dev/admin-notes/other/index.txt`: PASS.
+- Subnote return link says `Return to index.txt` and returns to the root index: PASS.
+- `[HERE, docs_build\tools-images-generated\achievements.txt]` displays `HERE` and opens the target file: PASS.
+- Forward slash and backslash custom paths both resolve to `docs_build/tools-images-generated/achievements.txt`: PASS.
+- Simple subnote traversal attempts are rejected before fetch: PASS.
+- Root-relative traversal and non-text paths are rejected before fetch: PASS.
+- Missing note and linked text files show visible actionable errors: PASS.
+- Status markers and bullet/sub-bullet parsing still render: PASS.
+
+## Notes
+- Missing-file validation intentionally triggers browser 404 fetches and verifies the visible actionable error messages.
+- Repository-root custom links are limited to normalized relative `.txt` paths without empty, current-directory, or parent-directory path segments.