@jmfederico/pi-web 1.202607.2 → 1.202608.0

package/dist/pi-web-plugins/relays/relayDiscovery.js

@@ -0,0 +1,228 @@
+// Generated from pi-web-plugins/relays/relayDiscovery.ts. Do not edit directly.
+export const RELAYS_ROOT = ".pi-web/relays";
+/** Documents that anchor a relay packet, in display order. Any other files follow alphabetically. */
+export const RELAY_ANCHOR_DOCUMENTS = ["status.md", "charter.md", "log.md"];
+/**
+ * Deepest node depth listed below the relay root; direct children of the relay
+ * root are depth 0. Children of a directory at this depth are skipped and the
+ * listing is flagged partial instead of walking arbitrarily deep trees.
+ */
+export const MAX_RELAY_TREE_DEPTH = 5;
+/** Most documents listed across one relay; extras are skipped and the listing is flagged partial. */
+export const MAX_RELAY_DOCUMENTS = 200;
+/** Most directories walked in one relay; extras stay listed but unexplored and the listing is flagged partial. */
+export const MAX_RELAY_DIRECTORIES = 50;
+// The workspace file API rejects with these messages when a path is absent or
+// is not a directory. For the relays root both mean "zero relays", not a failure.
+const missingListingErrorMessages = new Set(["Path does not exist", "Path is not a directory"]);
+/** List the workspace's relays, most recently modified first. Never rejects. */
+export async function listWorkspaceRelays(files) {
+    let listing;
+    try {
+        listing = await files.listFiles(RELAYS_ROOT);
+    }
+    catch (error) {
+        return fileAccessFailure(error);
+    }
+    const relays = sortRelaysByRecency(listing.entries
+        .filter((entry) => entry.type === "directory")
+        .map((entry) => toRelaySummary(entry)));
+    return { kind: "loaded", relays };
+}
+/**
+ * List one relay's document tree. At the relay root the anchor documents come
+ * first (status.md, charter.md, log.md); at every level files sort
+ * alphabetically before directories. Symlinks are never followed. Never
+ * rejects.
+ */
+export async function listRelayDocumentTree(files, relayPath) {
+    let rootListing;
+    try {
+        rootListing = await files.listFiles(relayPath);
+    }
+    catch (error) {
+        return fileAccessFailure(error);
+    }
+    const state = { documentCount: 0, directoryCount: 0, partial: rootListing.truncated };
+    const tree = await walkListing(files, rootListing, relayPath, 0, state);
+    return { kind: "loaded", tree, documentCount: state.documentCount, partial: state.partial };
+}
+/** Read one relay document. Never rejects. */
+export async function readRelayDocument(files, documentPath) {
+    try {
+        const file = await files.readFile(documentPath);
+        return { kind: "loaded", content: file.content, truncated: file.truncated, binary: file.binary };
+    }
+    catch (error) {
+        return fileAccessFailure(error);
+    }
+}
+/** Newest first; relays without a usable modifiedAt sort last, alphabetically. */
+export function sortRelaysByRecency(relays) {
+    return [...relays].sort(compareRelaysByRecency);
+}
+/** The document a relay opens on: the depth-first first file (root anchors sort first, so status.md wins when present). */
+export function defaultRelayDocument(tree) {
+    for (const node of tree) {
+        if (node.kind === "file")
+            return node;
+        const nested = defaultRelayDocument(node.children);
+        if (nested !== undefined)
+            return nested;
+    }
+    return undefined;
+}
+/** All file nodes in tree order, depth-first. */
+export function flattenRelayTree(tree) {
+    const files = [];
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.kind === "file")
+                files.push(node);
+            else
+                visit(node.children);
+        }
+    };
+    visit(tree);
+    return files;
+}
+/** Directory paths of every directory in the tree; used to prune stale expansion state. */
+export function collectDirectoryPaths(tree) {
+    const paths = new Set();
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.kind !== "directory")
+                continue;
+            paths.add(node.path);
+            visit(node.children);
+        }
+    };
+    visit(tree);
+    return paths;
+}
+/** Directory paths containing the given file, from the relay root down; empty when the file is not in the tree. */
+export function ancestorDirectoryPaths(tree, filePath) {
+    const chain = [];
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.kind === "file") {
+                if (node.path === filePath)
+                    return true;
+                continue;
+            }
+            chain.push(node.path);
+            if (visit(node.children))
+                return true;
+            chain.pop();
+        }
+        return false;
+    };
+    return visit(tree) ? chain : [];
+}
+/**
+ * Build the ordered children of one already-fetched directory listing.
+ * Subdirectories are walked in parallel; a subdirectory whose own listing
+ * fails contributes an empty node and flags the tree partial rather than
+ * failing the whole relay.
+ */
+async function walkListing(files, listing, relayPath, depth, state) {
+    // Symlink entries are intentionally never followed.
+    const fileEntries = listing.entries.filter((entry) => entry.type === "file");
+    const directoryEntries = listing.entries.filter((entry) => entry.type === "directory");
+    let fileNodes = orderFileEntries(fileEntries, depth === 0).map((entry) => toFileNode(entry, relayPath, depth));
+    const remaining = MAX_RELAY_DOCUMENTS - state.documentCount;
+    if (fileNodes.length > remaining) {
+        fileNodes = fileNodes.slice(0, Math.max(0, remaining));
+        state.partial = true;
+    }
+    state.documentCount += fileNodes.length;
+    const directories = await Promise.all([...directoryEntries].sort(compareByName).map(async (entry) => {
+        const node = {
+            kind: "directory",
+            name: entry.name,
+            path: entry.path,
+            relativePath: relativePathOf(entry.path, relayPath),
+            depth,
+            children: [],
+        };
+        if (depth >= MAX_RELAY_TREE_DEPTH) {
+            state.partial = true;
+            return node;
+        }
+        // The count is bumped synchronously before any await, so the parallel
+        // walk below stays deterministic in sorted order.
+        if (state.directoryCount >= MAX_RELAY_DIRECTORIES) {
+            state.partial = true;
+            return node;
+        }
+        state.directoryCount += 1;
+        try {
+            const subListing = await files.listFiles(entry.path);
+            if (subListing.truncated)
+                state.partial = true;
+            node.children = await walkListing(files, subListing, relayPath, depth + 1, state);
+        }
+        catch {
+            state.partial = true;
+        }
+        return node;
+    }));
+    return [...fileNodes, ...directories];
+}
+/** At the relay root the anchor documents lead; deeper levels are simply alphabetical. */
+function orderFileEntries(entries, isRelayRoot) {
+    return [...entries].sort(isRelayRoot ? compareRootFiles : compareByName);
+}
+function compareRootFiles(left, right) {
+    const anchorOrder = anchorIndexOf(left.name) - anchorIndexOf(right.name);
+    if (anchorOrder !== 0)
+        return anchorOrder;
+    return left.name.localeCompare(right.name);
+}
+function anchorIndexOf(name) {
+    const index = RELAY_ANCHOR_DOCUMENTS.indexOf(name);
+    return index === -1 ? RELAY_ANCHOR_DOCUMENTS.length : index;
+}
+function compareByName(left, right) {
+    return left.name.localeCompare(right.name);
+}
+function toRelaySummary(entry) {
+    return { name: entry.name, path: entry.path, modifiedAt: entry.modifiedAt };
+}
+function toFileNode(entry, relayPath, depth) {
+    return {
+        kind: "file",
+        name: entry.name,
+        path: entry.path,
+        relativePath: relativePathOf(entry.path, relayPath),
+        depth,
+        modifiedAt: entry.modifiedAt,
+    };
+}
+/** Entry paths from the file API should sit under the relay root; fall back to the file name if not. */
+function relativePathOf(path, relayPath) {
+    const prefix = `${relayPath}/`;
+    return path.startsWith(prefix) ? path.slice(prefix.length) : path.slice(path.lastIndexOf("/") + 1);
+}
+function compareRelaysByRecency(left, right) {
+    const leftTime = timestampOf(left.modifiedAt);
+    const rightTime = timestampOf(right.modifiedAt);
+    if (leftTime !== undefined && rightTime !== undefined && leftTime !== rightTime)
+        return rightTime - leftTime;
+    if (leftTime !== undefined)
+        return -1;
+    if (rightTime !== undefined)
+        return 1;
+    return left.name.localeCompare(right.name);
+}
+function timestampOf(modifiedAt) {
+    if (modifiedAt === undefined)
+        return undefined;
+    const time = Date.parse(modifiedAt);
+    return Number.isNaN(time) ? undefined : time;
+}
+function fileAccessFailure(error) {
+    if (error instanceof Error && missingListingErrorMessages.has(error.message))
+        return { kind: "missing" };
+    return { kind: "unavailable", detail: error instanceof Error ? error.message : String(error) };
+}