@unbrained/pm-web 2026.8.7 → 2026.8.14

package/public/src/views/packages.ts

@@ -60,6 +60,12 @@ let currentPackages: PackageRow[] = [];
  */
 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(): Promise<void> {
   ensureActionsWired();
   const el = document.getElementById('content-packages');
@@ -82,6 +88,12 @@ export async function renderPackagesView(): Promise<void> {
   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(): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -111,6 +123,14 @@ async function fetchAndRenderPackages(): Promise<void> {
   }
 }
 
+/**
+ * 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: PackageRow): string {
   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>`
@@ -180,6 +200,13 @@ function renderPackageCard(row: PackageRow): string {
 // 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: HTMLElement): void {
   root.addEventListener('click', (ev: MouseEvent) => {
     const btn = (ev.target as HTMLElement).closest<HTMLButtonElement>('[data-pkg-action]');
@@ -191,6 +218,16 @@ function wirePackageActions(root: HTMLElement): void {
   });
 }
 
+/**
+ * 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: string, action: string, btn: HTMLButtonElement): Promise<void> {
   const pid = state.currentProject?.id;
   if (!pid) return;
@@ -226,6 +263,10 @@ async function handlePackageAction(name: string, action: string, btn: HTMLButton
 
 // 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(): void {
   if (actionsWired) return;
   const root = document.getElementById('content-packages');

package/public/src/views/plan-execution.js

@@ -8,6 +8,7 @@ function normalizeStepRef(step, index) {
     const candidate = (step.ref || step.id || '').trim();
     return candidate || `step-${index + 1}`;
 }
+/** Returns the de-duplicated, trimmed dependency refs declared on a step, accepting either the camelCase or snake_case dependency field. */
 function normalizeDependsOn(step) {
     const raw = Array.isArray(step.dependsOn)
         ? step.dependsOn
@@ -23,6 +24,7 @@ function normalizeDependsOn(step) {
 function formatStepLine(step) {
     return `- [${step.ref}] ${step.title}`;
 }
+/** Returns a human-readable reason a step is waiting — joining its incomplete dependencies and unresolved (missing) ones — or the literal "waiting" when there are none. */
 function formatWaitReason(step) {
     const blockers = [
         ...step.incompleteDependencies,
@@ -32,12 +34,14 @@ function formatWaitReason(step) {
         return 'waiting';
     return `waiting on ${blockers.join(', ')}`;
 }
+/** Returns the combined list of a step's incomplete dependencies and its unresolved (missing) dependencies, with each missing ref suffixed by " (missing)". */
 function stepDependencyBlockers(step) {
     return [
         ...step.incompleteDependencies,
         ...step.unresolvedDependencies.map(dep => `${dep} (missing)`),
     ];
 }
+/** Builds an execution snapshot from raw plan steps: normalizes each step, resolves dependencies against completed steps, and partitions the not-done steps into ready, waiting, and blocked buckets along with completion percentage and the next ready step. */
 export function buildPlanExecutionSnapshot(steps) {
     const normalized = steps.map((step, index) => {
         const status = normalizeStatus(step.status);
@@ -107,6 +111,7 @@ export function buildPlanExecutionSnapshot(steps) {
         nextReadyStep: readySteps[0] || null,
     };
 }
+/** Builds a markdown agent brief for a plan, summarizing plan metadata and the ready, waiting, and blocked steps from the execution snapshot, closing with a single execution instruction. */
 export function buildPlanAgentBrief(plan, snapshot) {
     const title = (plan.title || plan.id || '(untitled)').trim();
     const lines = [
@@ -146,6 +151,7 @@ export function buildPlanAgentBrief(plan, snapshot) {
     lines.push('', 'Instruction:', 'Pick the top ready step, execute it end-to-end, and report tests/evidence before moving to the next.');
     return lines.join('\n');
 }
+/** Builds a markdown prompt for executing the next ready step (or the step matching stepRef), including its readiness, satisfied or pending dependencies, and execution requirements; returns a no-ready-step message when none applies. */
 export function buildNextStepPrompt(plan, snapshot, stepRef) {
     const step = stepRef ? snapshot.stepByRef[stepRef] : snapshot.nextReadyStep;
     if (!step) {

package/public/src/views/plan-execution.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-execution.js","sourceRoot":"","sources":["plan-execution.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan-execution.js","sourceRoot":"","sources":["plan-execution.ts"],"names":[],"mappings":"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"}

package/public/src/views/plan-execution.ts

@@ -18,6 +18,7 @@ type PlanInput = {
   status?: string;
 };
 
+/** A normalized plan step carrying its status and dependency refs plus derived readiness, including the done/blocked flags and the lists of dependencies that are missing or still incomplete. */
 export type AnalyzedPlanStep = {
   ref: string;
   title: string;
@@ -32,6 +33,7 @@ export type AnalyzedPlanStep = {
   original: PlanStepInput;
 };
 
+/** Aggregated execution state for a plan: step counts, the waiting/ready/blocked/all step lists, a ref-to-step lookup map, completion percentage, and the next ready step (if any). */
 export type PlanExecutionSnapshot = {
   totalSteps: number;
   completedSteps: number;
@@ -58,6 +60,7 @@ function normalizeStepRef(step: PlanStepInput, index: number): string {
   return candidate || `step-${index + 1}`;
 }
 
+/** Returns the de-duplicated, trimmed dependency refs declared on a step, accepting either the camelCase or snake_case dependency field. */
 function normalizeDependsOn(step: PlanStepInput): string[] {
   const raw = Array.isArray(step.dependsOn)
     ? step.dependsOn
@@ -74,6 +77,7 @@ function formatStepLine(step: AnalyzedPlanStep): string {
   return `- [${step.ref}] ${step.title}`;
 }
 
+/** Returns a human-readable reason a step is waiting — joining its incomplete dependencies and unresolved (missing) ones — or the literal "waiting" when there are none. */
 function formatWaitReason(step: AnalyzedPlanStep): string {
   const blockers = [
     ...step.incompleteDependencies,
@@ -83,6 +87,7 @@ function formatWaitReason(step: AnalyzedPlanStep): string {
   return `waiting on ${blockers.join(', ')}`;
 }
 
+/** Returns the combined list of a step's incomplete dependencies and its unresolved (missing) dependencies, with each missing ref suffixed by " (missing)". */
 function stepDependencyBlockers(step: AnalyzedPlanStep): string[] {
   return [
     ...step.incompleteDependencies,
@@ -90,6 +95,7 @@ function stepDependencyBlockers(step: AnalyzedPlanStep): string[] {
   ];
 }
 
+/** Builds an execution snapshot from raw plan steps: normalizes each step, resolves dependencies against completed steps, and partitions the not-done steps into ready, waiting, and blocked buckets along with completion percentage and the next ready step. */
 export function buildPlanExecutionSnapshot(steps: PlanStepInput[]): PlanExecutionSnapshot {
   const normalized: AnalyzedPlanStep[] = steps.map((step, index) => {
     const status = normalizeStatus(step.status);
@@ -162,6 +168,7 @@ export function buildPlanExecutionSnapshot(steps: PlanStepInput[]): PlanExecutio
   };
 }
 
+/** Builds a markdown agent brief for a plan, summarizing plan metadata and the ready, waiting, and blocked steps from the execution snapshot, closing with a single execution instruction. */
 export function buildPlanAgentBrief(plan: PlanInput, snapshot: PlanExecutionSnapshot): string {
   const title = (plan.title || plan.id || '(untitled)').trim();
   const lines: string[] = [
@@ -213,6 +220,7 @@ export function buildPlanAgentBrief(plan: PlanInput, snapshot: PlanExecutionSnap
   return lines.join('\n');
 }
 
+/** Builds a markdown prompt for executing the next ready step (or the step matching stepRef), including its readiness, satisfied or pending dependencies, and execution requirements; returns a no-ready-step message when none applies. */
 export function buildNextStepPrompt(
   plan: PlanInput,
   snapshot: PlanExecutionSnapshot,

package/public/src/views/plan.js

@@ -15,6 +15,11 @@ let currentExecutionSnapshot = null;
 function stepRef(step) {
     return step.ref || step.id || '';
 }
+/**
+ * Returns a small colored HTML status badge for a plan step, mapping the step
+ * status (defaulting to pending) to a fixed color by lowercasing the status
+ * text.
+ */
 function stepStatusBadge(status) {
     const s = (status || 'pending').toLowerCase();
     const colors = {
@@ -28,6 +33,10 @@ function stepStatusBadge(status) {
     const color = colors[s] || 'var(--text-muted)';
     return `<span style="font-size:11px;padding:2px 7px;border-radius:4px;background:color-mix(in srgb,${color} 18%,transparent);color:${color};font-weight:600;letter-spacing:.3px">${escHtml(s)}</span>`;
 }
+/**
+ * Returns an HTML metric badge card showing an uppercase label and a colored
+ * value, used for the plan execution summary counts.
+ */
 function metricBadge(label, value, color) {
     return `
     <div style="padding:8px 10px;border-radius:8px;background:color-mix(in srgb,${color} 14%, var(--bg-card));border:1px solid color-mix(in srgb,${color} 28%, var(--border));min-width:95px">
@@ -35,6 +44,12 @@ function metricBadge(label, value, color) {
       <div style="font-size:14px;font-weight:600;color:${color};margin-top:2px">${escHtml(value)}</div>
     </div>`;
 }
+/**
+ * Returns inline HTML describing a step's dependency state: an empty string
+ * when the step has no dependencies, is done, or is blocked; a 'Dependencies
+ * complete' note when all are finished; or a 'Waiting on' note listing the
+ * incomplete and unresolved (missing) dependencies.
+ */
 function renderDependencyHint(analyzed) {
     if (!analyzed || analyzed.dependsOn.length === 0 || analyzed.isDone || analyzed.isBlocked)
         return '';
@@ -47,6 +62,12 @@ function renderDependencyHint(analyzed) {
     ];
     return `<div style="font-size:12px;color:var(--warning,#f59e0b);margin-top:3px">Waiting on: ${escHtml(blockers.join(', '))}</div>`;
 }
+/**
+ * Renders the Execution Focus card for a plan: a dependency-aware summary with
+ * copy buttons for the agent brief and next-step prompt, metric badges for the
+ * completed/ready/waiting/blocked counts, the next ready step, and previews of
+ * the waiting and blocked steps.
+ */
 function renderExecutionFocus(planId, snapshot) {
     const next = snapshot.nextReadyStep;
     const waitingPreview = snapshot.waitingSteps.slice(0, 2).map(step => {
@@ -103,6 +124,12 @@ function renderExecutionFocus(planId, snapshot) {
         : ''}
     </div>`;
 }
+/**
+ * Returns the HTML for a single plan step row: the step ref, title (struck
+ * through when done), status badge, description, dependency hint, and blocked
+ * reason, plus conditional action buttons to copy the step prompt, mark
+ * complete, block, or remove the step.
+ */
 function renderStepRow(step, planId, analyzed) {
     const ref = stepRef(step);
     const isDone = ['done', 'completed'].includes((step.status || '').toLowerCase());
@@ -134,6 +161,11 @@ function renderStepRow(step, planId, analyzed) {
     </div>`;
 }
 // ─── Render ──────────────────────────────────────────────────
+/**
+ * Returns the top-level HTML markup for the Plans view: a page header with New
+ * Plan and Refresh buttons and a two-panel layout holding the plan list and
+ * detail panels.
+ */
 export function renderPlanView() {
     return `
     <div class="page-header">
@@ -157,6 +189,11 @@ export function renderPlanView() {
       </div>
     </div>`;
 }
+/**
+ * Initializes the Plans view into the page and resets the currently selected
+ * plan state. Shows a no-project empty state and returns when no project is
+ * selected; otherwise renders the view and loads the plan list.
+ */
 export async function initPlanView() {
     const el = document.getElementById('content-plan');
     if (!el)
@@ -171,6 +208,12 @@ export async function initPlanView() {
     el.innerHTML = renderPlanView();
     await loadPlanList();
 }
+/**
+ * Fetches all plans for the current project and renders them as clickable
+ * sidebar entries in the plan list panel, updating the subtitle to the project
+ * name. Clears the current plan when there are none, and shows an error state
+ * if the request fails.
+ */
 async function loadPlanList() {
     const listEl = document.getElementById('plan-list-panel');
     const subEl = document.getElementById('plan-subtitle');
@@ -206,6 +249,13 @@ async function loadPlanList() {
         listEl.innerHTML = `<div class="empty-state" style="padding:16px"><div class="empty-state-text">Error: ${escHtml(err instanceof Error ? err.message : String(err))}</div></div>`;
     }
 }
+/**
+ * Loads a plan into the detail panel by id, highlighting it in the list and
+ * building a dependency-aware execution snapshot. Renders a card with
+ * approve/materialize/edit/delete actions, the description and scope, the
+ * execution focus summary, and the list of step rows with an add-step button.
+ * Shows an error state if the fetch fails.
+ */
 export async function openPlanDetail(planId) {
     currentPlanId = planId;
     // Highlight selected in list
@@ -345,6 +395,11 @@ export async function openPlanDetail(planId) {
     }
 }
 // ─── Modal builders ──────────────────────────────────────────
+/**
+ * Opens the New Plan modal with fields for title, description, scope, tags, and
+ * priority. Shows an info toast and returns early when no project is currently
+ * selected.
+ */
 export function openCreatePlanModal() {
     if (!state.currentProject) {
         toast('Select a project first', 'info');
@@ -383,6 +438,11 @@ export function openCreatePlanModal() {
      <button class="btn btn-ghost" onclick="window.__app.hideModal('create-plan-modal')">Cancel</button>`);
     showModal('create-plan-modal');
 }
+/**
+ * Submits the New Plan form, requiring a title, and posts the plan fields to
+ * the plan endpoint. On success it closes the modal, toasts confirmation, and
+ * reloads the plan list.
+ */
 export async function submitCreatePlan() {
     if (!state.currentProject)
         return;
@@ -414,6 +474,11 @@ export async function submitCreatePlan() {
         toast(err instanceof Error ? err.message : 'Failed to create plan', 'error');
     }
 }
+/**
+ * Opens the Add Step modal for the given plan with title, description, and
+ * depends-on fields, wiring its submit button to submitAddStep with the plan
+ * id.
+ */
 export function openAddStepModal(planId) {
     createModal('add-step-modal', 'Add Step', `
     <div class="form-group">
@@ -431,6 +496,11 @@ export function openAddStepModal(planId) {
      <button class="btn btn-ghost" onclick="window.__app.hideModal('add-step-modal')">Cancel</button>`);
     showModal('add-step-modal');
 }
+/**
+ * Submits the Add Step form for a plan, requiring a title, and posts the step
+ * fields to the plan's steps endpoint. On success it closes the modal, toasts
+ * confirmation, and reopens the plan detail to show the new step.
+ */
 export async function submitAddStep(planId) {
     if (!state.currentProject)
         return;
@@ -456,6 +526,10 @@ export async function submitAddStep(planId) {
         toast(err instanceof Error ? err.message : 'Failed to add step', 'error');
     }
 }
+/**
+ * Marks the given plan step complete by posting to the step's complete
+ * endpoint, then toasts confirmation and reopens the plan detail.
+ */
 export async function planCompleteStep(planId, stepRef) {
     if (!state.currentProject)
         return;
@@ -468,6 +542,11 @@ export async function planCompleteStep(planId, stepRef) {
         toast(err instanceof Error ? err.message : 'Failed to complete step', 'error');
     }
 }
+/**
+ * Opens the Block Step modal for the given plan step, collecting a required
+ * reason and wiring its submit button to submitBlockStep with the plan id and
+ * step ref.
+ */
 export function planBlockStepPrompt(planId, stepRef) {
     createModal('block-step-modal', 'Block Step', `
     <div class="form-group">
@@ -477,6 +556,11 @@ export function planBlockStepPrompt(planId, stepRef) {
      <button class="btn btn-ghost" onclick="window.__app.hideModal('block-step-modal')">Cancel</button>`);
     showModal('block-step-modal');
 }
+/**
+ * Submits the Block Step form, requiring a reason, and posts it to the step's
+ * block endpoint. On success it closes the modal, toasts confirmation, and
+ * reopens the plan detail.
+ */
 export async function submitBlockStep(planId, stepRef) {
     if (!state.currentProject)
         return;
@@ -495,6 +579,11 @@ export async function submitBlockStep(planId, stepRef) {
         toast(err instanceof Error ? err.message : 'Failed to block step', 'error');
     }
 }
+/**
+ * Removes a plan step after confirming with the user, DELETEing it from the
+ * plan's steps endpoint. On success it toasts confirmation and reopens the plan
+ * detail.
+ */
 export function planRemoveStep(planId, stepRef) {
     confirmDialog('Remove step', `Remove step ${stepRef} from plan?`, async () => {
         if (!state.currentProject)
@@ -509,6 +598,10 @@ export function planRemoveStep(planId, stepRef) {
         }
     }, true);
 }
+/**
+ * Approves a plan after confirming with the user by posting to the plan's
+ * approve endpoint, then toasts confirmation and reopens the plan detail.
+ */
 export function planApprove(planId) {
     confirmDialog('Approve plan', `Approve plan ${planId}? Once approved, it can be materialized.`, async () => {
         if (!state.currentProject)
@@ -523,6 +616,11 @@ export function planApprove(planId) {
         }
     });
 }
+/**
+ * Opens the Materialize Plan modal for the given plan, offering fields for item
+ * type, a parent item id, and which steps to materialize, wiring its submit
+ * button to submitMaterializePlan with the plan id.
+ */
 export function planMaterializePrompt(planId) {
     createModal('materialize-plan-modal', 'Materialize Plan', `
     <p style="font-size:13px;color:var(--text-secondary);margin-bottom:12px">Materializing creates real project items from plan steps.</p>
@@ -547,6 +645,12 @@ export function planMaterializePrompt(planId) {
      <button class="btn btn-ghost" onclick="window.__app.hideModal('materialize-plan-modal')">Cancel</button>`);
     showModal('materialize-plan-modal');
 }
+/**
+ * Submits the Materialize Plan form, posting the chosen item type, parent item,
+ * and steps to the plan's materialize endpoint to create real items. On success
+ * it closes the modal, toasts confirmation, and switches to the Items view
+ * after a short delay.
+ */
 export async function submitMaterializePlan(planId) {
     if (!state.currentProject)
         return;
@@ -571,6 +675,12 @@ export async function submitMaterializePlan(planId) {
         toast(err instanceof Error ? err.message : 'Failed to materialize plan', 'error');
     }
 }
+/**
+ * Copies text to the clipboard and toasts the success message when the
+ * Clipboard API is available. When clipboard access is unavailable or blocked,
+ * opens a modal with a prefilled, selected textarea for manual copy and toasts
+ * an info notice instead.
+ */
 async function copyTextWithFallback(modalTitle, text, successMessage) {
     if (navigator.clipboard?.writeText) {
         try {
@@ -595,6 +705,11 @@ async function copyTextWithFallback(modalTitle, text, successMessage) {
     }
     toast('Clipboard blocked. Opened manual copy panel.', 'info');
 }
+/**
+ * Returns the currently open plan and its execution snapshot when the requested
+ * plan id matches the active plan; otherwise toasts an info notice and returns
+ * null so prompt generators bail out.
+ */
 function getCurrentPlanContext(planId) {
     const activeId = currentPlanData?.id || currentPlanId;
     if (!currentPlanData || !currentExecutionSnapshot || activeId !== planId) {
@@ -603,6 +718,11 @@ function getCurrentPlanContext(planId) {
     }
     return { plan: currentPlanData, snapshot: currentExecutionSnapshot };
 }
+/**
+ * Builds the dependency-aware agent brief for the currently open plan and
+ * copies it via copyTextWithFallback, first confirming the plan is open using
+ * its id.
+ */
 export async function copyPlanAgentBrief(planId) {
     const ctx = getCurrentPlanContext(planId);
     if (!ctx)
@@ -610,6 +730,12 @@ export async function copyPlanAgentBrief(planId) {
     const brief = buildPlanAgentBrief(ctx.plan, ctx.snapshot);
     await copyTextWithFallback('Plan Agent Brief', brief, 'Agent brief copied');
 }
+/**
+ * Builds and copies an execution prompt for a specific plan step, or for the
+ * next ready step when no ref is given. Validates that the requested step
+ * exists (or that a ready step exists), then copies the prompt via
+ * copyTextWithFallback.
+ */
 export async function copyPlanNextStepPrompt(planId, stepRef) {
     const ctx = getCurrentPlanContext(planId);
     if (!ctx)
@@ -625,6 +751,11 @@ export async function copyPlanNextStepPrompt(planId, stepRef) {
     const prompt = buildNextStepPrompt(ctx.plan, ctx.snapshot, stepRef);
     await copyTextWithFallback('Next Step Prompt', prompt, 'Next-step prompt copied');
 }
+/**
+ * Opens the Edit Plan modal with the title pre-filled, asynchronously
+ * populates the description by re-fetching the plan, and wires the submit
+ * button to submitEditPlan with the plan id.
+ */
 export function planEditPrompt(planId, currentTitle) {
     createModal('edit-plan-modal', 'Edit Plan', `
     <div class="form-group">
@@ -645,6 +776,11 @@ export function planEditPrompt(planId, currentTitle) {
             el.value = desc;
     }).catch(() => { });
 }
+/**
+ * Submits the Edit Plan form, requiring a title, and PATCHes the title and
+ * description to the plan endpoint. On success it closes the modal, toasts
+ * confirmation, and reloads both the plan list and the plan detail.
+ */
 export async function submitEditPlan(planId) {
     if (!state.currentProject)
         return;
@@ -665,6 +801,11 @@ export async function submitEditPlan(planId) {
         toast(err instanceof Error ? err.message : 'Failed to update plan', 'error');
     }
 }
+/**
+ * Deletes a plan after confirming with the user by DELETEing it from the plan
+ * endpoint. On success it toasts confirmation, clears the active plan state and
+ * detail panel, and reloads the plan list.
+ */
 export function planDeletePrompt(planId) {
     confirmDialog('Delete plan', `Delete plan ${planId} and all its steps? This cannot be undone.`, async () => {
         if (!state.currentProject)
@@ -686,5 +827,9 @@ export function planDeletePrompt(planId) {
     }, true);
 }
 // Expose currentPlanId for potential external use
+/**
+ * Returns the id of the currently selected plan, or null when no plan is
+ * selected.
+ */
 export function getCurrentPlanId() { return currentPlanId; }
 //# sourceMappingURL=plan.js.map