@unbrained/pm-web 2026.8.10 → 2026.8.17

package/public/src/views/items.ts

@@ -43,9 +43,11 @@ interface BulkClosePayload {
   reason: string;
 }
 
-// Mirror the active item filters into the URL query string (on the /items
-// path) so a filtered view is shareable and bookmarkable. Replaces the current
-// history entry to avoid polluting back/forward with every keystroke.
+/**
+ * Mirrors the current item filters into the page URL query string when the
+ * items view is active, using history.replaceState so the filtered view is
+ * shareable without adding back/forward entries. Does nothing on other views.
+ */
 function syncFiltersToUrl(): void {
   if (state.currentView !== 'items') return;
   const qs = filtersToQueryString(state.itemFilters);
@@ -53,8 +55,12 @@ function syncFiltersToUrl(): void {
   try { history.replaceState(history.state, '', url); } catch { /* ignore */ }
 }
 
-// Read filters from the current URL's query string into state. Called when the
-// Items view is opened so a shared link applies its filters.
+/**
+ * Reads item filters from the current URL query string into state. Only
+ * replaces the in-memory filters when the URL actually carries filter
+ * parameters, so navigating to /items without a query string preserves the
+ * existing filters.
+ */
 export function loadFiltersFromUrl(): void {
   const params = new URLSearchParams(window.location.search);
   // Only override when the URL actually carries filter params, so navigating
@@ -86,6 +92,12 @@ const DEP_REL_OPTIONS = [
   { value: 'related', label: 'Related' },
 ] as const;
 
+/**
+ * Normalizes a raw dependency relationship label to a canonical value by
+ * trimming, lowercasing, and converting dashes to underscores, then applying a
+ * known-alias map (e.g. blockedby → blocked_by). Returns the alias when one
+ * exists, otherwise the normalized input unchanged.
+ */
 function normalizeDepRelation(raw?: string): string {
   const aliases: Record<string, string> = {
     blockedby: 'blocked_by',
@@ -107,6 +119,11 @@ function normalizeDepRelation(raw?: string): string {
   return aliases[normalized] ?? normalized;
 }
 
+/**
+ * Builds the HTML <option> elements for a dependency relationship dropdown from
+ * the fixed DEP_REL_OPTIONS list, marking the option that matches the
+ * normalized selected value as selected.
+ */
 function renderDependencyOptions(selected?: string): string {
   const current = normalizeDepRelation(selected);
   return DEP_REL_OPTIONS
@@ -114,6 +131,11 @@ function renderDependencyOptions(selected?: string): string {
     .join('');
 }
 
+/**
+ * Returns a human-readable display label for a dependency relationship by
+ * looking up its normalized value in a fixed label map, falling back to the
+ * original relationship string when no label is defined.
+ */
 function depLabel(rel: string): string {
   const labels: Record<string, string> = {
     blocked_by: 'Blocked by',
@@ -136,6 +158,11 @@ function depRelation(dep: RawDependency): string {
 // ═══════════════════════════════════════════════════════════════
 // BULK UPDATE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Opens the Bulk Update Items modal, which lets the user filter items and
+ * choose fields to change across many items at once. Shows an info toast and
+ * returns early when no project is currently selected.
+ */
 export function showBulkUpdateModal(): void {
   if (!state.currentProject) { toast('Select a project first', 'info'); return; }
   createModal('bulk-update-modal', 'Bulk Update Items', `
@@ -208,6 +235,12 @@ export function showBulkUpdateModal(): void {
   showModal('bulk-update-modal');
 }
 
+/**
+ * Runs a dry-run bulk update and renders a preview of the matched items and
+ * their field changes inside the modal. Requires at least one field to update,
+ * and stashes the actual (non-dry-run) payload on the Apply button so
+ * applyBulkUpdate can run without re-reading the form.
+ */
 export async function previewBulkUpdate(): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -281,6 +314,12 @@ export async function previewBulkUpdate(): Promise<void> {
   }
 }
 
+/**
+ * Applies the bulk update payload stashed on the Apply button by
+ * previewBulkUpdate, posting to the update-many endpoint. Reports the updated
+ * and failed counts via toast, closes the bulk update modal, and refreshes the
+ * items list and project badge.
+ */
 export async function applyBulkUpdate(): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -309,6 +348,11 @@ export async function applyBulkUpdate(): Promise<void> {
 // ═══════════════════════════════════════════════════════════════
 // BULK CLOSE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Opens the Bulk Close Items modal, which lets the user filter items and close
+ * or cancel many of them at once with a required reason. Shows an info toast
+ * and returns early when no project is currently selected.
+ */
 export function showBulkCloseModal(): void {
   if (!state.currentProject) { toast('Select a project first', 'info'); return; }
   createModal('bulk-close-modal', 'Bulk Close Items', `
@@ -364,6 +408,12 @@ export function showBulkCloseModal(): void {
   showModal('bulk-close-modal');
 }
 
+/**
+ * Previews the items that would be closed or canceled by running an
+ * update-many dry-run, and renders the matched count and first few items
+ * inside the modal. Requires a close reason, and stashes the close payload on
+ * the Apply button for applyBulkClose to use.
+ */
 export async function previewBulkClose(): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -423,6 +473,13 @@ export async function previewBulkClose(): Promise<void> {
   }
 }
 
+/**
+ * Applies the bulk close payload stashed on the Apply button by
+ * previewBulkClose, posting to the close-many endpoint which closes or cancels
+ * each matched item with the chosen reason. Reports the closed and failed
+ * counts via toast, closes the modal, and refreshes the items list and project
+ * badge.
+ */
 export async function applyBulkClose(): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -460,6 +517,12 @@ export async function applyBulkClose(): Promise<void> {
   }
 }
 
+/**
+ * Renders the Items view into the page: a header with refresh and bulk
+ * actions, the status filter tabs, the multi-field filter bar, and a loading
+ * list placeholder, then fetches and renders the items. Shows an empty state
+ * and returns when no project is selected.
+ */
 export async function renderItemsView(): Promise<void> {
   const el = document.getElementById('content-items');
   if (!el) return;
@@ -512,6 +575,12 @@ export async function renderItemsView(): Promise<void> {
   await fetchAndRenderItems();
 }
 
+/**
+ * Fetches items for the current project using the active filters (capped at
+ * 200, with tags filtered client-side because the list endpoint has no tag
+ * flag), stores them in state, updates the count subtitle, and renders the
+ * list. Shows an error state in the list element if the request fails.
+ */
 export async function fetchAndRenderItems(): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -545,6 +614,10 @@ export async function fetchAndRenderItems(): Promise<void> {
   }
 }
 
+/**
+ * Renders the items list element from state.items, showing an empty-state
+ * placeholder when there are no items or the mapped item rows otherwise.
+ */
 function renderItemsList(): void {
   const el = document.getElementById('items-list');
   if (!el) return;
@@ -559,6 +632,11 @@ function renderItemsList(): void {
   el.innerHTML = `<div class="item-list">${state.items.map(item => renderItemRow(item)).join('')}</div>`;
 }
 
+/**
+ * Returns the HTML markup for a single items-list row: a clickable card
+ * showing the item's type icon, id, title, tags, priority dot, and status
+ * badge that opens the item detail modal when clicked.
+ */
 export function renderItemRow(item: Item): string {
   const tags = (item.tags||[]).map(t=>`<span class="tag">${escHtml(t)}</span>`).join('');
   return `<div class="item-row" onclick="window.__app.openItemDetail('${escHtml(item.id)}')">
@@ -573,6 +651,11 @@ export function renderItemRow(item: Item): string {
   </div>`;
 }
 
+/**
+ * Reads the current values from every items filter-bar control into
+ * state.itemFilters, mirrors them to the URL, and re-fetches and renders the
+ * list.
+ */
 export function applyItemFilters(): void {
   const fs = document.getElementById('filter-status') as HTMLSelectElement | null;
   const ft = document.getElementById('filter-type') as HTMLSelectElement | null;
@@ -592,6 +675,10 @@ export function applyItemFilters(): void {
   fetchAndRenderItems();
 }
 
+/**
+ * Resets the item filters to empty, clears every filter-bar control in the
+ * DOM, mirrors the cleared filters to the URL, and re-renders the items list.
+ */
 export function clearFilters(): void {
   state.itemFilters = { ...EMPTY_FILTERS };
   const ids = ['filter-status','filter-type','filter-priority','filter-sprint','filter-release','filter-assignee','filter-tag'];
@@ -603,7 +690,11 @@ export function clearFilters(): void {
   fetchAndRenderItems();
 }
 
-// Copy a shareable URL for the current filtered Items view to the clipboard.
+/**
+ * Builds a shareable URL for the current filtered items view and copies it to
+ * the clipboard, toasting success or, if the clipboard write fails, toasting
+ * the URL itself for manual copy.
+ */
 export async function copyFilterLink(): Promise<void> {
   const qs = filtersToQueryString(state.itemFilters);
   const url = `${window.location.origin}/items${qs ? `?${qs}` : ''}`;
@@ -615,6 +706,10 @@ export async function copyFilterLink(): Promise<void> {
   }
 }
 
+/**
+ * Sets the status filter to the provided value, mirrors it to the URL, and
+ * re-renders the entire items view.
+ */
 export function setStatusFilter(status: string): void {
   state.itemFilters.status = status;
   syncFiltersToUrl();
@@ -624,6 +719,12 @@ export function setStatusFilter(status: string): void {
 // ═══════════════════════════════════════════════════════════════
 // ITEM DETAIL MODAL
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Opens the item detail modal and renders it. Fetches the item together with
+ * its comments, history, dependencies, learnings, notes, tests, and linked
+ * files in parallel (each detail call falls back to empty on failure) and
+ * builds the full tabbed detail view.
+ */
 export async function openItemDetail(itemId: string): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -966,6 +1067,11 @@ export async function openItemDetail(itemId: string): Promise<void> {
   }
 }
 
+/**
+ * Formats a timestamp as a human-readable relative age string (just now,
+ * Nm/Nh/Nd ago) for recent times, or a localized date for anything older than
+ * a week. Returns an empty string when the timestamp is missing.
+ */
 function relTime(ts: string | undefined | null): string {
   if (!ts) return '';
   const d = new Date(ts);
@@ -983,6 +1089,12 @@ function fmtDate(ts: string | undefined | null): string {
   return new Date(ts).toLocaleDateString('en-US', { year:'numeric', month:'short', day:'numeric' });
 }
 
+/**
+ * Switches the item detail modal to the selected tab: toggles the active class
+ * on the tabs, shows the target tab panel while hiding the others, tears down
+ * the local graph when leaving the graph tab, and initializes the graph along
+ * with its depth-slider listener when entering the graph tab with a nodeId.
+ */
 export function switchDetailTab(tabEl: HTMLElement, targetId: string, nodeId?: string): void {
   const allTabs = tabEl.parentElement?.querySelectorAll('.tab');
   allTabs?.forEach(t => t.classList.remove('active'));
@@ -1008,6 +1120,11 @@ export function switchDetailTab(tabEl: HTMLElement, targetId: string, nodeId?: s
   }
 }
 
+/**
+ * Posts the comment typed into the detail modal's comment box to the item,
+ * requiring non-empty text. On success it clears the box, toasts confirmation,
+ * and reopens the item detail to refresh the comments tab.
+ */
 export async function addComment(itemId: string): Promise<void> {
   const el = document.getElementById('new-comment') as HTMLTextAreaElement | null;
   if (!el) return;
@@ -1021,6 +1138,10 @@ export async function addComment(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Posts the note typed into the detail modal's note box to the item, requiring
+ * non-empty text. On success it clears the box and toasts confirmation.
+ */
 export async function addNote(itemId: string): Promise<void> {
   const el = document.getElementById('new-note') as HTMLTextAreaElement | null;
   if (!el) return;
@@ -1033,6 +1154,11 @@ export async function addNote(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Appends the text from the detail modal's append box to the item's
+ * description, requiring non-empty text. On success it clears the box and
+ * toasts confirmation.
+ */
 export async function appendItem(itemId: string): Promise<void> {
   const el = document.getElementById('new-append') as HTMLTextAreaElement | null;
   if (!el) return;
@@ -1045,6 +1171,11 @@ export async function appendItem(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Saves the item detail's Update form: reads every edit field, requires a
+ * title, and PATCHes the changed fields to the backend. On success it reopens
+ * the item detail and refreshes the items list and project badge.
+ */
 export async function updateItem(itemId: string): Promise<void> {
   const titleEl = document.getElementById('edit-title') as HTMLInputElement | null;
   const statusEl = document.getElementById('edit-status') as HTMLSelectElement | null;
@@ -1093,6 +1224,12 @@ export async function updateItem(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Closes or cancels the item with a required reason. For canceled it first
+ * sets the status to canceled via the update endpoint before posting the close
+ * reason; for closed it posts the close reason directly. Reports the outcome,
+ * hides the detail modal, and refreshes the items list and project badge.
+ */
 export async function closeItem(itemId: string, targetStatus: string): Promise<void> {
   const reasonEl = document.getElementById('close-reason') as HTMLTextAreaElement | null;
   const reason = reasonEl?.value?.trim();
@@ -1111,6 +1248,10 @@ export async function closeItem(itemId: string, targetStatus: string): Promise<v
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Shows a confirmation dialog and, on confirm, DELETEs the item, hides the
+ * detail modal, and refreshes the items list and project badge.
+ */
 export function confirmDeleteItem(itemId: string): void {
   confirmDialog('Delete Item?', 'This action cannot be undone. The item and all its data will be permanently removed.', async () => {
     try {
@@ -1126,6 +1267,12 @@ export function confirmDeleteItem(itemId: string): void {
 // ═══════════════════════════════════════════════════════════════
 // CLAIM / RELEASE / START / PAUSE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Claims the item for the current user via the claim endpoint, dimming the
+ * matching list row optimistically. On success it reopens the detail and
+ * refreshes the list; on failure it restores the row opacity and toasts the
+ * error.
+ */
 export async function claimItem(itemId: string): Promise<void> {
   const row = document.querySelector(`.item-row[onclick*="${itemId}"]`) as HTMLElement | null;
   if (row) row.style.opacity = '0.6';
@@ -1137,6 +1284,10 @@ export async function claimItem(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); if (row) row.style.opacity = ''; }
 }
 
+/**
+ * Releases the current user's claim on the item via the release endpoint, then
+ * reopens the detail and refreshes the items list.
+ */
 export async function releaseItem(itemId: string): Promise<void> {
   try {
     await api('POST',`/projects/${state.currentProject!.id}/pm/release/${itemId}`,{});
@@ -1146,6 +1297,10 @@ export async function releaseItem(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Starts the item (moving it into in_progress) via the start-task endpoint,
+ * then reopens the detail and refreshes the items list and project badge.
+ */
 export async function startItem(itemId: string): Promise<void> {
   try {
     await api('POST',`/projects/${state.currentProject!.id}/pm/start-task/${itemId}`,{});
@@ -1156,6 +1311,10 @@ export async function startItem(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Pauses the in-progress item via the pause-task endpoint, then reopens the
+ * detail and refreshes the items list and project badge.
+ */
 export async function pauseItem(itemId: string): Promise<void> {
   try {
     await api('POST',`/projects/${state.currentProject!.id}/pm/pause-task/${itemId}`,{});
@@ -1169,6 +1328,12 @@ export async function pauseItem(itemId: string): Promise<void> {
 // ═══════════════════════════════════════════════════════════════
 // DEPS / LEARNINGS / TESTS / FILES
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Adds a dependency to the item from the detail modal's dependency inputs:
+ * reads and normalizes the target id and relationship, rejects an empty or
+ * self-referential target, and posts to the deps endpoint. On success it
+ * reopens the item detail.
+ */
 export async function addDep(itemId: string): Promise<void> {
   const targetIdEl = document.getElementById('dep-target-id') as HTMLInputElement | null;
   const relEl = document.getElementById('dep-rel') as HTMLSelectElement | null;
@@ -1186,6 +1351,11 @@ export async function addDep(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Removes a dependency from the item after confirming with the user. Normalizes
+ * the relationship, requires a target id, and DELETEs the dependency from the
+ * deps endpoint; on success it reopens the item detail.
+ */
 export async function removeDep(itemId: string, targetId: string, relation: string): Promise<void> {
   const rel = normalizeDepRelation(relation);
   if (!targetId) { toast('Target item ID is required','error'); return; }
@@ -1203,6 +1373,11 @@ export async function removeDep(itemId: string, targetId: string, relation: stri
   );
 }
 
+/**
+ * Records a learning typed into the detail modal on the item, requiring
+ * non-empty text. On success it toasts confirmation and reopens the item
+ * detail.
+ */
 export async function addLearning(itemId: string): Promise<void> {
   const el = document.getElementById('new-learning') as HTMLTextAreaElement | null;
   const text = el?.value?.trim() || '';
@@ -1214,6 +1389,11 @@ export async function addLearning(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Adds a test command (required) with an optional description to the item via
+ * the tests endpoint. On success it toasts confirmation and reopens the item
+ * detail.
+ */
 export async function addTest(itemId: string): Promise<void> {
   const cmdEl = document.getElementById('new-test-cmd') as HTMLInputElement | null;
   const descEl = document.getElementById('new-test-desc') as HTMLInputElement | null;
@@ -1227,6 +1407,10 @@ export async function addTest(itemId: string): Promise<void> {
   } catch(err: unknown) { toast(err instanceof Error ? err.message : String(err),'error'); }
 }
 
+/**
+ * Links a file path (required) to the item via the files endpoint. On success
+ * it toasts confirmation and reopens the item detail.
+ */
 export async function addFileLink(itemId: string): Promise<void> {
   const el = document.getElementById('file-path-input') as HTMLInputElement | null;
   const filePath = el?.value?.trim() || '';
@@ -1241,6 +1425,12 @@ export async function addFileLink(itemId: string): Promise<void> {
 // ═══════════════════════════════════════════════════════════════
 // USE ITEM AS TEMPLATE
 // ═══════════════════════════════════════════════════════════════
+/**
+ * Closes the item detail modal and opens the create view pre-filled from the
+ * given item's fields, prefixing the title with "Copy of" and focusing and
+ * selecting it so the user can immediately edit. The form is filled after a
+ * short delay to let the create view render.
+ */
 export function useItemAsTemplate(item: Record<string, unknown>): void {
   // Close the item detail modal and navigate to create view
   hideModal('item-detail-modal');

package/public/src/views/normalize.js

@@ -5,6 +5,7 @@ import { state } from '../state.js';
 import { api } from '../api.js';
 import { escHtml } from '../utils.js';
 import { toast } from '../components/toast.js';
+/** Renders a dry-run preview of lifecycle metadata normalization for the current project, listing each suggested change with an item link and an apply button that only advises using the CLI. */
 export async function renderNormalizeView() {
     const el = document.getElementById('content-normalize');
     if (!el)
@@ -59,6 +60,7 @@ export async function renderNormalizeView() {
             el2.innerHTML = `<div class="empty-state"><div class="empty-state-text">Error: ${escHtml(err instanceof Error ? err.message : String(err))}</div></div>`;
     }
 }
+/** Notifies the user that normalization in the web UI is a dry-run and that applying changes requires the CLI with the --apply flag. */
 export function applyNormalize() {
     if (!state.currentProject)
         return;

package/public/src/views/normalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.js","sourceRoot":"","sources":["normalize.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,iBAAiB;AACjB,kEAAkE;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAG/C,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACxD,IAAI,CAAC,EAAE;QAAE,OAAO;IAChB,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC;QAAC,EAAE,CAAC,SAAS,GAAG,wFAAwF,CAAC;QAAC,OAAO;IAAC,CAAC;IAC/I,EAAE,CAAC,SAAS,GAAG;;oHAEmG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC;;;2GAG3C,CAAC;IAC1G,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAoB,MAAM,EAAE,aAAa,KAAK,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,CAAC;QACvG,MAAM,IAAI,GAAkB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC;QACpE,MAAM,KAAK,GAAsB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QAClE,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,SAAS,GAAG,mKAAmK,CAAC;QACtL,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,SAAS,GAAG;;gFAE0D,KAAK,CAAC,MAAM;;cAE9E,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;;;;gDAIiB,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBACpF,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,wHAAwH,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,gDAAgD,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;;qBAEzN,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;;;;;;eAMhB,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,SAAS,GAAG,yHAAyH,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC;QACtM,CAAC;IACH,CAAC;IAAC,OAAM,GAAY,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QACzD,IAAI,GAAG;YAAE,GAAG,CAAC,SAAS,GAAG,iEAAiE,OAAO,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC;IACpK,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC,KAAK,CAAC,cAAc;QAAE,OAAO;IAClC,KAAK,CAAC,wEAAwE,EAAE,MAAM,CAAC,CAAC;AAC1F,CAAC"}
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["normalize.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,iBAAiB;AACjB,kEAAkE;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAG/C,kMAAkM;AAClM,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACxD,IAAI,CAAC,EAAE;QAAE,OAAO;IAChB,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC;QAAC,EAAE,CAAC,SAAS,GAAG,wFAAwF,CAAC;QAAC,OAAO;IAAC,CAAC;IAC/I,EAAE,CAAC,SAAS,GAAG;;oHAEmG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC;;;2GAG3C,CAAC;IAC1G,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAoB,MAAM,EAAE,aAAa,KAAK,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC,CAAC;QACvG,MAAM,IAAI,GAAkB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC;QACpE,MAAM,KAAK,GAAsB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QAClE,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,SAAS,GAAG,mKAAmK,CAAC;QACtL,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,SAAS,GAAG;;gFAE0D,KAAK,CAAC,MAAM;;cAE9E,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;;;;gDAIiB,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,WAAW,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBACpF,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,wHAAwH,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,gDAAgD,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;;qBAEzN,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;;;;;;eAMhB,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,SAAS,GAAG,yHAAyH,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC;QACtM,CAAC;IACH,CAAC;IAAC,OAAM,GAAY,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QACzD,IAAI,GAAG;YAAE,GAAG,CAAC,SAAS,GAAG,iEAAiE,OAAO,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC;IACpK,CAAC;AACH,CAAC;AAED,wIAAwI;AACxI,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC,KAAK,CAAC,cAAc;QAAE,OAAO;IAClC,KAAK,CAAC,wEAAwE,EAAE,MAAM,CAAC,CAAC;AAC1F,CAAC"}

package/public/src/views/normalize.ts

@@ -7,6 +7,7 @@ import { escHtml } from '../utils.js';
 import { toast } from '../components/toast.js';
 import type { NormalizeChange, NormalizePlan, NormalizeResponse } from '../api-types.js';
 
+/** Renders a dry-run preview of lifecycle metadata normalization for the current project, listing each suggested change with an item link and an apply button that only advises using the CLI. */
 export async function renderNormalizeView(): Promise<void> {
   const el = document.getElementById('content-normalize');
   if (!el) return;
@@ -53,6 +54,7 @@ export async function renderNormalizeView(): Promise<void> {
   }
 }
 
+/** Notifies the user that normalization in the web UI is a dry-run and that applying changes requires the CLI with the --apply flag. */
 export function applyNormalize(): void {
   if (!state.currentProject) return;
   toast('Normalization applied (dry-run — use CLI with --apply to make changes)', 'info');

package/public/src/views/packages.js

@@ -30,6 +30,12 @@ let currentPackages = [];
  * own response if a newer fetch has begun since.
  */
 let packagesFetchToken = 0;
+/**
+ * Mounts the packages view into the #content-packages element. Wires the
+ * action handler, shows an empty state when no project is selected, otherwise
+ * renders the header and a loading placeholder, then fetches and renders the
+ * package cards.
+ */
 export async function renderPackagesView() {
     ensureActionsWired();
     const el = document.getElementById('content-packages');
@@ -52,6 +58,12 @@ export async function renderPackagesView() {
     <div id="packages-content"><div class="loading-state"><div class="loading-spinner"></div></div></div>`;
     await fetchAndRenderPackages();
 }
+/**
+ * Fetches the project's package catalog from the extensions endpoint and
+ * renders the package cards into the content container, or an empty/error
+ * state. Uses a fetch token to discard stale responses that resolve after a
+ * project switch or a newer refresh.
+ */
 async function fetchAndRenderPackages() {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -85,6 +97,14 @@ async function fetchAndRenderPackages() {
         target.innerHTML = `<div class="empty-state"><div class="empty-state-text">${escHtml(t('packages.loadError', { error: msg }))}</div></div>`;
     }
 }
+/**
+ * Renders one package as a card showing its title, install status and
+ * version, a template badge for authoring scaffolds, honest gating notes for
+ * required services or credentials, its capabilities, and action buttons
+ * appropriate to its installed/active state.
+ * @param row - The package catalog row to render.
+ * @returns The card markup string.
+ */
 function renderPackageCard(row) {
     const statusChip = row.installed
         ? `<span style="font-size:11px;color:var(--text-muted);background:var(--bg-input);padding:2px 8px;border-radius:4px">${escHtml(t('packages.installed'))}${row.version ? ' · ' + escHtml(t('packages.version', { version: row.version })) : ''}</span>`
@@ -95,6 +115,19 @@ function renderPackageCard(row) {
     const templateBadge = row.category === 'template'
         ? `<span style="font-size:11px;color:var(--text-secondary);background:var(--bg-accent);padding:2px 8px;border-radius:4px" data-i18n="packages.templateBadge">${escHtml(t('packages.templateBadge'))}</span>`
         : '';
+    // A package with no published release is shown, because hiding it would make
+    // the catalog look complete while the fleet plainly contains it — but it is
+    // shown as unavailable, never with an install action that cannot succeed.
+    const unreleased = row.availability === 'unreleased';
+    const unreleasedBadge = unreleased
+        ? `<span style="font-size:11px;color:var(--text-secondary);background:var(--bg-accent);padding:2px 8px;border-radius:4px" data-i18n="packages.unreleasedBadge">${escHtml(t('packages.unreleasedBadge'))}</span>`
+        : '';
+    // The explanation is about not being installable, so it only applies while
+    // the package is not installed. Showing it beside an installed package would
+    // contradict the card's own status chip.
+    const unreleasedNote = unreleased && !row.installed
+        ? `<div class="pkg-req" style="font-size:12px;color:var(--text-secondary);margin-top:6px">🚧 ${escHtml(t('packages.unreleased'))}</div>`
+        : '';
     // Honest gating explanations — the UI must not promise a one-click install
     // for a package that needs a Neo4j instance or an API token.
     const serviceNote = row.requiresService
@@ -114,7 +147,15 @@ function renderPackageCard(row) {
     // a raw DOM string — and the server validates it against the catalog again
     // before any pm command is spawned.
     let actions = '';
-    if (!row.installed) {
+    if (unreleased && !row.installed) {
+        // Nothing to install: there is no published version to install from. An
+        // unreleased package that IS installed — from a local path or a
+        // preexisting install — keeps its full management controls below, because
+        // the server supports deactivating and removing it and hiding those would
+        // strand the user with a package they cannot get rid of.
+        actions = '';
+    }
+    else if (!row.installed) {
         actions = `<button class="btn btn-primary btn-sm" style="width:100%" data-pkg-action="install" data-pkg-name="${escHtml(row.name)}">${escHtml(t('packages.install'))}</button>`;
     }
     else if (row.active && row.enabled) {
@@ -136,20 +177,27 @@ function renderPackageCard(row) {
       <div class="card-header" style="display:flex;align-items:center;justify-content:space-between;gap:8px">
         <div style="display:flex;align-items:center;gap:6px">
           <div class="card-title">${escHtml(row.title)}</div>
-          ${templateBadge}
+          ${templateBadge}${unreleasedBadge}
         </div>
-        ${statusChip}
+        ${unreleased && !row.installed ? '' : statusChip}
       </div>
       <div class="card-body" style="padding-top:0">
         <div style="font-size:12px;color:var(--text-muted);margin-bottom:8px;line-height:1.4">${escHtml(row.description)}</div>
-        ${serviceNote}${credNotes}${caps}
-        <div style="margin-top:12px">${actions}</div>
+        ${unreleasedNote}${serviceNote}${credNotes}${caps}
+        ${actions ? `<div style="margin-top:12px">${actions}</div>` : ''}
       </div>
     </div>`;
 }
 // Delegate clicks on package action buttons so each card stays simple and the
 // handler resolves the action + name from data attributes, then calls the
 // server-validated extensions route.
+/**
+ * Installs a delegated click handler on the given container that routes
+ * package action button clicks (install/activate/deactivate/uninstall) to the
+ * package action handler, reading the action and package name from data
+ * attributes.
+ * @param root - The container element capturing the clicks.
+ */
 function wirePackageActions(root) {
     root.addEventListener('click', (ev) => {
         const btn = ev.target.closest('[data-pkg-action]');
@@ -162,6 +210,16 @@ function wirePackageActions(root) {
         void handlePackageAction(name, action, btn);
     });
 }
+/**
+ * Performs a package action against the extensions route for the current
+ * project. Disables and marks the clicked button while in flight, confirms
+ * before uninstalling, picks the HTTP method and URL suffix from the action,
+ * toasts the result, and re-renders the package list. Restores the button on
+ * failure.
+ * @param name - The catalog name of the target package.
+ * @param action - One of install, activate, deactivate, or uninstall.
+ * @param btn - The button element that triggered the action.
+ */
 async function handlePackageAction(name, action, btn) {
     const pid = state.currentProject?.id;
     if (!pid)
@@ -198,6 +256,10 @@ async function handlePackageAction(name, action, btn) {
 }
 // Wire the delegated action handler once the view container exists.
 let actionsWired = false;
+/**
+ * Wires the delegated package action handler onto the #content-packages
+ * container exactly once, guarded by the actionsWired flag.
+ */
 function ensureActionsWired() {
     if (actionsWired)
         return;