@wrongstack/cli 0.291.2 → 0.292.0

package/dist/hq-server.d.ts

@@ -1,53 +1,61 @@
-import { type HqTranscriptEntry } from '@wrongstack/core';
+/**
+ * HQ server — the read-only command-center backend for `wstack --hq`.
+ *
+ * Single HTTP server, single port. Two WebSocket upgrade paths:
+ *   /ws/client  — TUI/REPL/WebUI clients publish telemetry
+ *   /ws/browser — HQ browser connects and receives snapshot + events
+ *
+ * Phase 1 is read-only: the HQ browser observes what clients publish. No
+ * control commands are sent to clients from the browser yet.
+ *
+ * Mailbox aggregation: every `mailbox.snapshot` envelope from a client is
+ * stored per-(client, mailbox) and merged into the global HqSnapshot on
+ * each browser poll / broadcast. Mailbox events still flow through as
+ * transient events; snapshots give us the authoritative rollups.
+ *
+ * @module hq-server
+ */
 import { HQ_HTML } from './hq-dashboard-html.js';
+import { readLocalSubagentTranscript, agentRingKey, agentMessageToEntry, decodePathSegment, sanitizeApiError } from './hq-server/routes.js';
+import type { ConnectedClient, TranscriptRing } from './hq-server/types.js';
+export type { ConnectedClient, TranscriptRing };
+export { HqInsecureExposureError } from '@wrongstack/core';
+export { HQ_HTML };
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 3499;
+export declare const MAX_EVENT_LOG = 5000;
+export declare const MAX_NON_STRICT_PORT_SCAN = 50;
+export declare const CLIENT_TTL_MS = 60000;
+export declare const CLIENT_CLEANUP_INTERVAL_MS = 30000;
+export declare const BROWSER_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const SESSION_SNAPSHOT_TTL_MS = 30000;
+export { readLocalSubagentTranscript, decodePathSegment, sanitizeApiError, agentRingKey, agentMessageToEntry, };
 export interface HqServerOptions {
     host?: string;
     port?: number;
     strictPort?: boolean;
-    /**
-     * When true, the server binds exactly to `port` and fails with an error
-     * if that port is already in use — no port scanning. Use this when the
-     * user explicitly selected a port and we should not silently pick another.
-     */
     exactPort?: boolean;
-    /**
-     * HQ data directory. When omitted, the server resolves one via
-     * `resolveHqDataDir()` (honoring `WRONGSTACK_HQ_DATA_DIR` then falling
-     * back to `~/.wrongstack/hq`). The directory holds `auth.json` and, in
-     * later phases, the persistent event log and snapshot cache.
-     */
     dataDir?: string;
-    /** Browser liveness frame interval. Primarily exposed for deterministic integration tests. */
     browserHeartbeatIntervalMs?: number;
-    /** Connected-client inactivity timeout. Primarily exposed for deterministic integration tests. */
     clientTtlMs?: number;
-    /** Stale-client scan interval. Primarily exposed for deterministic integration tests. */
     clientCleanupIntervalMs?: number;
-    /** Session-snapshot freshness timeout. Primarily exposed for deterministic integration tests. */
     sessionSnapshotTtlMs?: number;
-    /** Optional browser password login. Sets or rotates the scrypt hash in auth.json. */
     password?: string;
-    /**
-     * Allow a non-loopback bind while HQ is in open mode (no tokens, no
-     * password). Off by default: that pairing serves POST /api/command
-     * unauthenticated to the whole network. See assessHqExposure.
-     */
     allowInsecureOpen?: boolean;
-    /**
-     * Set `Secure` flag on session cookies. Enable this when HQ is behind a
-     * TLS-terminating reverse proxy. Defaults to `false` because HQ speaks
-     * plain HTTP; setting `Secure` on an HTTP cookie makes it invisible to
-     * the browser.
-     */
     secureCookies?: boolean;
+    requireBrowserAuth?: boolean;
     /**
-     * Keep browser authentication enabled for the full server lifetime. Used
-     * by public relays such as --tunnel so an auth.json reload cannot silently
-     * turn an authenticated public endpoint into open mode.
+     * Optional time-to-live (milliseconds) stamped on the first-run browser
+     * and client tokens minted on a brand-new HQ data directory. Existing
+     * auth.json files are not modified. When set, tokens carry an `expiresAt`
+     * and the server refuses them past that timestamp; default is no expiry.
+     *
+     * Useful for short-lived deployments (CI, ephemeral relays) where a leaked
+     * first-run token should not outlive the deployment window. Set via the
+     * `--hq-token-ttl-ms` CLI flag.
      */
-    requireBrowserAuth?: boolean;
+    tokenTtlMs?: number;
 }
-export { HqInsecureExposureError } from '@wrongstack/core';
 export interface HqStartupConnectionInfo {
     dataDir: string;
     browserUrl: string;
@@ -65,32 +73,8 @@ export interface HqServerHandle {
     host: string;
     port: number;
     firstRunSetup?: HqFirstRunSetup;
-    /** Authorize an exact browser-facing HTTPS origin established by trusted server code. */
     trustPublicOrigin(origin: string): void;
     close(): Promise<void>;
 }
-/**
- * Read one local subagent's FULL conversation from disk. The agent monitor
- * writes every timeline entry to
- *   <projectSessions>/<sessionId>/subagents/transcripts/<subId>/transcript.jsonl
- * so for sessions on THIS machine we can serve the complete history — not
- * just the ≤4000-entry live ring. Returns null when the session isn't local
- * or the file is absent (caller falls back to the ring).
- */
-export declare function readLocalSubagentTranscript(sessionId: string, subagentId: string): Promise<HqTranscriptEntry[] | null>;
-/**
- * Library default: loopback. `startHqServer` is called programmatically
- * (tests, embedders) as well as from the CLI, and a caller that never
- * mentions a host has not asked to be reachable from the network.
- *
- * HQ is still the deliberate cross-machine surface — the CLI entry points
- * (`wstack hq`, the launch menu) pass HQ_CLI_DEFAULT_HOST explicitly, so
- * `wstack hq` binds every interface with no extra flag. Keeping the wide
- * bind at the CLI edge rather than in this default is what stops an
- * unrelated embedder from silently publishing HQ to its whole network.
- */
-export declare const DEFAULT_HOST = "127.0.0.1";
-export declare const DEFAULT_PORT = 3499;
-export { HQ_HTML };
 export declare function startHqServer(options?: HqServerOptions): Promise<HqServerHandle>;
 //# sourceMappingURL=hq-server.d.ts.map

package/dist/hq-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hq-server.d.ts","sourceRoot":"","sources":["../src/hq-server.ts"],"names":[],"mappings":"AAsBA,OAAO,EA0BL,KAAK,iBAAiB,EAevB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAUjD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,iGAAiG;IACjG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE;QACT,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC,yFAAyF;IACzF,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAkHD;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,EAAE,GAAG,IAAI,CAAC,CA4BrC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,YAAY,OAAO,CAAC;AA8HjC,OAAO,EAAE,OAAO,EAAE,CAAC;AAgLnB,wBAAsB,aAAa,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAwD1F"}
+{"version":3,"file":"hq-server.d.ts","sourceRoot":"","sources":["../src/hq-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAoCH,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAIjD,OAAO,EAaL,2BAA2B,EAC3B,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,aAAa,OAAO,CAAC;AAClC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,CAAC;AAIF,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE;QACT,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID,wBAAsB,aAAa,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqD1F"}