@wrongstack/tools 0.320.1 → 1.0.1

package/dist/codebase-index/project-server-framing.d.ts

@@ -0,0 +1,29 @@
+import { type ProjectServerClientMessage, type ProjectServerMessage } from './project-server-protocol.js';
+import type { ClientState } from './project-server-types.js';
+/**
+ * Cap on outbound bytes queued for one client before it is dropped. This
+ * server pushes index-activity updates to every client, and `socket.write()`
+ * buffers without limit when its `false` return is ignored — so one client
+ * that stops reading would otherwise grow the owner's heap indefinitely. The
+ * index lives in SQLite; a dropped client re-queries on reconnect.
+ */
+export declare const MAX_CLIENT_WRITE_BUFFER_BYTES: number;
+export declare function sendServerMessage(state: ClientState, message: ProjectServerMessage): void;
+/**
+ * Frame reader for one client connection. Each frame is sniffed per first
+ * byte: `0x57` ('W') → length-prefixed MessagePack, anything else →
+ * newline-delimited JSON text. Bytes stay raw until a complete frame is
+ * assembled, so a multibyte UTF-8 sequence split across chunks is only ever
+ * decoded as part of a finished line (raw `0x0a` only occurs as the JSON
+ * delimiter — inside JSON strings `\n` is escaped — so a complete line is
+ * always complete UTF-8).
+ *
+ * The buffer is consumed with a scan offset rather than re-slicing after
+ * every frame: each parsed frame advances `scan` within the same Buffer,
+ * and the leftover tail is compacted once at the end of the call. A burst
+ * of small frames therefore costs one allocation per chunk, not one
+ * per frame (the previous slice-per-frame loop reallocated on every frame
+ * while pinning the whole parent buffer).
+ */
+export declare function consumeClientChunk(state: ClientState, chunk: Buffer, onMessage: (state: ClientState, message: ProjectServerClientMessage) => void): void;
+//# sourceMappingURL=project-server-framing.d.ts.map

package/dist/codebase-index/project-server-lifecycle.d.ts

@@ -0,0 +1,20 @@
+import type { ProjectIndexServerMetadata } from './project-server-protocol.js';
+export declare function removeMetadataIfOwned(metadataPath: string, pid: number): void;
+export declare function writeProjectServerMetadata(metadataPath: string, metadata: ProjectIndexServerMetadata): Promise<void>;
+/**
+ * One SIGINT/SIGTERM pair per PROCESS, not per module instance.
+ *
+ * The in-process test harness imports this module once per test case with a
+ * `?case=<n>` query URL, so every case evaluates this module body fresh; a
+ * bare top-level `process.once(signal, ...)` pair accumulates one handler
+ * per case until Node raises MaxListenersExceededWarning in every coverage
+ * run. The guard lives on globalThis under a Symbol.for key: the first
+ * evaluation registers the pair, every evaluation re-targets it at its own
+ * `stop`, and a fired signal removes the pair (once semantics).
+ */
+export interface CodebaseIndexSignalGuard {
+    arm(stop: (signal: string) => Promise<void>): void;
+}
+export declare const SIGNAL_GUARD: unique symbol;
+export declare function armCodebaseIndexSignalGuard(stop: (signal: string) => Promise<void>): void;
+//# sourceMappingURL=project-server-lifecycle.d.ts.map

package/dist/codebase-index/project-server-operations.d.ts

@@ -0,0 +1,37 @@
+import type { ProjectIndexServerActivity, ProjectServerClientMessage, ProjectServerMessage } from './project-server-protocol.js';
+import { type ServerQueryCaches } from './project-server-query-cache.js';
+import type { ActiveFullIndex, ClientState } from './project-server-types.js';
+import type { IndexOpArgs, OpShapes } from './worker-protocol.js';
+export interface OperationContext {
+    projectRoot: string;
+    indexDir: string;
+    queryCaches: ServerQueryCaches;
+    getActivity: () => ProjectIndexServerActivity;
+    withIndexWrite: <T>(job: (onProgress: (currentFile: number, totalFiles: number) => void) => Promise<T>, options: {
+        preserveCaches: boolean;
+    }) => Promise<T>;
+    send: (state: ClientState, message: ProjectServerMessage) => void;
+    getActiveFullIndex: () => ActiveFullIndex | null;
+    setActiveFullIndex: (active: ActiveFullIndex | null) => void;
+}
+/**
+ * Cache policy at write-run completion.
+ *
+ * A run with an explicit targeted file list (edit/watcher reindex) makes a
+ * per-file surgical change, so — on success — every previous-generation entry
+ * stays valid as a stale answer for the NEXT refresh. On failure the run's
+ * transaction rolls back, which equally leaves the cached entries describing
+ * the on-disk truth. (Precision: the rollback is per-file — a multi-file
+ * targeted run commits the files that parsed and rolls back only the failed
+ * one — but each file's slice is atomic, and queries never straddle slices,
+ * so cached answers stay correct.) Anything else (full scan, force rebuild,
+ * langs/ignore-filtered scan) can reshape the whole index, so its caches are
+ * dropped on completion and on failure alike.
+ */
+export declare function preservesQueryCaches(args: IndexOpArgs): boolean;
+export declare function isShareableFullIndex(args: IndexOpArgs): boolean;
+export declare function runFullIndex(ctx: OperationContext, state: ClientState, id: number, args: IndexOpArgs): Promise<OpShapes['index']['result']>;
+export declare function dispatchOperation(ctx: OperationContext, state: ClientState, message: Extract<ProjectServerClientMessage, {
+    type: 'request';
+}>): Promise<unknown>;
+//# sourceMappingURL=project-server-operations.d.ts.map

package/dist/codebase-index/project-server-types.d.ts

@@ -0,0 +1,30 @@
+import type * as net from 'node:net';
+import type { OpShapes } from './worker-protocol.js';
+export interface ClientState {
+    socket: net.Socket;
+    /**
+     * Raw inbound bytes. Frames may be newline-delimited JSON or length-
+     * prefixed binary (magic 0x57); the mode is sniffed per frame. Kept as
+     * bytes because a JSON text line may split a multibyte UTF-8 sequence at a
+     * chunk boundary — the StringDecoder handles that at parse time.
+     */
+    buffer: Buffer;
+    cancelled: Set<number>;
+    cancel: Map<number, () => void>;
+    watchExternal: boolean;
+    debounceMs: number;
+    coalesceWindowMs: number;
+    lastSeenAt: number;
+    /** True once this client has sent at least one binary frame. */
+    binary: boolean;
+}
+export interface FullIndexSubscriber {
+    state: ClientState;
+    id: number;
+}
+export interface ActiveFullIndex {
+    promise: Promise<OpShapes['index']['result']>;
+    controller: AbortController;
+    subscribers: Set<FullIndexSubscriber>;
+}
+//# sourceMappingURL=project-server-types.d.ts.map

package/dist/codebase-index/project-server-watcher.d.ts

@@ -0,0 +1,25 @@
+import type { ClientState } from './project-server-types.js';
+export declare const DEFAULT_EXTERNAL_DEBOUNCE_MS = 400;
+export declare const DEFAULT_EXTERNAL_COALESCE_WINDOW_MS = 50;
+export declare function isIgnoredRelativePath(relativePath: string): boolean;
+export interface ProjectServerWatcherOptions {
+    projectRoot: string;
+    onFilesChanged: (files: string[]) => void;
+}
+export declare class ProjectServerWatcherManager {
+    private readonly options;
+    private externalWatcher;
+    private externalDebounceMs;
+    private externalCoalesceWindowMs;
+    private readonly externalDebounceTimers;
+    private readonly externalReadyFiles;
+    private externalReadyFlush;
+    constructor(options: ProjectServerWatcherOptions);
+    get isWatching(): boolean;
+    get pendingFileCount(): number;
+    private enqueueExternalFile;
+    private ensureExternalWatcher;
+    stop(): void;
+    reconcile(clients: Iterable<ClientState>): void;
+}
+//# sourceMappingURL=project-server-watcher.d.ts.map