@reticlehq/server 3.9.0 → 3.10.1

package/dist/portal/session/dev-server/dev-command.js

@@ -8,9 +8,9 @@
  *
  * Pure apart from one injected reader, so every case is a unit test rather than a temp directory.
  */
-import { readFileSync, readdirSync } from 'node:fs';
+import { accessSync, constants, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { RETICLE_NPM_PACKAGE, desktopLaunch, workspacePackageDirs } from '@reticlehq/init';
+import { RETICLE_NPM_PACKAGE, desktopLaunch, isWebApp, workspacePackageDirs, } from '@reticlehq/init';
 /**
  * Script names checked, in order.
  *
@@ -129,24 +129,66 @@ function devCommandFor(directory, manager, read) {
 /** Folders never read as an app: dependencies, and anything hidden (`.git`, `.cache`). */
 const NODE_MODULES = 'node_modules';
 const HIDDEN_PREFIX = '.';
+/** Whether the process can write in `path`. Asked of every web-app candidate — see `preferWebApps`. */
+function isWritableDirectory(path) {
+    try {
+        accessSync(path, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * The direct child folders of `directory` that are apps with a dev command, sorted by name.
+ * Whether the package in `directory` is a web app, using init's own signal.
+ *
+ * A backend can have a dev script too, so the script alone is not enough. init already answers
+ * "is this a page somebody can open", and a second answer here would let the two disagree.
+ */
+function isWebAppAt(directory, read) {
+    return isWebApp('.', {
+        exists: (path) => read(join(directory, path)) !== undefined,
+        readFile: (path) => read(join(directory, path)) ?? null,
+    });
+}
+/**
+ * Web apps first, and of those the ones this process can write. When nothing here reads as a web
+ * app, every candidate comes back, in its original order.
+ *
+ * `isWebApp` is a detector, and a detector has gaps: a custom webpack or esbuild setup, a framework
+ * it does not know yet, a repository whose only candidate is a backend. Gating on it — as this code
+ * first did — hands the agent no next action where `main` hands it a command, and silence is the
+ * worse failure: a command that starts the wrong thing can be corrected, no command cannot. So the
+ * web-app check RANKS candidates instead of gating them.
+ *
+ * Writability is the exception: asked of the web apps only, where it is absolute. The reported bug
+ * (#2017) is a read-only backup copy sitting beside the real app, and a folder nobody can write must
+ * never be the one chosen while a writable sibling exists.
+ */
+function preferWebApps(candidates, isWebAppCandidate, isWritable) {
+    const apps = candidates.filter(isWebAppCandidate);
+    return 0 < apps.length ? apps.filter(isWritable) : candidates;
+}
+/**
+ * The direct child folders of `directory` that are apps with a dev command, sorted by name: the web
+ * apps when there are any, every dev-script folder when there are none (see `preferWebApps`).
  *
  * Only for a folder with no package.json of its own. A task folder holds the app one level down, and
- * no workspace file lists it, so `workspacePackageDirs` never finds it. Folders that are not apps
- * (no package.json, or no dev script), `node_modules` and hidden folders are skipped.
+ * no workspace file lists it, so `workspacePackageDirs` never finds it. `node_modules`, hidden
+ * folders and folders with no dev script are never candidates.
  */
-export function childDevApps(directory, read = readTextFile, listDirs = readDirNames) {
+export function childDevApps(directory, read = readTextFile, listDirs = readDirNames, writable = isWritableDirectory) {
     if (read(join(directory, PACKAGE_JSON)) !== undefined) {
         return [];
     }
-    return listDirs(directory)
+    const candidates = listDirs(directory)
         .filter((name) => NODE_MODULES !== name && !name.startsWith(HIDDEN_PREFIX))
         .filter((name) => {
         const child = join(directory, name);
         return devCommandFor(child, packageManager(child, read), read) !== undefined;
     })
         .sort();
+    return preferWebApps(candidates, (name) => isWebAppAt(join(directory, name), read), (name) => writable(join(directory, name)));
 }
 /** Directory names under `path`, or none when it cannot be read. */
 function readDirNames(path) {
@@ -177,7 +219,7 @@ export function detectDevCommand(directory, read = readTextFile) {
  * init's own workspace listing answers which directories to consider; the root's lockfile picks the
  * package manager, because a workspace package usually has no lockfile of its own.
  */
-export function detectDevCommandInProject(directory, read = readTextFile, listDirs = readDirNames) {
+export function detectDevCommandInProject(directory, read = readTextFile, listDirs = readDirNames, writable = isWritableDirectory) {
     const manager = packageManager(directory, read);
     const here = devCommandFor(directory, manager, read);
     if (here !== undefined) {
@@ -188,7 +230,7 @@ export function detectDevCommandInProject(directory, read = readTextFile, listDi
     // `childDevApps`. With none, the workspace search below still looks a level deeper.
     if (read(join(directory, PACKAGE_JSON)) === undefined &&
         read(join(directory, PNPM_WORKSPACE)) === undefined) {
-        const [only, ...others] = childDevApps(directory, read, listDirs);
+        const [only, ...others] = childDevApps(directory, read, listDirs, writable);
         if (0 < others.length) {
             return undefined;
         }
@@ -204,13 +246,17 @@ export function detectDevCommandInProject(directory, read = readTextFile, listDi
         readFile: (path) => read(join(directory, path)) ?? null,
         listDirs: (path) => listDirs(join(directory, path)),
     });
+    const candidates = [];
     for (const sub of packages) {
-        const found = devCommandFor(join(directory, sub), manager, read);
-        if (found !== undefined) {
-            return { ...found, directory: sub };
+        const child = join(directory, sub);
+        const command = devCommandFor(child, manager, read);
+        if (command !== undefined) {
+            candidates.push({ sub, child, command });
         }
     }
-    return undefined;
+    // Same rule as the child folders above, so a workspace and a task folder cannot disagree.
+    const [first] = preferWebApps(candidates, (entry) => isWebAppAt(entry.child, read), (entry) => writable(entry.child));
+    return first === undefined ? undefined : { ...first.command, directory: first.sub };
 }
 /**
  * The command that wires THIS project for good: `init`, in the app's own folder, through the
@@ -220,11 +266,11 @@ export function detectDevCommandInProject(directory, read = readTextFile, listDi
  * time: `init` run in a folder that is not the app stops on a missing package.json, and a runner the
  * machine does not have is "command not found". npx whenever there is doubt — it ships with Node.
  */
-export function initCommandIn(directory, read = readTextFile, listDirs = readDirNames) {
+export function initCommandIn(directory, read = readTextFile, listDirs = readDirNames, writable = isWritableDirectory) {
     const manager = packageManager(directory, read);
     const berry = read(join(directory, YARN_BERRY_MARKER)) !== undefined;
     const runner = YARN === manager ? (berry ? YARN_DLX : NPX) : (RUNNER[manager] ?? NPX);
     const command = `${runner} ${RETICLE_NPM_PACKAGE} ${INIT_VERB}`;
-    const app = detectDevCommandInProject(directory, read, listDirs)?.directory;
+    const app = detectDevCommandInProject(directory, read, listDirs, writable)?.directory;
     return app === undefined ? command : `cd ${app} && ${command}`;
 }

package/dist/portal/session/dev-server/dev-server-probe.d.ts

@@ -69,6 +69,13 @@ export declare function probeDevServerStates(ports?: readonly number[], probe?:
     serving: number[];
     slow: number[];
 }>;
+/**
+ * Whether anything accepted a connection on this port, on either loopback family. Never rejects.
+ *
+ * A server compiling its first route answers `CONNECTED_NO_ANSWER`, and that counts: the lease uses
+ * this to stop telling an agent to start a dev server that is already running (#2005).
+ */
+export declare function portAcceptsConnection(port: number, probe?: (port: number) => Promise<PortState>): Promise<boolean>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;
 export {};

package/dist/portal/session/dev-server/dev-server-probe.js

@@ -156,6 +156,15 @@ async function anyFamilyState(port, probe = probeState) {
         return PortState.CONNECTED_NO_ANSWER;
     return PortState.CLOSED;
 }
+/**
+ * Whether anything accepted a connection on this port, on either loopback family. Never rejects.
+ *
+ * A server compiling its first route answers `CONNECTED_NO_ANSWER`, and that counts: the lease uses
+ * this to stop telling an agent to start a dev server that is already running (#2005).
+ */
+export async function portAcceptsConnection(port, probe = (p) => anyFamilyState(p)) {
+    return PortState.CLOSED !== (await classifyPort(port, probe));
+}
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyServes(p)) {
     const results = await Promise.all(ports.map((p) => probe(p).then((up) => (up ? p : null))));

package/dist/portal/session/dev-server/project-ports.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ports this project sets in its `.env` files (reticle#1543).
+ *
+ * The no-session scan probes a list of well-known ports, the ports the build plugins announced, a
+ * port pinned in the `dev` script (#1367), and the ports of earlier sessions. An app that reads its
+ * port from `.env` is on none of those. Reported from React apps on Windows: a preview server on
+ * :3020, started by a Node script, and the answer said no app was running and suggested a dev
+ * server, which would start a duplicate.
+ *
+ * This only ADDS candidates to the scan. The scan still decides which of them answer like a dev
+ * server.
+ */
+/** The `.env` files a Node dev setup reads, in the order dotenv-style loaders read them. */
+export declare const ENV_PORT_FILES: readonly [".env", ".env.local", ".env.development", ".env.development.local"];
+/**
+ * The ports the project's `.env` files set with `PORT=`.
+ *
+ * Every file is read, not only the one a given loader would pick: the scan only probes candidates,
+ * so an extra port costs one connection attempt, while a missed one is the defect this fixes.
+ */
+export declare function envFilePorts(directory: string, read?: (path: string) => string | undefined): number[];

package/dist/portal/session/dev-server/project-ports.js

@@ -0,0 +1,62 @@
+/**
+ * Ports this project sets in its `.env` files (reticle#1543).
+ *
+ * The no-session scan probes a list of well-known ports, the ports the build plugins announced, a
+ * port pinned in the `dev` script (#1367), and the ports of earlier sessions. An app that reads its
+ * port from `.env` is on none of those. Reported from React apps on Windows: a preview server on
+ * :3020, started by a Node script, and the answer said no app was running and suggested a dev
+ * server, which would start a duplicate.
+ *
+ * This only ADDS candidates to the scan. The scan still decides which of them answer like a dev
+ * server.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The `.env` files a Node dev setup reads, in the order dotenv-style loaders read them. */
+export const ENV_PORT_FILES = [
+    '.env',
+    '.env.local',
+    '.env.development',
+    '.env.development.local',
+];
+/** One `PORT=3020` line. `export`, quotes and a trailing comment are allowed. */
+const ENV_PORT_LINE = /^\s*(?:export\s+)?PORT\s*=\s*["']?(\d{1,5})["']?\s*(?:#.*)?$/gm;
+/** The highest TCP port. */
+const MAX_PORT = 65_535;
+function toPort(digits) {
+    if (digits === undefined) {
+        return undefined;
+    }
+    const port = Number(digits);
+    return Number.isInteger(port) && port > 0 && port <= MAX_PORT ? port : undefined;
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The ports the project's `.env` files set with `PORT=`.
+ *
+ * Every file is read, not only the one a given loader would pick: the scan only probes candidates,
+ * so an extra port costs one connection attempt, while a missed one is the defect this fixes.
+ */
+export function envFilePorts(directory, read = readText) {
+    const ports = new Set();
+    for (const file of ENV_PORT_FILES) {
+        const text = read(join(directory, file));
+        if (text === undefined) {
+            continue;
+        }
+        for (const match of text.matchAll(ENV_PORT_LINE)) {
+            const port = toPort(match[1]);
+            if (port !== undefined) {
+                ports.add(port);
+            }
+        }
+    }
+    return [...ports];
+}

package/dist/portal/session/facts/departed-network.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Carry the network record of a document that unloaded into the session of the next document (#1944).
+ *
+ * A click on "Sign out" sends a POST and then loads `/sign-in`. The old document sends the POST's
+ * records before it unloads, so the daemon has them. But the new document connects as a new
+ * `Session` under the same id, and the act's verdict, every later `reticle_observe { action:
+ * "network" }` and every later `reticle_assert` read only that session. The POST went away with the
+ * old `Session` object, and a `net` check on a real request answered "no call matched".
+ *
+ * What is carried, and why only that:
+ *
+ * - Only the network records from the start of the agent's newest action on the old document. Those
+ *   are the window that the act's verdict and the agent's next check read. Nothing is carried when
+ *   no agent acted, so a person's own reloads do not move old traffic into a new page.
+ * - Not the departure record (`NetInitiator.NAVIGATION`). The new document records its own load.
+ * - Only when the new session's first stamped event is from a DIFFERENT document. The same document
+ *   reconnecting after a bridge outage did not unload, and its requests can still be answered.
+ *
+ * How the loss is declared (AGENTS.md rule 11):
+ *
+ * - Every carried record has `fromDepartedDocument: true`. Its `t` is when it was carried, so it
+ *   cannot show where the request was in the old document's timeline.
+ * - A request that failed with status 0 is not carried as a failure: the browser cancels a leaving
+ *   document's requests, so that status is not the server's answer (see `abortedByUnload`).
+ * - A request that had no answer is marked `pageUnloaded: true`. Its answer went to a document that
+ *   no longer exists. Its outcome is unknown: `net` checks that rest on it are `unknown`, never `no`,
+ *   and settle does not wait for it (`neverAnswered`).
+ * - `documentId`, `seq`, `actionId` and `attribution` are removed. They are about the old document
+ *   and its journal, and kept here they would make the old document the current one again.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+/** What the old document sent, and which document it was. */
+export interface DepartedNetwork {
+    /** The old document's id, or undefined when its SDK does not stamp one. */
+    readonly documentId: string | undefined;
+    readonly events: readonly ReticleEvent[];
+}
+/** The part of a `Session` this needs. A real `Session` satisfies it. */
+export interface DepartingSession {
+    readonly currentDocumentId: string | undefined;
+    readonly lastAct: {
+        cursor(): number | undefined;
+    };
+    /** The newest action id this session minted. Events in an open action window carry it. */
+    readonly lastActionId: string | undefined;
+    eventsSince(cursor: number): ReticleEvent[];
+}
+/** The part of a `Session` that receives the record. A real `Session` satisfies it. */
+export interface ArrivingSession {
+    pushEvent(event: ReticleEvent): void;
+    onEvent(listener: (event: ReticleEvent) => void): () => void;
+}
+/**
+ * The network records the old document made after the agent's last act on it, ready to carry.
+ * Undefined when nothing is to be carried.
+ */
+export declare function departedNetworkOf(session: DepartingSession): DepartedNetwork | undefined;
+/**
+ * Give the new session the old document's record once it shows that it is a new document.
+ *
+ * Waits for the first event that carries a `documentId`. A different id means the old document
+ * unloaded: the record goes in, right after that event. The same id means the same document
+ * reconnected, and nothing goes in. An old document with no id cannot be told apart, so nothing
+ * goes in then either. Returns a function that stops the wait.
+ */
+export declare function carryOnNewDocument(next: ArrivingSession, departed: DepartedNetwork): () => void;

package/dist/portal/session/facts/departed-network.js

@@ -0,0 +1,142 @@
+/**
+ * Carry the network record of a document that unloaded into the session of the next document (#1944).
+ *
+ * A click on "Sign out" sends a POST and then loads `/sign-in`. The old document sends the POST's
+ * records before it unloads, so the daemon has them. But the new document connects as a new
+ * `Session` under the same id, and the act's verdict, every later `reticle_observe { action:
+ * "network" }` and every later `reticle_assert` read only that session. The POST went away with the
+ * old `Session` object, and a `net` check on a real request answered "no call matched".
+ *
+ * What is carried, and why only that:
+ *
+ * - Only the network records from the start of the agent's newest action on the old document. Those
+ *   are the window that the act's verdict and the agent's next check read. Nothing is carried when
+ *   no agent acted, so a person's own reloads do not move old traffic into a new page.
+ * - Not the departure record (`NetInitiator.NAVIGATION`). The new document records its own load.
+ * - Only when the new session's first stamped event is from a DIFFERENT document. The same document
+ *   reconnecting after a bridge outage did not unload, and its requests can still be answered.
+ *
+ * How the loss is declared (AGENTS.md rule 11):
+ *
+ * - Every carried record has `fromDepartedDocument: true`. Its `t` is when it was carried, so it
+ *   cannot show where the request was in the old document's timeline.
+ * - A request that failed with status 0 is not carried as a failure: the browser cancels a leaving
+ *   document's requests, so that status is not the server's answer (see `abortedByUnload`).
+ * - A request that had no answer is marked `pageUnloaded: true`. Its answer went to a document that
+ *   no longer exists. Its outcome is unknown: `net` checks that rest on it are `unknown`, never `no`,
+ *   and settle does not wait for it (`neverAnswered`).
+ * - `documentId`, `seq`, `actionId` and `attribution` are removed. They are about the old document
+ *   and its journal, and kept here they would make the old document the current one again.
+ */
+import { DepartedNetField, EventType, NetInitiator, asString, } from '@reticlehq/core';
+/** The records of one request. Streams are left out: an open stream would hold settle open. */
+const CARRIED_TYPES = new Set([
+    EventType.NET_PENDING,
+    EventType.NET_REQUEST,
+    EventType.NET_RESPONSE_BODY,
+]);
+/**
+ * A request that failed with no HTTP status (status 0) in a document that then unloaded.
+ *
+ * A browser cancels the requests of a document it leaves, and the page sees that as a network
+ * error ("Failed to fetch"). The server can have received the request and answered it: driven
+ * against a POST that took 2 s to answer, the server logged the POST while the page recorded
+ * status 0. So the status 0 is not the server's answer. The record is left out, and its pending
+ * half is carried as `pageUnloaded`: unknown, not failed.
+ */
+function abortedByUnload(event) {
+    return event.type === EventType.NET_REQUEST && 0 === event.data['status'];
+}
+/**
+ * Where the newest action's records start in the departed session, or undefined when no agent acted.
+ *
+ * Two sources, and the later one wins. `lastAct.cursor()` is set when an act's reply arrives. A
+ * click that calls `location.assign()` can unload the page before that reply, so the cursor stays
+ * at an OLDER act (or unset), and the request is left behind (driven: it was). The events of an
+ * open action window carry its id, so the first event with the newest id marks where that action
+ * began to have effects. The later of the two is the newest action, so older traffic stays out.
+ */
+function newestActionStart(session) {
+    const cursor = session.lastAct.cursor();
+    const id = session.lastActionId;
+    const firstOfNewest = id === undefined ? undefined : session.eventsSince(0).find((e) => e.actionId === id)?.t;
+    if (cursor === undefined) {
+        return firstOfNewest;
+    }
+    if (firstOfNewest === undefined) {
+        return cursor;
+    }
+    return Math.max(cursor, firstOfNewest);
+}
+/** One carried record: the loss is declared and the old document's coordinates are removed. */
+function carried(event, unanswered) {
+    const id = asString(event.data['id']);
+    const lost = event.type === EventType.NET_PENDING && id !== undefined && unanswered.has(id)
+        ? { [DepartedNetField.PAGE_UNLOADED]: true }
+        : {};
+    return {
+        t: event.t,
+        type: event.type,
+        sessionId: event.sessionId,
+        data: { ...event.data, [DepartedNetField.FROM_DEPARTED_DOCUMENT]: true, ...lost },
+    };
+}
+/**
+ * The network records the old document made after the agent's last act on it, ready to carry.
+ * Undefined when nothing is to be carried.
+ */
+export function departedNetworkOf(session) {
+    const floor = newestActionStart(session);
+    if (floor === undefined) {
+        return undefined;
+    }
+    const window = session
+        .eventsSince(floor)
+        .filter((e) => CARRIED_TYPES.has(e.type) &&
+        e.data['initiator'] !== NetInitiator.NAVIGATION &&
+        !abortedByUnload(e));
+    if (0 === window.length) {
+        return undefined;
+    }
+    const answered = new Set();
+    for (const e of window) {
+        const id = asString(e.data['id']);
+        if (e.type === EventType.NET_REQUEST && id !== undefined) {
+            answered.add(id);
+        }
+    }
+    const unanswered = new Set();
+    for (const e of window) {
+        const id = asString(e.data['id']);
+        if (e.type === EventType.NET_PENDING && id !== undefined && !answered.has(id)) {
+            unanswered.add(id);
+        }
+    }
+    return {
+        documentId: session.currentDocumentId,
+        events: window.map((e) => carried(e, unanswered)),
+    };
+}
+/**
+ * Give the new session the old document's record once it shows that it is a new document.
+ *
+ * Waits for the first event that carries a `documentId`. A different id means the old document
+ * unloaded: the record goes in, right after that event. The same id means the same document
+ * reconnected, and nothing goes in. An old document with no id cannot be told apart, so nothing
+ * goes in then either. Returns a function that stops the wait.
+ */
+export function carryOnNewDocument(next, departed) {
+    const stop = next.onEvent((event) => {
+        if (event.documentId === undefined) {
+            return;
+        }
+        stop();
+        if (departed.documentId === undefined || event.documentId === departed.documentId) {
+            return;
+        }
+        for (const record of departed.events) {
+            next.pushEvent(record);
+        }
+    });
+    return stop;
+}

package/dist/portal/session/no-session-diagnosis.d.ts

@@ -29,6 +29,15 @@ export interface NoSessionFacts {
      * lock. Named in the message so the reader can tell the two apart.
      */
     slowListeners?: readonly number[];
+    /**
+     * Ports that processes in this project's folder listen on, and the scan did not hear a page on.
+     *
+     * Never a place to send the agent, so never in `listening`: agent tools run in this folder and
+     * listen too, and one serves a page. An agent-browser viewer in `listening` produced "just open
+     * http://localhost:<port>" while the app was not running (reticle#1543). What these ports prove
+     * is less: the answer cannot say that nothing is listening.
+     */
+    folderListeners?: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
     /**