@reticlehq/server 2.11.0 → 2.13.0

package/dist/cli/project-name.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What project a repo binds to when nobody says.
+ *
+ * `link` used to answer "default" for every repo on every machine, which is wrong in two directions
+ * at once. Measured: two unrelated checkouts linked on one account — a storefront and a billing
+ * service — both bound to a single project called "Default" and shared one key, so their runs,
+ * issues and impact merged into one bucket and the dashboard's per-project view described nothing.
+ * It is also what made two TENANTS collide, because a credential slot built from a project id is
+ * only as distinct as the ids are.
+ *
+ * A repo already knows its name: the directory it lives in. That is not a guess, it is the name its
+ * owner chose and the one they will look for in a project list.
+ */
+/** The id used when a directory name yields nothing usable — the historical behaviour, unchanged. */
+export declare const DEFAULT_PROJECT_ID = "default";
+/**
+ * Turn a directory name into a project id: lowercase, and anything that is not a letter or digit
+ * becomes a single hyphen. Conservative on purpose — this id ends up in URLs, in credential slot
+ * keys and in a project list somebody has to read.
+ */
+export declare const slugifyProjectName: (raw: string) => string;
+/**
+ * The project a `link` with no `--project` should target.
+ *
+ * The EXISTING binding wins over the directory name, and that ordering is the whole safety of this
+ * change. A repo that is already linked has history in a project; re-running `link` — which people
+ * do to rotate a key or repoint an environment — must land in that same project or the history
+ * silently splits in two, which is worse than the shared-bucket problem this fixes.
+ */
+export declare const defaultProjectFor: (cwdBasename: string, existingProjectId: string | undefined) => string;

package/dist/cli/project-name.js

@@ -0,0 +1,44 @@
+/**
+ * What project a repo binds to when nobody says.
+ *
+ * `link` used to answer "default" for every repo on every machine, which is wrong in two directions
+ * at once. Measured: two unrelated checkouts linked on one account — a storefront and a billing
+ * service — both bound to a single project called "Default" and shared one key, so their runs,
+ * issues and impact merged into one bucket and the dashboard's per-project view described nothing.
+ * It is also what made two TENANTS collide, because a credential slot built from a project id is
+ * only as distinct as the ids are.
+ *
+ * A repo already knows its name: the directory it lives in. That is not a guess, it is the name its
+ * owner chose and the one they will look for in a project list.
+ */
+/** Cap the slug so a deep or oddly-named checkout cannot produce an unreadable project id. */
+const MAX_SLUG = 48;
+/** The id used when a directory name yields nothing usable — the historical behaviour, unchanged. */
+export const DEFAULT_PROJECT_ID = 'default';
+/**
+ * Turn a directory name into a project id: lowercase, and anything that is not a letter or digit
+ * becomes a single hyphen. Conservative on purpose — this id ends up in URLs, in credential slot
+ * keys and in a project list somebody has to read.
+ */
+export const slugifyProjectName = (raw) => {
+    const slug = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, MAX_SLUG)
+        .replace(/-+$/g, '');
+    return 0 === slug.length ? DEFAULT_PROJECT_ID : slug;
+};
+/**
+ * The project a `link` with no `--project` should target.
+ *
+ * The EXISTING binding wins over the directory name, and that ordering is the whole safety of this
+ * change. A repo that is already linked has history in a project; re-running `link` — which people
+ * do to rotate a key or repoint an environment — must land in that same project or the history
+ * silently splits in two, which is worse than the shared-bucket problem this fixes.
+ */
+export const defaultProjectFor = (cwdBasename, existingProjectId) => {
+    if (existingProjectId !== undefined && existingProjectId.length > 0)
+        return existingProjectId;
+    return slugifyProjectName(cwdBasename);
+};

package/dist/cli/sibling-ports.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Well-known Reticle ports other than the one this daemon bound.
+ *
+ * The remaining half of #261: when the SDK dials 4460 and we listen on 4400, we cannot see the
+ * refused inbound — but we CAN notice that a well-known Reticle port other than ours has a
+ * listener. That is an observation, not a diagnosis. A neighbour's daemon, another project, or an
+ * unrelated process on 4460 all look identical from here, so the sentence that reports it must not
+ * conclude that it is the daemon this app wants. Maintainer constraint on the issue: report the
+ * observation without the conclusion.
+ */
+/**
+ * The port the bench fixture's SDK dials.
+ *
+ * Deliberate, and must not be "fixed" onto the default: `bench/harness/ports.mjs` documents a past
+ * incident caused by having more than one source of truth for it. It exists so a default daemon on
+ * 4400 and a bench run never collide. Doctor and the no-session diagnosis probe it as a sibling
+ * of 4400 for that reason — it is the port the original silent no-connect was on.
+ */
+export declare const RETICLE_BENCH_PORT = 4460;
+/** Ports a Reticle daemon is known to occupy. Probe every one except the port we ourselves bound. */
+export declare const WELL_KNOWN_RETICLE_PORTS: readonly number[];
+/** Well-known Reticle ports other than `boundPort`. Empty when we are the only well-known occupant. */
+export declare function siblingPorts(boundPort: number, known?: readonly number[]): readonly number[];
+/**
+ * One sentence for a listener on a sibling Reticle port. `undefined` when there is nothing to say.
+ *
+ * Wording is load-bearing: it names the observation and refuses the conclusion. A test pins that it
+ * does not claim the listener is the daemon this app wants, or that the SDK is dialling it.
+ */
+export declare function siblingListenerNote(boundPort: number, occupiedSiblings: readonly number[]): string | undefined;
+/**
+ * Which well-known siblings currently accept a TCP connection.
+ *
+ * Pure in the rule, impure at the edge: `isListening` is injected so this can be tested without a
+ * socket, and so a lying probe is a separate failure from a lying sentence.
+ */
+export declare function findOccupiedSiblings(boundPort: number, isListening: (port: number) => Promise<boolean>): Promise<readonly number[]>;

package/dist/cli/sibling-ports.js

@@ -0,0 +1,56 @@
+/**
+ * Well-known Reticle ports other than the one this daemon bound.
+ *
+ * The remaining half of #261: when the SDK dials 4460 and we listen on 4400, we cannot see the
+ * refused inbound — but we CAN notice that a well-known Reticle port other than ours has a
+ * listener. That is an observation, not a diagnosis. A neighbour's daemon, another project, or an
+ * unrelated process on 4460 all look identical from here, so the sentence that reports it must not
+ * conclude that it is the daemon this app wants. Maintainer constraint on the issue: report the
+ * observation without the conclusion.
+ */
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+/**
+ * The port the bench fixture's SDK dials.
+ *
+ * Deliberate, and must not be "fixed" onto the default: `bench/harness/ports.mjs` documents a past
+ * incident caused by having more than one source of truth for it. It exists so a default daemon on
+ * 4400 and a bench run never collide. Doctor and the no-session diagnosis probe it as a sibling
+ * of 4400 for that reason — it is the port the original silent no-connect was on.
+ */
+export const RETICLE_BENCH_PORT = 4460;
+/** Ports a Reticle daemon is known to occupy. Probe every one except the port we ourselves bound. */
+export const WELL_KNOWN_RETICLE_PORTS = [
+    RETICLE_DEFAULT_PORT,
+    RETICLE_BENCH_PORT,
+];
+/** Well-known Reticle ports other than `boundPort`. Empty when we are the only well-known occupant. */
+export function siblingPorts(boundPort, known = WELL_KNOWN_RETICLE_PORTS) {
+    return known.filter((port) => port !== boundPort);
+}
+/**
+ * One sentence for a listener on a sibling Reticle port. `undefined` when there is nothing to say.
+ *
+ * Wording is load-bearing: it names the observation and refuses the conclusion. A test pins that it
+ * does not claim the listener is the daemon this app wants, or that the SDK is dialling it.
+ */
+export function siblingListenerNote(boundPort, occupiedSiblings) {
+    if (0 === occupiedSiblings.length)
+        return undefined;
+    const listed = occupiedSiblings.map((port) => `:${String(port)}`).join(', ');
+    return (`something is listening on ${listed}, which this daemon is not` +
+        ` (this daemon is on :${String(boundPort)}); that may or may not be related.`);
+}
+/**
+ * Which well-known siblings currently accept a TCP connection.
+ *
+ * Pure in the rule, impure at the edge: `isListening` is injected so this can be tested without a
+ * socket, and so a lying probe is a separate failure from a lying sentence.
+ */
+export async function findOccupiedSiblings(boundPort, isListening) {
+    const occupied = [];
+    for (const port of siblingPorts(boundPort)) {
+        if (await isListening(port))
+            occupied.push(port);
+    }
+    return occupied;
+}

package/dist/cli/status-next-action.d.ts

@@ -27,6 +27,20 @@ export interface StatusFacts {
      * paths do the first without the second.
      */
     initialized: boolean;
+    /**
+     * Ports of dev servers that ANNOUNCED themselves — i.e. that have Reticle loaded in the process
+     * actually running.
+     *
+     * `nextActionFor` already ranks on a listening-port list; it just never had one from here, so this
+     * command passed `[]` and every wired project with a live dev server was told "the app is probably
+     * not running". That is advice contradicting the terminal the reader is looking at, and it sends
+     * them to restart something already up.
+     *
+     * Stronger than the port scan the field was designed for: a scanned port proves something is
+     * listening, an announced one proves it is listening AND instrumented. Optional so every existing
+     * caller keeps today's behaviour.
+     */
+    devServerPorts?: readonly number[];
 }
 /**
  * What to do next, or `undefined` when a session is connected and there is nothing to fix.

package/dist/cli/status-next-action.js

@@ -43,9 +43,9 @@ export function statusNextAction(facts) {
             `Reticle tool, and it exits again when idle. ${wiring} Ask your agent to verify something, then ` +
             `run status again.`).replace(/\s+/g, ' ');
     }
-    // The daemon is up and no page has connected. `nextActionFor` owns the ranking; the CLI cannot see
-    // listening ports or a dev command from here, so it passes what it has and lets that function say
-    // what is missing rather than guessing at it.
+    // The daemon is up and no page has connected. `nextActionFor` owns the ranking; this passes what
+    // it has and lets that function say what is missing rather than guessing at it. It CAN see
+    // listening ports now — the announced ones — which is what the empty list here used to cost.
     const next = nextActionFor({
         // The durable bit IS this side's `everConnected`. In-process the flag means "this daemon has served
         // a session", which a daemon seconds old cannot know; from the CLI the honest equivalent is "an app
@@ -53,7 +53,7 @@ export function statusNextAction(facts) {
         // is in question at all.
         everConnected: facts.previouslyConnected,
         initialized: facts.initialized,
-        listening: [],
+        listening: facts.devServerPorts ?? [],
         dev: undefined,
         previouslyConnected: facts.previouslyConnected,
     });

package/dist/cli.d.ts

@@ -2,3 +2,4 @@
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
+export declare function handleStatus(port: number): Promise<void>;