@unbrained/pm-web 2026.8.10 → 2026.8.14

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2026.8.14 - 2026-08-14
+
+### Fixed
+
+- The pm CLI dependency was an unpinned range in a package whose production image installs without dev dependencies ([pm-web-swb5](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-swb5.toon))
+
+## 2026.8.10 - 2026-08-10
+
+### Fixed
+
+- SW mutation queue: IndexedDB read failure indistinguishable from empty queue ([pm-web-zz37](https://github.com/unbraind/pm-web/blob/main/.agents/pm/bugs/pm-web-zz37.toon))
+
+### Other
+
+- Adopt canonical pm-ops docstring gate and reach 100% docstring coverage ([pm-web-mglt](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-mglt.toon))
+
 ## 2026.8.7 - 2026-08-07
 
 ### Fixed

package/dist/app.d.ts

@@ -17,6 +17,22 @@ import { type Express } from "express";
 export declare const LEGAL_PAGES: readonly ["legal-notice", "privacy-policy", "terms", "cookie-settings"];
 /** German short-path aliases that 308-redirect to the canonical legal pages. */
 export declare const LEGAL_REDIRECTS: Record<string, string>;
+/**
+ * Resolve the directory that serves the standalone legal-page HTML.
+ *
+ * With no `PM_WEB_LEGAL_DIR` configured (or a blank value) the bundled
+ * `public/` directory is returned, whose placeholder templates are English.
+ * When an operator overlay is set it is validated strictly before use: the path
+ * must be absolute, must `realpath`-resolve to a real directory, and every one
+ * of the {@link LEGAL_PAGES} must exist there as a regular (non-symlink) file
+ * whose real path stays inside the overlay root and is readable. Any failure
+ * throws with a specific message, so a half-configured overlay never silently
+ * falls back to the placeholders.
+ *
+ * @param env - Environment to read `PM_WEB_LEGAL_DIR` from; defaults to
+ *   `process.env` so callers (and tests) can inject a controlled environment.
+ * @returns The real, resolved directory path holding the legal HTML files.
+ */
 export declare function resolveLegalPagesDir(env?: NodeJS.ProcessEnv): string;
 /**
  * Build the Express application with all middleware, static assets, legal

package/dist/app.js

@@ -42,6 +42,22 @@ export const LEGAL_REDIRECTS = {
     "/agb": "/terms",
     "/cookies": "/cookie-settings",
 };
+/**
+ * Resolve the directory that serves the standalone legal-page HTML.
+ *
+ * With no `PM_WEB_LEGAL_DIR` configured (or a blank value) the bundled
+ * `public/` directory is returned, whose placeholder templates are English.
+ * When an operator overlay is set it is validated strictly before use: the path
+ * must be absolute, must `realpath`-resolve to a real directory, and every one
+ * of the {@link LEGAL_PAGES} must exist there as a regular (non-symlink) file
+ * whose real path stays inside the overlay root and is readable. Any failure
+ * throws with a specific message, so a half-configured overlay never silently
+ * falls back to the placeholders.
+ *
+ * @param env - Environment to read `PM_WEB_LEGAL_DIR` from; defaults to
+ *   `process.env` so callers (and tests) can inject a controlled environment.
+ * @returns The real, resolved directory path holding the legal HTML files.
+ */
 export function resolveLegalPagesDir(env = process.env) {
     const configured = env.PM_WEB_LEGAL_DIR?.trim();
     if (!configured)

package/dist/app.js.map

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

package/dist/auth.d.ts

@@ -1,4 +1,9 @@
 import type { Request, Response } from "express";
+/**
+ * Claims encoded into a pm-web session JWT: the authenticated user's stable id
+ * and email, both set by the OIDC login flow and later restored by
+ * `verifyToken`.
+ */
 export interface JwtPayload {
     userId: string;
     email: string;

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,cAAc,CAAC;AAE/B,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACpE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;AAC3G,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B,IAAI,CAAC,UAAU,EAAE,CAAC;IAChB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;AAC/E,CAAC;AAOD,MAAM,UAAU,SAAS,CAAC,OAAmB;IAC3C,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAa,EAAE,OAAmB;IACjE,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE;QAC5B,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAC7C,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;KACjC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAe,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;IAC7C,IAAI,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,MAAM,GAAI,GAAsD,CAAC,OAAO,EAAE,QAAQ,CAAC;IACzF,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,yEAAyE;IACzE,uEAAuE;IACvE,4EAA4E;IAC5E,MAAM,UAAU,GAAI,GAAG,CAAC,KAA6C,EAAE,CAAC,OAAO,CAAC,CAAC;IACjF,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,cAAc,CAAC;AAE/B,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACpE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;AAC3G,MAAM,WAAW,GAAG,KAAK,CAAC;AAE1B,IAAI,CAAC,UAAU,EAAE,CAAC;IAChB,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;AAC/E,CAAC;AAYD,MAAM,UAAU,SAAS,CAAC,OAAmB;IAC3C,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAa,EAAE,OAAmB;IACjE,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE;QAC5B,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAC7C,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;KACjC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAe,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;IAC7C,IAAI,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,MAAM,GAAI,GAAsD,CAAC,OAAO,EAAE,QAAQ,CAAC;IACzF,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,yEAAyE;IACzE,uEAAuE;IACvE,4EAA4E;IAC5E,MAAM,UAAU,GAAI,GAAG,CAAC,KAA6C,EAAE,CAAC,OAAO,CAAC,CAAC;IACjF,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/board.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Minimal projection of a pm item used by the pure board/search helpers: a
+ * stable id plus the optional text fields the kanban columns and full-text
+ * filter read. Callers cast richer item shapes to this narrow view.
+ */
 export type BoardItem = {
     id: string;
     title?: string;
@@ -6,10 +11,58 @@ export type BoardItem = {
     body?: string;
     description?: string;
 };
+/**
+ * Coerce an arbitrary status value into a normalized board-column key.
+ *
+ * A non-empty string is trimmed and used; anything else (or a blank string)
+ * falls back to `"open"`. The result is then lowercased and has each run of
+ * whitespace or hyphens replaced with a single underscore, so `"In Progress"`,
+ * `"in-progress"` and `"in progress"` all map to `in_progress`.
+ *
+ * @param value - The raw `status` field from an item; type is `unknown` because
+ *   imported items can carry non-string values.
+ * @returns The normalized, lowercase, underscore-separated status key.
+ */
 export declare function normalizeStatusKey(value: unknown): string;
+/**
+ * Normalize an item's `tags` field into a trimmed, blank-free string array.
+ *
+ * An array has each entry stringified and trimmed; a string is split on commas;
+ * any other type yields an empty array. Empty fragments are dropped in every
+ * case, so `"a, ,b"` becomes `["a", "b"]`.
+ *
+ * @param value - The raw `tags` field from an item.
+ * @returns The list of non-empty tag strings.
+ */
 export declare function normalizeItemTags(value: unknown): string[];
+/**
+ * Group items into board columns keyed by the workspace's actual statuses.
+ *
+ * The supplied `statuses` (from `pm contracts`) define the ordered columns; if
+ * none are given a default `open / in_progress / blocked / closed` set is used.
+ * Each status is matched case- and separator-insensitively via
+ * {@link normalizeStatusKey}, so items land in the intended column regardless of
+ * capitalization. Items whose status matches no known column are collected into
+ * a trailing `(other)` column so nothing is silently dropped. Columns are
+ * returned in declared-status order, with `(other)` appended when first needed.
+ *
+ * @param items - Items to distribute.
+ * @param statuses - The workspace's declared status labels.
+ * @returns Columns in declared-status order, each carrying its items.
+ */
 export declare function boardColumns<T extends BoardItem>(items: T[], statuses: string[]): Array<{
     status: string;
     items: T[];
 }>;
+/**
+ * Case-insensitive substring filter over an item's text fields.
+ *
+ * Matches against the concatenation of id, title, tags (normalized), body and
+ * description, lowercased. A blank query short-circuits and returns the input
+ * array unchanged. The original items are returned by reference, not copied.
+ *
+ * @param items - Items to filter.
+ * @param query - Free-text query; surrounding whitespace is ignored.
+ * @returns The items whose text fields contain the query substring.
+ */
 export declare function filterItemsByQuery<T extends BoardItem>(items: T[], query: string): T[];

package/dist/board.js

@@ -1,10 +1,32 @@
 // Pure, dependency-free helpers for the kanban board and search endpoints.
 // Kept in their own module (no db/neo4j imports) so they are unit-testable
 // without booting the server or a database.
+/**
+ * Coerce an arbitrary status value into a normalized board-column key.
+ *
+ * A non-empty string is trimmed and used; anything else (or a blank string)
+ * falls back to `"open"`. The result is then lowercased and has each run of
+ * whitespace or hyphens replaced with a single underscore, so `"In Progress"`,
+ * `"in-progress"` and `"in progress"` all map to `in_progress`.
+ *
+ * @param value - The raw `status` field from an item; type is `unknown` because
+ *   imported items can carry non-string values.
+ * @returns The normalized, lowercase, underscore-separated status key.
+ */
 export function normalizeStatusKey(value) {
     const raw = typeof value === "string" && value.trim() ? value.trim() : "open";
     return raw.toLowerCase().replace(/[\s-]+/g, "_");
 }
+/**
+ * Normalize an item's `tags` field into a trimmed, blank-free string array.
+ *
+ * An array has each entry stringified and trimmed; a string is split on commas;
+ * any other type yields an empty array. Empty fragments are dropped in every
+ * case, so `"a, ,b"` becomes `["a", "b"]`.
+ *
+ * @param value - The raw `tags` field from an item.
+ * @returns The list of non-empty tag strings.
+ */
 export function normalizeItemTags(value) {
     if (Array.isArray(value))
         return value.map(String).map((tag) => tag.trim()).filter(Boolean);
@@ -16,6 +38,21 @@ export function normalizeItemTags(value) {
 // (from `pm contracts`), so the kanban board reflects whatever statuses the
 // installed pm CLI + extensions define. Items with an unlisted status fall into
 // a trailing "(other)" column so nothing is silently dropped.
+/**
+ * Group items into board columns keyed by the workspace's actual statuses.
+ *
+ * The supplied `statuses` (from `pm contracts`) define the ordered columns; if
+ * none are given a default `open / in_progress / blocked / closed` set is used.
+ * Each status is matched case- and separator-insensitively via
+ * {@link normalizeStatusKey}, so items land in the intended column regardless of
+ * capitalization. Items whose status matches no known column are collected into
+ * a trailing `(other)` column so nothing is silently dropped. Columns are
+ * returned in declared-status order, with `(other)` appended when first needed.
+ *
+ * @param items - Items to distribute.
+ * @param statuses - The workspace's declared status labels.
+ * @returns Columns in declared-status order, each carrying its items.
+ */
 export function boardColumns(items, statuses) {
     const known = (statuses.length > 0 ? statuses : ["open", "in_progress", "blocked", "closed"])
         .map((status) => String(status).trim())
@@ -43,6 +80,17 @@ export function boardColumns(items, statuses) {
     return [...columns.entries()].map(([status, list]) => ({ status, items: list }));
 }
 // Case-insensitive full-text filter over id, title, tags and body.
+/**
+ * Case-insensitive substring filter over an item's text fields.
+ *
+ * Matches against the concatenation of id, title, tags (normalized), body and
+ * description, lowercased. A blank query short-circuits and returns the input
+ * array unchanged. The original items are returned by reference, not copied.
+ *
+ * @param items - Items to filter.
+ * @param query - Free-text query; surrounding whitespace is ignored.
+ * @returns The items whose text fields contain the query substring.
+ */
 export function filterItemsByQuery(items, query) {
     const q = query.trim().toLowerCase();
     if (!q)

package/dist/board.js.map

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

package/dist/crypto.d.ts

@@ -1,2 +1,25 @@
+/**
+ * Encrypt a secret (a GitHub access token) for at-rest storage.
+ *
+ * Uses AES-256-GCM with a random 12-byte IV and a key derived as SHA-256 of
+ * {@link secretMaterial}. Returns a single self-describing string
+ * `pmweb:v1:<iv>:<authTag>:<ciphertext>`; the IV, auth tag, and ciphertext
+ * are base64url-encoded, while `pmweb:v1` remains a literal prefix that tags
+ * the format for {@link decryptSecret}.
+ *
+ * @param plainText - The plaintext secret to encrypt.
+ * @returns The prefixed, colon-separated token string.
+ */
 export declare function encryptSecret(plainText: string): string;
+/**
+ * Decrypt a value previously produced by {@link encryptSecret}.
+ *
+ * A nullish or empty input returns `null`, and a value without the `pmweb:v1:`
+ * prefix is returned unchanged (a legacy plaintext token passes through).
+ * Otherwise the IV, auth tag and ciphertext are parsed and decrypted with
+ * AES-256-GCM; a malformed string or failed authenticity check throws.
+ *
+ * @param stored - The stored token string, or null/undefined when none exists.
+ * @returns The recovered plaintext, or `null` for a missing value.
+ */
 export declare function decryptSecret(stored: string | null | undefined): string | null;

package/dist/crypto.js

@@ -1,5 +1,14 @@
 import crypto from "node:crypto";
 const TOKEN_PREFIX = "pmweb:v1";
+/**
+ * Resolve the shared secret used to derive the GitHub-token encryption key.
+ *
+ * Reads `PM_WEB_SECRET_KEY` first, then falls back to `JWT_SECRET`. Throws when
+ * neither is set or the value is shorter than 32 characters, because AES-256
+ * under a weak secret would expose stored tokens to offline brute force.
+ *
+ * @returns The raw secret string (at least 32 characters).
+ */
 function secretMaterial() {
     const value = process.env.PM_WEB_SECRET_KEY || process.env.JWT_SECRET;
     if (!value || value.length < 32) {
@@ -10,6 +19,18 @@ function secretMaterial() {
 function encryptionKey() {
     return crypto.createHash("sha256").update(secretMaterial(), "utf8").digest();
 }
+/**
+ * Encrypt a secret (a GitHub access token) for at-rest storage.
+ *
+ * Uses AES-256-GCM with a random 12-byte IV and a key derived as SHA-256 of
+ * {@link secretMaterial}. Returns a single self-describing string
+ * `pmweb:v1:<iv>:<authTag>:<ciphertext>`; the IV, auth tag, and ciphertext
+ * are base64url-encoded, while `pmweb:v1` remains a literal prefix that tags
+ * the format for {@link decryptSecret}.
+ *
+ * @param plainText - The plaintext secret to encrypt.
+ * @returns The prefixed, colon-separated token string.
+ */
 export function encryptSecret(plainText) {
     const iv = crypto.randomBytes(12);
     const cipher = crypto.createCipheriv("aes-256-gcm", encryptionKey(), iv);
@@ -22,6 +43,17 @@ export function encryptSecret(plainText) {
         encrypted.toString("base64url"),
     ].join(":");
 }
+/**
+ * Decrypt a value previously produced by {@link encryptSecret}.
+ *
+ * A nullish or empty input returns `null`, and a value without the `pmweb:v1:`
+ * prefix is returned unchanged (a legacy plaintext token passes through).
+ * Otherwise the IV, auth tag and ciphertext are parsed and decrypted with
+ * AES-256-GCM; a malformed string or failed authenticity check throws.
+ *
+ * @param stored - The stored token string, or null/undefined when none exists.
+ * @returns The recovered plaintext, or `null` for a missing value.
+ */
 export function decryptSecret(stored) {
     if (!stored)
         return null;

package/dist/crypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEhC,SAAS,cAAc;IACrB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IACtE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,+FAA+F,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,OAAO;QACL,YAAY;QACZ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;QACxB,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;QACzB,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC;KAChC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAiC;IAC7D,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,EAAE,AAAD,EAAG,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CACtC,aAAa,EACb,aAAa,EAAE,EACf,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAChC,CAAC;IACF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACvD,QAAQ,CAAC,KAAK,EAAE;KACjB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEhC;;;;;;;;GAQG;AACH,SAAS,cAAc;IACrB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IACtE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,+FAA+F,CAAC,CAAC;IACnH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,aAAa,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,OAAO;QACL,YAAY;QACZ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;QACxB,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC;QACzB,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC;KAChC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,MAAiC;IAC7D,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,EAAE,AAAD,EAAG,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CACtC,aAAa,EACb,aAAa,EAAE,EACf,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAChC,CAAC;IACF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACvD,QAAQ,CAAC,KAAK,EAAE;KACjB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}

package/dist/db.d.ts

@@ -7,5 +7,24 @@
  * server fails fast with guidance instead.
  */
 export declare function assertDbConfigured(): void;
+/**
+ * Shared PostgreSQL connection pool for all pm-web queries.
+ *
+ * Configured from {@link resolvePoolConfig} (DATABASE_URL or POSTGRES_* vars)
+ * with a generous default `max`; one client is permanently reserved for the
+ * LISTEN/NOTIFY channel, and `PM_WEB_DB_POOL_MAX` tunes capacity for larger
+ * multi-user deployments. Query code borrows from this pool rather than
+ * opening its own connections.
+ */
 export declare const pool: import("pg").Pool;
+/**
+ * Create the pm-web database schema, idempotently.
+ *
+ * Issues `CREATE TABLE IF NOT EXISTS` for users, projects, groups, group
+ * members, project shares, external (OIDC) identities, the admin audit log,
+ * and GitHub item links, plus their indexes; runs idempotent `ADD COLUMN IF
+ * NOT EXISTS` migrations for later-added columns; and, when
+ * `PM_WEB_BOOTSTRAP_ADMIN_EMAIL` is set, promotes that (lower-cased) user to
+ * admin. Safe to call on every boot.
+ */
 export declare function initSchema(): Promise<void>;

package/dist/db.js

@@ -42,6 +42,15 @@ export function assertDbConfigured() {
         "    export DATABASE_URL=postgres://user:pass@localhost:5432/pmweb\n" +
         "  (or provide POSTGRES_HOST + POSTGRES_DB and related POSTGRES_* vars).");
 }
+/**
+ * Shared PostgreSQL connection pool for all pm-web queries.
+ *
+ * Configured from {@link resolvePoolConfig} (DATABASE_URL or POSTGRES_* vars)
+ * with a generous default `max`; one client is permanently reserved for the
+ * LISTEN/NOTIFY channel, and `PM_WEB_DB_POOL_MAX` tunes capacity for larger
+ * multi-user deployments. Query code borrows from this pool rather than
+ * opening its own connections.
+ */
 export const pool = new Pool({
     ...resolvePoolConfig(),
     // One client is permanently reserved for LISTEN/NOTIFY. Keep request/query
@@ -53,6 +62,16 @@ export const pool = new Pool({
 const bootstrapAdminEmail = (process.env.PM_WEB_BOOTSTRAP_ADMIN_EMAIL || "")
     .trim()
     .toLowerCase();
+/**
+ * Create the pm-web database schema, idempotently.
+ *
+ * Issues `CREATE TABLE IF NOT EXISTS` for users, projects, groups, group
+ * members, project shares, external (OIDC) identities, the admin audit log,
+ * and GitHub item links, plus their indexes; runs idempotent `ADD COLUMN IF
+ * NOT EXISTS` migrations for later-added columns; and, when
+ * `PM_WEB_BOOTSTRAP_ADMIN_EMAIL` is set, promotes that (lower-cased) user to
+ * admin. Safe to call on every boot.
+ */
 export async function initSchema() {
     await pool.query(`
     CREATE TABLE IF NOT EXISTS pm_users (

package/dist/db.js.map

@@ -1 +1 @@
-{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAEpB;;;;;;;GAOG;AACH,SAAS,iBAAiB;IACxB,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QAC7B,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;IACxD,CAAC;IAED,oEAAoE;IACpE,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACzD,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,MAAM,EAAE,EAAE,CAAC;YACvD,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;YACvC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;SAClC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,UAAU,GACd,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QACjC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAChE,IAAI,UAAU;QAAE,OAAO;IACvB,MAAM,IAAI,KAAK,CACb,mEAAmE;QACjE,mCAAmC;QACnC,qEAAqE;QACrE,yEAAyE,CAC5E,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;IAC3B,GAAG,iBAAiB,EAAE;IACtB,2EAA2E;IAC3E,wEAAwE;IACxE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IAC5E,iBAAiB,EAAE,MAAM;IACzB,uBAAuB,EAAE,KAAK;CAC/B,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;KACzE,IAAI,EAAE;KACN,WAAW,EAAE,CAAC;AAEjB,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDhB,CAAC,CAAC;IAEH,0CAA0C;IAC1C,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;GAMhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;GAahB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd;;;;;;MAME,CACH,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CACd,yFAAyF,CAC1F,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;GAUhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd,6FAA6F,CAC9F,CAAC;IAEF,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,KAAK,CACd,wFAAwF,EACxF,CAAC,mBAAmB,CAAC,CACtB,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAEpB;;;;;;;GAOG;AACH,SAAS,iBAAiB;IACxB,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QAC7B,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;IACxD,CAAC;IAED,oEAAoE;IACpE,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACzD,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,MAAM,EAAE,EAAE,CAAC;YACvD,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;YACvC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;SAClC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,UAAU,GACd,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QACjC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAChE,IAAI,UAAU;QAAE,OAAO;IACvB,MAAM,IAAI,KAAK,CACb,mEAAmE;QACjE,mCAAmC;QACnC,qEAAqE;QACrE,yEAAyE,CAC5E,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;IAC3B,GAAG,iBAAiB,EAAE;IACtB,2EAA2E;IAC3E,wEAAwE;IACxE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IAC5E,iBAAiB,EAAE,MAAM;IACzB,uBAAuB,EAAE,KAAK;CAC/B,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;KACzE,IAAI,EAAE;KACN,WAAW,EAAE,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDhB,CAAC,CAAC;IAEH,0CAA0C;IAC1C,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;GAMhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;GAahB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd;;;;;;MAME,CACH,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CACd,yFAAyF,CAC1F,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;GAUhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd,6FAA6F,CAC9F,CAAC;IAEF,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,KAAK,CACd,wFAAwF,EACxF,CAAC,mBAAmB,CAAC,CACtB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/ical.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Minimal projection of a pm item used for iCalendar export: a stable id plus
+ * the optional fields the VEVENT builder reads (title, type, status, priority,
+ * deadline, assignee, tags). Only `deadline` is required to produce an event.
+ */
 export type CalendarItem = {
     id: string;
     title?: string;
@@ -8,17 +13,84 @@ export type CalendarItem = {
     assignee?: string;
     tags?: string[];
 };
+/**
+ * Options for {@link buildIcsCalendar}: the displayed calendar name, a stable
+ * UID domain suffix that keeps events from different projects from colliding
+ * in a multi-calendar client, and an optional fixed `now` to make output
+ * deterministic in tests.
+ */
 export type IcsOptions = {
     calendarName?: string;
     uidDomain?: string;
     now?: Date;
 };
+/**
+ * Escape a value for an RFC 5545 (§3.3.11) TEXT property.
+ *
+ * Prefixes backslash, and escapes semicolons, commas, and any newline variant
+ * (CRLF/CR/LF) as the literal `\n` sequence, so the value can be embedded in a
+ * property without breaking line or field structure.
+ *
+ * @param value - The raw text to escape.
+ * @returns The escaped text, safe to place after a property name and colon.
+ */
 export declare function icsEscapeText(value: string): string;
+/**
+ * Fold a content line to 75-octet segments per RFC 5545 (§3.1).
+ *
+ * Lines at or under 75 octets are returned unchanged; longer lines are split
+ * with the first segment taking 75 octets and each continuation taking 74 plus
+ * a single leading space, joined with CRLF. Folding is done on character
+ * boundaries, which is safe for the ASCII-dominant content pm produces.
+ *
+ * @param line - A single unfolded content line.
+ * @returns The line, folded into CRLF-joined 75-octet segments when needed.
+ */
 export declare function foldLine(line: string): string;
+/**
+ * Format a Date as a UTC `DATE-TIME` value (`YYYYMMDDTHHMMSSZ`, RFC 5545 form
+ * 2). Uses the UTC components of the date so the result is timezone-stable.
+ *
+ * @param d - The instant to format.
+ * @returns The UTC timestamp string ending in `Z`.
+ */
 export declare function formatUtcTimestamp(d: Date): string;
+/**
+ * Format a Date as an all-day `DATE` value (`YYYYMMDD`, RFC 5545 §3.3.4),
+ * using the UTC calendar date.
+ *
+ * @param d - The date to format.
+ * @returns The `YYYYMMDD` date string.
+ */
 export declare function formatDateValue(d: Date): string;
+/**
+ * Build a single VEVENT (RFC 5545) for a pm item that has a usable deadline.
+ *
+ * Returns `null` when the item has no deadline or one {@link parseDeadline}
+ * cannot read. Otherwise emits UID/DTSTAMP, all-day or timed DTSTART/DTEND,
+ * an escaped SUMMARY and DESCRIPTION (status/assignee/priority/tags), an iCal
+ * PRIORITY mapped from pm's 0–4 scale, CATEGORIES from tags, and a STATUS of
+ * CANCELLED for closed/canceled items (CONFIRMED otherwise). Each line is
+ * folded and the event is joined with CRLF.
+ *
+ * @param item - The item to render.
+ * @param opts - The UID domain suffix and the shared DTSTAMP value.
+ * @returns The folded VEVENT text, or `null` when the item has no deadline.
+ */
 export declare function itemToVevent(item: CalendarItem, opts: {
     uidDomain: string;
     dtstamp: string;
 }): string | null;
+/**
+ * Build a complete VCALENDAR document from pm items.
+ *
+ * Emits the VCALENDAR header (version, PRODID, calendar name), one VEVENT per
+ * item that has a usable deadline (items without one are skipped), and the
+ * closing tag, all CRLF-joined with a trailing CRLF per RFC 5545. The UID
+ * domain defaults to `pm-web` and is sanitized to hostname-safe characters.
+ *
+ * @param items - The items to export.
+ * @param opts - Optional calendar name, UID domain, and fixed `now` for tests.
+ * @returns The full iCalendar (.ics) document text.
+ */
 export declare function buildIcsCalendar(items: CalendarItem[], opts?: IcsOptions): string;

package/dist/ical.js

@@ -5,6 +5,16 @@
 // the pm CLI and hands the relevant fields here.
 // Escape a text value per RFC 5545 §3.3.11 (TEXT): backslash, semicolon,
 // comma and newlines must be escaped.
+/**
+ * Escape a value for an RFC 5545 (§3.3.11) TEXT property.
+ *
+ * Prefixes backslash, and escapes semicolons, commas, and any newline variant
+ * (CRLF/CR/LF) as the literal `\n` sequence, so the value can be embedded in a
+ * property without breaking line or field structure.
+ *
+ * @param value - The raw text to escape.
+ * @returns The escaped text, safe to place after a property name and colon.
+ */
 export function icsEscapeText(value) {
     return value
         .replace(/\\/g, "\\\\")
@@ -15,6 +25,17 @@ export function icsEscapeText(value) {
 // Fold long content lines to 75 octets per RFC 5545 §3.1. Continuation lines
 // begin with a single space. We fold on character boundaries which is safe for
 // the ASCII-dominant content pm produces.
+/**
+ * Fold a content line to 75-octet segments per RFC 5545 (§3.1).
+ *
+ * Lines at or under 75 octets are returned unchanged; longer lines are split
+ * with the first segment taking 75 octets and each continuation taking 74 plus
+ * a single leading space, joined with CRLF. Folding is done on character
+ * boundaries, which is safe for the ASCII-dominant content pm produces.
+ *
+ * @param line - A single unfolded content line.
+ * @returns The line, folded into CRLF-joined 75-octet segments when needed.
+ */
 export function foldLine(line) {
     if (line.length <= 75)
         return line;
@@ -30,18 +51,44 @@ export function foldLine(line) {
     return parts.join("\r\n");
 }
 // Format a Date as a UTC timestamp: YYYYMMDDTHHMMSSZ (RFC 5545 form 2).
+/**
+ * Format a Date as a UTC `DATE-TIME` value (`YYYYMMDDTHHMMSSZ`, RFC 5545 form
+ * 2). Uses the UTC components of the date so the result is timezone-stable.
+ *
+ * @param d - The instant to format.
+ * @returns The UTC timestamp string ending in `Z`.
+ */
 export function formatUtcTimestamp(d) {
     const p = (n, w = 2) => String(n).padStart(w, "0");
     return (`${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}` +
         `T${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}Z`);
 }
 // Format a Date as an all-day DATE value: YYYYMMDD (RFC 5545 §3.3.4).
+/**
+ * Format a Date as an all-day `DATE` value (`YYYYMMDD`, RFC 5545 §3.3.4),
+ * using the UTC calendar date.
+ *
+ * @param d - The date to format.
+ * @returns The `YYYYMMDD` date string.
+ */
 export function formatDateValue(d) {
     const p = (n) => String(n).padStart(2, "0");
     return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}`;
 }
 // A pm deadline may be a date-only string (YYYY-MM-DD) or a full ISO datetime.
 // Returns null for anything unparseable so callers can skip the item.
+/**
+ * Parse a pm deadline string into a date plus an all-day flag.
+ *
+ * Accepts a date-only `YYYY-MM-DD` value or a full ISO datetime; surrounding
+ * whitespace and empty strings yield `null`, as do values `new Date` cannot
+ * parse. A date-only value, or any instant that lands exactly on midnight UTC,
+ * is treated as an all-day event (which calendar clients render far better
+ * than a zero-length 00:00 event).
+ *
+ * @param raw - The raw deadline string from a pm item.
+ * @returns The parsed date and all-day flag, or `null` when unparseable.
+ */
 function parseDeadline(raw) {
     const trimmed = raw.trim();
     if (!trimmed)
@@ -62,6 +109,20 @@ function parseDeadline(raw) {
 }
 // Build a single VEVENT for a pm item with a deadline. Returns null when the
 // item has no usable deadline.
+/**
+ * Build a single VEVENT (RFC 5545) for a pm item that has a usable deadline.
+ *
+ * Returns `null` when the item has no deadline or one {@link parseDeadline}
+ * cannot read. Otherwise emits UID/DTSTAMP, all-day or timed DTSTART/DTEND,
+ * an escaped SUMMARY and DESCRIPTION (status/assignee/priority/tags), an iCal
+ * PRIORITY mapped from pm's 0–4 scale, CATEGORIES from tags, and a STATUS of
+ * CANCELLED for closed/canceled items (CONFIRMED otherwise). Each line is
+ * folded and the event is joined with CRLF.
+ *
+ * @param item - The item to render.
+ * @param opts - The UID domain suffix and the shared DTSTAMP value.
+ * @returns The folded VEVENT text, or `null` when the item has no deadline.
+ */
 export function itemToVevent(item, opts) {
     if (!item.deadline)
         return null;
@@ -114,6 +175,18 @@ export function itemToVevent(item, opts) {
 }
 // Build a complete VCALENDAR document from pm items. Items without a usable
 // deadline are skipped. Output uses CRLF line endings per RFC 5545 §3.1.
+/**
+ * Build a complete VCALENDAR document from pm items.
+ *
+ * Emits the VCALENDAR header (version, PRODID, calendar name), one VEVENT per
+ * item that has a usable deadline (items without one are skipped), and the
+ * closing tag, all CRLF-joined with a trailing CRLF per RFC 5545. The UID
+ * domain defaults to `pm-web` and is sanitized to hostname-safe characters.
+ *
+ * @param items - The items to export.
+ * @param opts - Optional calendar name, UID domain, and fixed `now` for tests.
+ * @returns The full iCalendar (.ics) document text.
+ */
 export function buildIcsCalendar(items, opts = {}) {
     const now = opts.now ?? new Date();
     const dtstamp = formatUtcTimestamp(now);