@aexol/spectral 0.9.234 → 0.9.241

package/dist/utils/serve-state.d.ts

@@ -0,0 +1,264 @@
+/**
+ * On-disk rendezvous between `spectral serve` (the relay daemon) and whoever
+ * launched it — today `spectral desktop`, tomorrow any supervisor.
+ *
+ * Two files, both under `getConfigDir()` (`~/.spectral`, or `SPECTRAL_CONFIG_DIR`
+ * in tests/CI):
+ *
+ *   serve.pid        the daemon's own pid (single-instance lock)
+ *   serve-ready.json { pid, ts, version } written once the relay socket is open
+ *
+ * Why both: the pid file alone says "a process exists", not "the relay is
+ * connected" — and the web app at aexol.ai/agent subscribes to the relay the
+ * moment it loads, so opening the browser before the socket is up produces a
+ * `machine_disconnected` on every start (the exact bug the removed Electron app
+ * papered over with a 3-second `setTimeout`). `serve-ready.json` plus the
+ * `SPECTRAL_SERVE_READY` stdout marker give the launcher a real signal.
+ *
+ * A stale pid file (SIGKILL, power loss, crash) is expected: every reader
+ * sanity-checks liveness with `kill(pid, 0)` and removes dead entries, so a
+ * crashed daemon never blocks the next start.
+ *
+ * Ownership is explicit: the pid file is a *claim*, taken atomically with
+ * `O_EXCL` ({@link claimServePidFile}) and only ever rewritten or removed by
+ * whoever holds it ({@link ownsServeState}). A launcher that merely *read* the
+ * file must never treat it as its own, and a process that lost the claim must
+ * not overwrite the state of the daemon that actually owns it.
+ *
+ * All helpers are synchronous and never throw — a daemon must not fail because
+ * a bookkeeping file could not be written.
+ */
+/** Line `spectral serve` prints to stdout once the relay socket is open. */
+export declare const SERVE_READY_MARKER = "SPECTRAL_SERVE_READY";
+/** Serve log size threshold past which `spectral desktop` rotates the log. */
+export declare const DEFAULT_SERVE_LOG_MAX_BYTES: number;
+/** Contents of `serve-ready.json`. */
+export interface ServeReadyInfo {
+    pid: number;
+    /** Unix epoch millis at which the relay became ready. */
+    ts: number;
+    /** CLI version that produced the ready signal. */
+    version: string;
+}
+export declare function getServePidFile(): string;
+export declare function getServeReadyFile(): string;
+/**
+ * @param env env to read `SPECTRAL_SERVE_LOG_PATH` from. Defaults to
+ *   `process.env`, but a caller that holds a custom env (the desktop spawn
+ *   plan) must pass it — otherwise the wrapper watches one file while the
+ *   daemon logs into another.
+ */
+export declare function getServeLogFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * Is `pid` a live process? Uses signal 0, which performs error checking
+ * without delivering a signal. `EPERM` counts as alive — the process exists,
+ * it just belongs to somebody else.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Genealogy verdicts for a live pid we did not spawn:
+ *
+ *   - `ours`     — provably a descendant of one of the given ancestors;
+ *   - `not-ours` — the parent chain was readable and reached init without
+ *     passing through an ancestor;
+ *   - `unknown`  — parentage could not be read (Windows, no `ps`, transient
+ *     probe failure under load).
+ *
+ * The distinction matters: `unknown` is NOT "ours". A live pid nobody can
+ * vouch for must never be classified as our daemon.
+ */
+export type ServeGenealogy = "ours" | "not-ours" | "unknown";
+/**
+ * Is `pid` a descendant of `ancestor`? Used to confirm that the pid file handed
+ * over after a spawn really belongs to the process we launched: under `tsx` the
+ * CLI re-execs, so the daemon is the *child* of the spawned pid.
+ *
+ * Best-effort: when parentage cannot be read (Windows, no `ps`, process gone)
+ * it answers true, i.e. "unknown" is treated as ours — a launcher must never
+ * block a legitimate start over an unverifiable genealogy. Callers that must
+ * keep "ours" apart from "unreadable" (see {@link confirmServePidChild}) use the
+ * strict tri-state verdict instead.
+ */
+export declare function isDescendantOf(pid: number, ancestor: number, maxDepth?: number): boolean;
+/** Write the pid file for the current (or given) daemon process. */
+export declare function writeServePid(pid?: number): void;
+/**
+ * Read a pid file WITHOUT a liveness check. Returns null when the file is
+ * missing or is not a plain pid. The whole payload must be digits: `parseInt`
+ * turns `"12abc"` into 12, and a launcher would then signal a process nobody
+ * claimed.
+ *
+ * @param file defaults to {@link getServePidFile}; tests and alternative
+ *   layouts may point elsewhere.
+ */
+export declare function readServePidFile(file?: string): number | null;
+/**
+ * Read the pid file WITH a liveness check. A stale entry (process gone) is
+ * deleted and reported as "not running".
+ */
+export declare function getLiveServePid(): number | null;
+/**
+ * Does `pid` hold the pid-file claim? Every cleanup and every ready-signal
+ * write is gated on this, so a second daemon (or a wrapper that merely read
+ * the file) can never delete or overwrite the state of the process that owns
+ * it.
+ */
+export declare function ownsServeState(pid?: number): boolean;
+export type ServePidClaim = 
+/** We hold the claim; the file currently records `placeholderPid`. */
+{
+    status: "claimed";
+    placeholderPid: number;
+}
+/** A live process holds it — reuse that daemon instead of spawning one. */
+ | {
+    status: "busy";
+    pid: number;
+}
+/** The claim could not be taken (e.g. unwritable config dir). */
+ | {
+    status: "failed";
+    error: string;
+};
+/**
+ * Atomically claim `serve.pid` BEFORE spawning anything.
+ *
+ * The naive version — read the file, ask "is it alive?", then spawn — races two
+ * concurrent `spectral desktop` invocations into starting two daemons, because
+ * both see "not running" before either writes. `open(O_EXCL)` folds the test
+ * and the claim into one syscall: exactly one winner, everyone else gets
+ * `busy`.
+ *
+ * The winner writes its *own* pid as a placeholder — a live pid, so a racer
+ * that arrives microseconds later also sees `busy` — and hands it over with
+ * {@link confirmServePidChild} once the spawn succeeded.
+ */
+export declare function claimServePidFile(placeholderPid?: number): ServePidClaim;
+export interface ServePidChildConfirmation {
+    status: "child" | "daemon" | "foreign" | "unknown";
+    pid: number | null;
+}
+export interface ConfirmServePidChildOptions {
+    /**
+     * Injectable genealogy verdict for tests. The real probe walks `ps -o ppid=`
+     * and can transiently fail under load, so tests pin the verdict to keep the
+     * `daemon`/`foreign`/`unknown` classification deterministic.
+     */
+    genealogy?: (pid: number, ancestors: number[]) => ServeGenealogy;
+}
+/**
+ * After a successful spawn, confirm `serve.pid` records the daemon we launched.
+ *
+ * - `child`   — it holds the spawned pid (the normal standalone/node case).
+ * - `daemon`  — the daemon already rewrote it with its own pid, which happens
+ *   when the CLI re-execs (`tsx` in dev). Accepted only when that pid is
+ *   provably our descendant.
+ * - `foreign` — a live, unrelated process owns it: the caller must warn and
+ *   stop touching the state instead of hijacking it.
+ * - `unknown` — the hand-off write did not land (read-only dir), or a live pid
+ *   this command did not spawn could not be verified as ours (unreadable
+ *   parentage); the caller must warn (unverified holder) but must never signal
+ *   it — readiness still works via the log marker and the ready file.
+ */
+export declare function confirmServePidChild(childPid: number, placeholderPid?: number, opts?: ConfirmServePidChildOptions): ServePidChildConfirmation;
+/**
+ * Drop a claim taken by {@link claimServePidFile} when the start failed. Only
+ * removes the files while they still record the placeholder or the child we
+ * launched — never a foreign daemon's state.
+ */
+export declare function releaseServePidClaim(placeholderPid?: number, childPid?: number): void;
+/** Write the readiness marker next to the pid file. */
+export declare function writeServeReady(version: string, pid?: number): ServeReadyInfo;
+/** Read `serve-ready.json`, or null when missing/corrupt. */
+export declare function readServeReadyFile(file?: string): ServeReadyInfo | null;
+/** Remove both the pid file and the ready file. Idempotent. */
+export declare function clearServeState(): void;
+/** Current size of a file, 0 when it does not exist yet. */
+export declare function fileSizeOf(file: string): number;
+/**
+ * Truncate a daemon log that outgrew {@link DEFAULT_SERVE_LOG_MAX_BYTES} by
+ * moving it aside as `<file>.old` (one generation kept — enough to debug the
+ * previous start, without an unbounded log growing forever).
+ *
+ * Must run BEFORE the new daemon is spawned and before the caller snapshots the
+ * log offset: after a rotate the fresh log starts at byte 0.
+ *
+ * @returns true when a rotation happened.
+ */
+export declare function rotateServeLogFile(file?: string, maxBytes?: number): boolean;
+/**
+ * Append-mode read: return the bytes written to `file` since `offset` and the
+ * new offset. The desktop launcher snapshots the log size before spawning so
+ * the `SPECTRAL_SERVE_READY` marker of a *previous* run can never be mistaken
+ * for the current one.
+ *
+ * The returned offset is always the offset to read from next time — including
+ * when there is nothing new, and when the file shrank under us (a rotation).
+ * A caller that only advanced on new text would stay pinned past end-of-file
+ * and never see the next marker.
+ */
+export declare function readFromOffset(file: string, offset: number): {
+    text: string;
+    offset: number;
+};
+export interface WaitForServeReadyOptions {
+    /** Pid of the spawned serve process (used for the fast-fail path). */
+    pid: number;
+    /** Log file to scan for {@link SERVE_READY_MARKER}. */
+    logFile?: string;
+    /** Ready file to poll as fallback. Defaults to `serve-ready.json`. */
+    readyFile?: string;
+    /** Pid file consulted to recognise a re-exec'd daemon as the signal owner. */
+    pidFile?: string;
+    /** Byte offset in `logFile` to start scanning from. */
+    logOffset?: number;
+    /**
+     * Wall-clock millis captured BEFORE the daemon was spawned. A ready signal
+     * older than this belongs to an earlier run and is rejected. Defaults to 0
+     * (no freshness requirement) for callers that cannot know the spawn time.
+     */
+    sinceMs?: number;
+    /**
+     * True when the spawned child re-execs into the daemon (`tsx`/`ts-node` in
+     * dev). This pid is then only the wrapper, so the `process-exited` quick-fail
+     * is skipped and only the ready signal or the timeout decides.
+     */
+    expectReExec?: boolean;
+    /** Extra pids considered ours (tests, alternative supervisors). */
+    expectedPids?: number[];
+    timeoutMs?: number;
+    intervalMs?: number;
+    /** Injectable for tests. */
+    alive?: (pid: number) => boolean;
+}
+export type ServeReadyOutcome = "marker" | "ready-file" | "process-exited" | "timeout";
+export interface ServeReadyResult {
+    ok: boolean;
+    reason: ServeReadyOutcome;
+    waitedMs: number;
+    /** Ready-file payload when a ready signal was observed. */
+    info?: ServeReadyInfo;
+    /** Last chunk of daemon output, surfaced in error messages. */
+    logTail?: string;
+}
+/**
+ * Wait for the daemon to announce readiness, by either signal:
+ *   - `SPECTRAL_SERVE_READY` appearing in the serve log after `logOffset`, or
+ *   - a live `serve-ready.json`.
+ *
+ * A signal only counts when it belongs to THIS launch:
+ *   - the pid it reports is the spawned pid, or the pid `serve.pid` currently
+ *     records (the daemon's own pid once it re-exec'd), and
+ *   - its timestamp is not older than `sinceMs`, and
+ *   - that pid is alive.
+ *
+ * The log marker carries no pid of its own, so whenever a ready file exists it
+ * must pass the same check — a marker can never be trusted on its own while the
+ * ready file proves the signal came from a foreign or stale daemon.
+ *
+ * Gives up early when the child dies (registration/auth/sqlite failures) so the
+ * user sees the real error instead of waiting out the timeout, and always
+ * returns (never throws) with the tail of the log for diagnostics.
+ */
+export declare function waitForServeReady(opts: WaitForServeReadyOptions): Promise<ServeReadyResult>;
+//# sourceMappingURL=serve-state.d.ts.map

package/dist/utils/serve-state.d.ts.map

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