@superblocksteam/shared 0.9607.3 → 0.9608.0

package/src/socket/heartbeat.ts

@@ -0,0 +1,469 @@
+/**
+ * A paced liveness beat over a request channel.
+ *
+ * Every long-lived socket in this repo eventually needs the same thing: proof
+ * that the peer is still answering, cheaply, for as long as the connection is
+ * held. The naive version - an interval that fires a request and counts the
+ * failures - is wrong in three ways that only show up under load, and each one
+ * was found the hard way:
+ *
+ *   1. A request inherits the channel's own budget, which is the whole
+ *      caller-facing operation (minutes). A beat that borrows it cannot report a
+ *      miss inside any window a caller waits in, so it holds its own deadline.
+ *   2. Without an in-flight guard, a peer that stopped answering collects a new
+ *      pending request every interval, none of which can ever be reconciled.
+ *      The answer paces the beats, not the interval.
+ *   3. A beat's response shares the socket with bulk pushes, so a large transfer
+ *      head-of-line blocks the answer past any sane deadline while the
+ *      connection is perfectly healthy. Acting on that kills a busy socket and,
+ *      where the caller reconnects, re-sends the same payload and does it again.
+ *
+ * The third is the subtle one, and it takes two guards, because neither is
+ * sufficient alone. Inbound traffic during the beat's own wait proves the
+ * connection is alive - but a bulk RPC response is a single websocket message,
+ * and no receive event fires until its last byte lands, so that cannot be the
+ * only guard. A single missed beat therefore also gets grace: a transfer merely
+ * has to finish inside one extra interval for the next answer to get through.
+ *
+ * Both guards answer to one bound. Inbound data proves the receive path, not
+ * that the request channel answers, so no amount of either excuse may let a
+ * wedged channel hide forever: once
+ * {@link SocketHeartbeatOptions.maxConsecutiveUnanswered} beats in a row have
+ * gone unanswered, the next silence is believed whatever the reason, and the
+ * grace is bypassed with it.
+ *
+ * Extracted from the browser editor's dev-server heartbeat, which learned all
+ * of the above the hard way and is the first thing to beat with it.
+ */
+
+/** Why a beat settled the way it did. */
+export type BeatOutcome =
+  /** Answered. The peer is there and the channel works. */
+  | 'success'
+  /** A definite answer that was an error. It arrived, so the channel works. */
+  | 'refused'
+  /** Unanswered, but the socket was provably delivering data. Excused. */
+  | 'lapse'
+  /** Unanswered and believed, but held back so a slow transfer can catch up. */
+  | 'grace'
+  /** Unanswered and believed. The caller should act on this one. */
+  | 'miss';
+
+/**
+ * Running account of the beat, readable at any time and reported when a socket
+ * dies.
+ *
+ * A socket can die before any beat settles, so `sent` counts beats issued
+ * rather than outcomes observed: unanswered beats are the strongest evidence
+ * there is that the peer was gone, and an account built from settled outcomes
+ * alone would report the most telling deaths as having nothing to say.
+ */
+export type HeartbeatAccount = {
+  /**
+   * Consecutive believed silences. Only an unanswered beat that nothing excused
+   * counts here, so this is what decides when the beat is lost - and why a
+   * refusal, which is an answer, can never close a connection on its own.
+   */
+  readonly failures: number;
+  /**
+   * Unanswered beats excused because the socket was provably delivering data at
+   * the time. Purely diagnostic: this is the difference between a dead
+   * connection and a live one whose request channel went quiet, which no close
+   * code can tell apart.
+   *
+   * Cleared by an answered beat or a new connection, not by a refusal - see
+   * {@link HeartbeatAccount.unanswered}.
+   */
+  readonly lapses: number;
+  readonly lastError?: string;
+  readonly lastReceivedAt?: number;
+  readonly lastSuccessAt?: number;
+  /**
+   * When the beat still waiting for its answer went out, or absent if none is.
+   *
+   * `sent` says a beat was issued and {@link HeartbeatAccount.lastSuccessAt}
+   * says one was answered; neither says whether the last one came back. Without
+   * this, a socket that answered a beat and then went silent is indistinguishable
+   * from one answering right up to the close.
+   *
+   * Deliberately survives {@link SocketHeartbeat.stop}, which is the first thing
+   * a caller does with a dead connection: the account is read after the socket
+   * is gone, no settle is coming for a retired beat, and clearing the stamp on
+   * the way out would erase the only record that a beat was outstanding.
+   */
+  readonly pendingSince?: number;
+  /**
+   * Consecutive beats answered with an error. Kept apart from
+   * {@link HeartbeatAccount.failures} because a refusal proves the channel
+   * works: it belongs in the report, never in the decision to give up on a
+   * connection.
+   */
+  readonly refusals: number;
+  /** Every beat issued, including one still waiting. */
+  readonly sent: number;
+  /**
+   * Beats that got no answer, excused or not. This is what the deferral bound is
+   * measured against, so it is also what says how long a silence had been
+   * tolerated when the beat was finally believed.
+   *
+   * Saturates at {@link SocketHeartbeatOptions.maxConsecutiveUnanswered}, so
+   * the run it reports can never exceed the bound it is measured against -
+   * beats keep going out after the alarm is raised, and an unbounded count
+   * would describe a silence longer than the one that was acted on.
+   *
+   * Cleared only by a definite success, proof of life, or a new connection. A
+   * refusal leaves it standing: it answers one beat, and were it to clear the
+   * run, a channel alternating between timing out and refusing could defer the
+   * bound forever while inbound traffic excused every silence.
+   */
+  readonly unanswered: number;
+};
+
+export interface SocketHeartbeatOptions {
+  /** Issues one beat. The cheapest authorized round trip the channel offers. */
+  beat: () => Promise<unknown>;
+  /** Gap between beats. A beat still in flight when one is due skips it. */
+  intervalMs: number;
+  /** How long one beat waits for its answer before it counts as unanswered. */
+  timeoutMs: number;
+  /**
+   * Consecutive genuine misses before the beat is declared lost. Defaults to
+   * {@link DEFAULT_MAX_CONSECUTIVE_MISSES}.
+   */
+  maxConsecutiveMisses?: number;
+  /**
+   * Consecutive unanswered beats to tolerate before neither proof of life nor
+   * grace may excuse another. Defaults to
+   * {@link DEFAULT_MAX_CONSECUTIVE_UNANSWERED}.
+   */
+  maxConsecutiveUnanswered?: number;
+  /**
+   * Renders a rejection for the account. Channels that reject with plain
+   * objects rather than `Error`s need this, or the cause reads
+   * `[object Object]`.
+   */
+  describeError?: (error: unknown) => string;
+  /**
+   * Whether a rejection means the beat went unanswered, as opposed to being
+   * refused. Only an unanswered beat can lapse or be believed: a refusal is a
+   * definite answer about the peer, and treating it as silence would hide the
+   * very thing it reports. Defaults to recognizing this heartbeat's own
+   * deadline.
+   */
+  isUnanswered?: (error: unknown) => boolean;
+  /**
+   * The beat is lost: enough consecutive beats went unanswered that the peer
+   * cannot be assumed to be there.
+   *
+   * Edge-triggered. It fires on the beat that crosses the threshold and stays
+   * quiet until proof of life re-arms it, because the counters it reports are
+   * an account read at socket death - resetting them to re-arm the alarm would
+   * erase the evidence the death report is built from.
+   *
+   * Throwing from here says the loss could not be acted on - the socket lookup
+   * failed, the close was rejected - and re-arms the alarm, because the
+   * connection this was meant to tear down is still there. A caller that
+   * swallows its own failure instead gets one alarm for a teardown that never
+   * happened.
+   *
+   * A refusal never reaches this. The peer answered, so whatever is wrong is
+   * not the connection, and tearing one down over an application-level refusal
+   * would replace a working channel with an outage.
+   */
+  onLost: (account: HeartbeatAccount) => void;
+  /** Every settled beat, for telemetry. Receives the account at settle time. */
+  onOutcome?: (outcome: BeatOutcome, durationMs: number, account: HeartbeatAccount) => void;
+  /**
+   * Whether the channel can carry a beat at all right now - an authorized
+   * credential, an open socket. A gate that is closed skips the beat entirely
+   * rather than counting it, because a channel with nothing to protect yet has
+   * neither missed nor answered anything.
+   */
+  shouldBeat?: () => boolean;
+}
+
+export const DEFAULT_MAX_CONSECUTIVE_MISSES = 2;
+export const DEFAULT_MAX_CONSECUTIVE_UNANSWERED = 8;
+
+type Timer = ReturnType<typeof setTimeout>;
+
+/** Keeps a Node timer from holding the process open; a no-op in a browser. */
+function unref(timer: Timer): void {
+  (timer as unknown as { unref?: () => void }).unref?.();
+}
+
+/** This heartbeat's own deadline, so a rejection it raised is recognizable. */
+class BeatTimeoutError extends Error {
+  public constructor(timeoutMs: number) {
+    super(`beat timed out after ${timeoutMs}ms`);
+    this.name = 'BeatTimeoutError';
+  }
+}
+
+function describeUnknownError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'object' && error !== null) {
+    const { message } = error as { message?: unknown };
+    if (typeof message === 'string' && message.length > 0) {
+      return message;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  return String(error);
+}
+
+type MutableAccount = {
+  -readonly [K in keyof HeartbeatAccount]: HeartbeatAccount[K];
+};
+
+const emptyAccount = (): MutableAccount => ({ failures: 0, lapses: 0, refusals: 0, sent: 0, unanswered: 0 });
+
+export class SocketHeartbeat {
+  private inFlight = false;
+  private intervalTimer: Timer | undefined;
+  /**
+   * Identifies the current chain of scheduled beats.
+   *
+   * Separate from {@link epoch} on purpose: a reset means a new connection, not
+   * a new cadence, so retiring an in-flight beat must not also unhook the
+   * interval that would have issued the next one.
+   */
+  private intervalToken = 0;
+  /** Whether the alarm has already been raised for the current run of misses. */
+  private lost = false;
+  /**
+   * Bumped by every start, stop and reset.
+   *
+   * A deadline armed for a previous connection fires after a reconnect - an
+   * intentional close does not reject the request it was waiting on - and
+   * letting it tick the new run's counters would condemn a healthy socket on
+   * the strength of a dead one's silence.
+   */
+  private epoch = 0;
+  private state: MutableAccount = emptyAccount();
+
+  public constructor(private readonly options: SocketHeartbeatOptions) {}
+
+  /** A snapshot, so a caller holding it cannot be surprised by a later beat. */
+  public get account(): HeartbeatAccount {
+    return { ...this.state };
+  }
+
+  /**
+   * Begins beating on a fresh account, replacing any cadence already running.
+   *
+   * Returns the way to stop *this* cadence. The disposer is inert once a later
+   * start has replaced it, which matters whenever one heartbeat is shared
+   * across successive connections: a superseded connection's teardown arrives
+   * late, and an unguarded stop would silently take the live connection's beat
+   * down with it.
+   */
+  public start(): () => void {
+    this.stop();
+    this.reset();
+    this.schedule();
+    const token = this.intervalToken;
+    return () => {
+      if (token === this.intervalToken) {
+        this.stop();
+      }
+    };
+  }
+
+  public stop(): void {
+    this.invalidate();
+    this.intervalToken += 1;
+    if (this.intervalTimer) {
+      clearTimeout(this.intervalTimer);
+      this.intervalTimer = undefined;
+    }
+  }
+
+  /**
+   * Starts the account over for a new connection, without touching the
+   * interval.
+   *
+   * Separate from {@link start} because a caller may learn it has a new
+   * connection before it is ready to beat on one, and the old socket's armed
+   * deadline has to stop counting the moment that happens rather than when the
+   * first new beat goes out.
+   */
+  public reset(): void {
+    this.invalidate();
+    this.state = emptyAccount();
+  }
+
+  /**
+   * Beats once, now, outside the interval.
+   *
+   * For callers with a reason to check immediately - a user who just came back
+   * to the keyboard - rather than waiting out a cadence sized for idle
+   * connections. Safe alongside a running interval: the in-flight guard means
+   * one of the two simply skips.
+   */
+  public async beatNow(): Promise<void> {
+    await this.fire(this.epoch);
+  }
+
+  /**
+   * Stamps inbound traffic. Call this for every message the socket delivers:
+   * it is what lets a beat starved behind a bulk transfer be told apart from
+   * one starved by a peer that is gone.
+   */
+  public recordReceive(): void {
+    this.state.lastReceivedAt = Date.now();
+  }
+
+  /** Retires whatever is in flight, so its settle cannot touch the next run. */
+  private invalidate(): void {
+    this.epoch += 1;
+    this.inFlight = false;
+    this.lost = false;
+  }
+
+  private schedule(): void {
+    const token = this.intervalToken;
+    this.intervalTimer = setTimeout(() => {
+      if (token !== this.intervalToken) {
+        return;
+      }
+      // Rescheduled before the beat is issued rather than after it settles, so
+      // the interval stays the gap between beats instead of drifting by however
+      // long each answer took.
+      this.schedule();
+      void this.fire(this.epoch);
+    }, this.options.intervalMs);
+    unref(this.intervalTimer);
+  }
+
+  private async fire(armedEpoch: number): Promise<void> {
+    if (this.inFlight || this.options.shouldBeat?.() === false) {
+      return;
+    }
+    this.inFlight = true;
+    this.state.sent += 1;
+    const sentAt = Date.now();
+    this.state.pendingSince = sentAt;
+    let deadline: Timer | undefined;
+    try {
+      await Promise.race([
+        this.options.beat(),
+        new Promise<never>((_, reject) => {
+          deadline = setTimeout(() => reject(new BeatTimeoutError(this.options.timeoutMs)), this.options.timeoutMs);
+          unref(deadline);
+        })
+      ]);
+      this.settle(armedEpoch, sentAt, undefined);
+    } catch (error) {
+      this.settle(armedEpoch, sentAt, error ?? new Error('beat failed'));
+    } finally {
+      if (deadline !== undefined) {
+        clearTimeout(deadline);
+      }
+      // Only this epoch's beat owns the guard. Releasing it after a reset would
+      // let a stale settle admit a second concurrent beat.
+      if (armedEpoch === this.epoch) {
+        this.inFlight = false;
+      }
+    }
+  }
+
+  private settle(armedEpoch: number, sentAt: number, error: unknown): void {
+    if (armedEpoch !== this.epoch) {
+      // A beat belonging to a connection that is already gone. It says nothing
+      // about the current one, so it is neither counted nor reported.
+      return;
+    }
+    const durationMs = Date.now() - sentAt;
+    // Nothing is outstanding any more: this beat is the one that was, and a
+    // stale-epoch beat returned above without touching the current run's stamp.
+    delete this.state.pendingSince;
+    const outcome = error === undefined ? this.recordAnswer() : this.recordRejection(error, sentAt);
+    const account = this.account;
+    this.options.onOutcome?.(outcome, durationMs, account);
+    if (outcome === 'miss' && !this.lost) {
+      this.lost = true;
+      try {
+        this.options.onLost(account);
+      } catch {
+        // The caller could not act on the loss, so the connection it meant to
+        // tear down is still there and still not answering. Re-arm, or the one
+        // alarm this run gets has been spent on a teardown that never happened.
+        // Swallowed rather than rethrown: `settle` already runs inside the
+        // beat's own catch, and throwing from here escapes `fire` as an
+        // unhandled rejection.
+        this.lost = false;
+      }
+    }
+  }
+
+  private recordAnswer(): BeatOutcome {
+    this.state.failures = 0;
+    this.state.lapses = 0;
+    this.state.refusals = 0;
+    this.state.unanswered = 0;
+    this.state.lastSuccessAt = Date.now();
+    this.lost = false;
+    delete this.state.lastError;
+    return 'success';
+  }
+
+  private recordRejection(error: unknown, sentAt: number): BeatOutcome {
+    const describe = this.options.describeError ?? describeUnknownError;
+    if (!(this.options.isUnanswered ?? ((cause) => cause instanceof BeatTimeoutError))(error)) {
+      // A definite answer, and recorded as one: a peer that answers is
+      // reachable, so a refusal must never close a connection over what is an
+      // application-level problem.
+      //
+      // It answers this beat and no others, so every count of what went
+      // missing is left exactly as it stands. Clearing `failures` would spend
+      // a refusal on the grace meant for a starved pong; clearing `unanswered`
+      // would hand a channel that alternates between timing out and refusing
+      // an unlimited deferral, because where inbound traffic excuses every
+      // silence that counter is the only thing left that can end one.
+      this.state.refusals += 1;
+      this.state.lastError = describe(error);
+      return 'refused';
+    }
+    // Saturating rather than growing: this is what the caller reports as the
+    // length of the silence that killed the connection, and beats keep going
+    // out after the alarm is raised - the caller still has a socket to tear
+    // down - so an unbounded count would report a run longer than the bound it
+    // is measured against.
+    this.state.unanswered = Math.min(this.state.unanswered + 1, this.maxConsecutiveUnanswered);
+    // The cause of every unanswered beat, excused or not. A lapse that leaves
+    // this stale would have the log for an excused timeout name whatever failed
+    // before it.
+    this.state.lastError = describe(error);
+    const excusable = this.state.unanswered < this.maxConsecutiveUnanswered;
+    if (excusable && this.receivedSince(sentAt)) {
+      this.state.lapses += 1;
+      // Traffic during the beat's own wait proves the connection is alive, which
+      // clears an earlier suspicion as surely as an answer would.
+      this.state.failures = 0;
+      this.lost = false;
+      return 'lapse';
+    }
+    this.state.failures += 1;
+    return excusable && this.state.failures < this.maxConsecutiveMisses ? 'grace' : 'miss';
+  }
+
+  /** Traffic that arrived while this beat was waiting, not merely at some point. */
+  private receivedSince(sentAt: number): boolean {
+    return this.state.lastReceivedAt !== undefined && this.state.lastReceivedAt >= sentAt;
+  }
+
+  private get maxConsecutiveMisses(): number {
+    return this.options.maxConsecutiveMisses ?? DEFAULT_MAX_CONSECUTIVE_MISSES;
+  }
+
+  private get maxConsecutiveUnanswered(): number {
+    return this.options.maxConsecutiveUnanswered ?? DEFAULT_MAX_CONSECUTIVE_UNANSWERED;
+  }
+}

package/src/socket/index.ts

@@ -1,5 +1,6 @@
 // the implementation of ISocket
 // this is protocol agnostic, it only handles the communication
+export * from './heartbeat.js';
 export * from './socket.js';
 export * from './socketWithClientAuth.js';
 export * from './types.js';

package/src/socket/util.test.ts

@@ -33,7 +33,7 @@ describe('connectWebSocket User-Agent', () => {
 
     expect(constructorSpy).toHaveBeenCalledWith(
       'wss://example.com/api/v1/rpc-ws',
-      undefined,
+      [],
       expect.objectContaining({
         maxPayload: MAX_SOCKET_PAYLOAD_BYTES,
         headers: expect.objectContaining({ 'User-Agent': DEFAULT_WEBSOCKET_USER_AGENT })
@@ -46,7 +46,7 @@ describe('connectWebSocket User-Agent', () => {
 
     expect(constructorSpy).toHaveBeenCalledWith(
       'wss://example.com/api/v1/rpc-ws',
-      undefined,
+      [],
       expect.objectContaining({
         headers: expect.objectContaining({ 'User-Agent': 'superblocks-cli/9.9.9' })
       })
@@ -58,6 +58,18 @@ describe('connectWebSocket User-Agent', () => {
 
     expect(constructorSpy).toHaveBeenCalledWith('wss://example.com/api/v1/rpc-ws', 'editor', expect.anything());
   });
+
+  it('offers no subprotocol at all when the caller asked for none', () => {
+    // A browser turns an explicit `undefined` here into the literal string
+    // "undefined" on the wire, so a caller that wanted no role ends up offering
+    // one no server implements. An empty list is the only value that reaches the
+    // handshake as "no subprotocol offered".
+    void connectWebSocket('wss://example.com/api/v1/rpc-ws');
+
+    const [, protocol] = constructorSpy.mock.calls[0] as [string, unknown, unknown];
+    expect(protocol).toEqual([]);
+    expect(protocol).not.toBeUndefined();
+  });
 });
 
 describe('buildClientUserAgent', () => {

package/src/socket/util.ts

@@ -45,7 +45,21 @@ export interface ConnectWebSocketOptions {
 export function connectWebSocket(wsUrl: string, options: ConnectWebSocketOptions = {}): Promise<WebSocket> {
   const { protocol, timeout = 30_000, headers } = options;
   return new Promise((resolve, reject) => {
-    const ws = new WebSocket(wsUrl, protocol, {
+    // `protocol ?? []` normalizes "no role asked for" to the empty list. It is
+    // defensive only: both runtimes this reaches already collapse an explicit
+    // `undefined` to the same thing, so neither offers a subprotocol that was
+    // never requested. A browser applies the WebIDL default (`protocols` is
+    // optional with default `[]`, and an explicit `undefined` selects it), and
+    // isomorphic-ws hands browsers the native WebSocket. Node takes `ws`, which
+    // maps `undefined` to `[]` before building the header (websocket.js: `if
+    // (protocols === undefined) protocols = []`).
+    //
+    // What does break a handshake is a *string* naming a role the server does
+    // not implement: it answers without echoing a subprotocol, the client fails
+    // the handshake, and it reads as a dead dev server rather than a bad offer.
+    // `??` cannot catch that - a string is not nullish - so a caller that
+    // stringifies its own value still offers the bogus role.
+    const ws = new WebSocket(wsUrl, protocol ?? [], {
       maxPayload: MAX_SOCKET_PAYLOAD_BYTES,
       headers: { 'User-Agent': DEFAULT_WEBSOCKET_USER_AGENT, ...headers }
     });

package/src/types/ai/index.ts

@@ -60,9 +60,12 @@ export interface AiResolveAttachmentLeasesResponse {
  * System event trigger types for AI operations without prompt_id
  */
 export enum AiSystemTriggerType {
+  API_USAGE_SUMMARY = 'api_usage_summary',
   APP_NAME = 'app_name',
+  ATTACHMENT_LABEL = 'attachment_label',
   COMMIT_MESSAGE = 'commit_message',
   DASHBOARD_CHAT = 'dashboard_chat',
+  ERROR_SUMMARY = 'error_summary',
   FACT_METADATA = 'fact_metadata',
   PR_DESCRIPTION = 'pr_description'
 }

package/src/types/application/index.ts

@@ -479,6 +479,20 @@ export interface IHomepageApplicationV2Dto extends IResourceMetadata {
     name: string;
     email: string;
   };
+  /** Per-requesting-user last editor open; null when this user has never opened the app. */
+  lastOpenedAt?: Date | null;
+}
+
+/** Where the user last opened the app; drives Home recent-card destination. */
+export type ApplicationOpenMode = 'deployed' | 'editor';
+
+/** One item in the per-user "recently opened" list on Home. */
+export interface IRecentApplicationDto {
+  devEnvEnabled: boolean;
+  id: string;
+  lastOpenedAt: Date;
+  lastOpenMode: ApplicationOpenMode;
+  name: string;
 }
 
 export interface ApplicationV2GlobalDto {

package/src/types/codeSecurity/index.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveScannedPackageVersion } from './index.js';
+
+describe('resolveScannedPackageVersion', () => {
+  it('prefers an exact resolved version', () => {
+    expect(resolveScannedPackageVersion('^8.5.18', '8.5.20')).toBe('8.5.20');
+  });
+
+  it("falls back to the declared range's minimum version when unresolved", () => {
+    expect(resolveScannedPackageVersion('^8.5.18', null)).toBe('8.5.18');
+  });
+
+  it('falls back to the declared range when resolved is an empty string', () => {
+    expect(resolveScannedPackageVersion('^8.5.18', '')).toBe('8.5.18');
+  });
+
+  it('returns null for specs semver cannot parse', () => {
+    expect(resolveScannedPackageVersion('workspace:*', null)).toBeNull();
+  });
+});