@todesktop/shared 7.191.1 → 7.192.0

package/lib/cjs/desktopify.d.ts

@@ -1,5 +1,6 @@
 import { Configuration, PackagerOptions, PublishOptions } from 'app-builder-lib';
 import { IApp2 } from './desktopify2';
+import { BreakpointPauseLease, BreakpointQueueEntry, CurrentBreakpointState } from './introspection/breakpoints';
 import { IApp } from './toDesktop';
 type appBuilderLib = PackagerOptions & PublishOptions;
 export interface IAppBuilderLib extends appBuilderLib {
@@ -92,6 +93,30 @@ export interface PlatformBuild {
     status: BuildStatus;
 }
 export type CIRunner = 'azure' | 'circle';
+export type IntrospectBreakpointStatus = 'error' | 'finished' | 'initializing' | 'paused' | 'ready' | 'resuming';
+export type IntrospectShellStatus = 'connected' | 'connecting' | 'disconnected' | 'error' | 'initializing' | 'ready';
+export interface IntrospectPlatformData {
+    breakpointQueue?: BreakpointQueueEntry[];
+    breakpointStatus: IntrospectBreakpointStatus;
+    connectedAt?: Date;
+    connectedUserId?: string;
+    createdAt: ISODate;
+    currentBreakpoint?: CurrentBreakpointState;
+    disconnectedAt?: Date;
+    enabled: boolean;
+    error?: string;
+    jtiExpiresAt?: Date;
+    pauseLease?: BreakpointPauseLease;
+    sessionJti?: string;
+    shellStatus: IntrospectShellStatus;
+    tunnelUrl?: string;
+    usedJti?: string;
+}
+export interface IntrospectData {
+    linux: IntrospectPlatformData;
+    mac: IntrospectPlatformData;
+    windows: IntrospectPlatformData;
+}
 export interface Build {
     appCustomDomain?: string;
     appName: string;
@@ -118,6 +143,7 @@ export interface Build {
     hash?: string;
     icon?: string;
     id: string;
+    introspect?: IntrospectData;
     isArtifactsPruned?: boolean;
     isBeingCancelled?: boolean;
     linux?: PlatformBuild;

package/lib/cjs/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.schemaVersion = void 0;
-/* eslint-disable @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports */
+/* eslint-disable @typescript-eslint/no-require-imports */
 // CJS-specific entry point
 // Path is relative to lib/cjs/ output directory
 const packageJson = require('../../package.json');

package/lib/cjs/introspection/__tests__/breakpoints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/cjs/introspection/__tests__/breakpoints.test.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const breakpoints_1 = require("../breakpoints");
+(0, vitest_1.describe)('isSameBreakpoint', () => {
+    (0, vitest_1.it)('matches identical phase breakpoints', () => {
+        (0, vitest_1.expect)((0, breakpoints_1.isSameBreakpoint)({ id: 'beforeInstall', type: 'phase' }, { id: 'beforeInstall', type: 'phase' })).toBe(true);
+    });
+    (0, vitest_1.it)('fails when breakpoint types differ', () => {
+        (0, vitest_1.expect)((0, breakpoints_1.isSameBreakpoint)({ id: 'beforeInstall', type: 'phase' }, { id: 'todesktop:beforeInstall', position: 'before', type: 'hook' })).toBe(false);
+    });
+    (0, vitest_1.it)('considers hook positions', () => {
+        (0, vitest_1.expect)((0, breakpoints_1.isSameBreakpoint)({ id: 'todesktop:beforeBuild', position: 'before', type: 'hook' }, { id: 'todesktop:beforeBuild', position: 'after', type: 'hook' })).toBe(false);
+    });
+    (0, vitest_1.it)('returns false when either side is undefined', () => {
+        (0, vitest_1.expect)((0, breakpoints_1.isSameBreakpoint)(undefined, { id: 'afterInstall', type: 'phase' })).toBe(false);
+    });
+});
+(0, vitest_1.describe)('cloneBreakpointQueue', () => {
+    (0, vitest_1.it)('produces a deep copy of the queue', () => {
+        const original = [
+            { hitAt: undefined, id: 'beforeInstall', type: 'phase' },
+            {
+                id: 'todesktop:afterPack',
+                position: 'after',
+                skipped: true,
+                type: 'hook',
+            },
+        ];
+        const copy = (0, breakpoints_1.cloneBreakpointQueue)(original);
+        (0, vitest_1.expect)(copy).toEqual(original);
+        (0, vitest_1.expect)(copy).not.toBe(original);
+        (0, vitest_1.expect)(copy[0]).not.toBe(original[0]);
+    });
+});
+(0, vitest_1.describe)('markQueueSkipped', () => {
+    (0, vitest_1.it)('marks the starting entry as skipped and adds fallback timestamps', () => {
+        const queue = [
+            { id: 'beforeInstall', type: 'phase' },
+            { id: 'afterInstall', type: 'phase' },
+        ];
+        const fallbackHitAt = '2024-01-01T00:00:00.000Z';
+        const updated = (0, breakpoints_1.markQueueSkipped)(queue, 0, { fallbackHitAt });
+        (0, vitest_1.expect)(updated[0]).toMatchObject({
+            hitAt: fallbackHitAt,
+            skipped: true,
+        });
+        (0, vitest_1.expect)(updated[1]).toMatchObject({ skipped: true });
+        (0, vitest_1.expect)(queue[0].skipped).toBeUndefined();
+    });
+    (0, vitest_1.it)('returns a cloned queue when index is out of bounds', () => {
+        const queue = [
+            { id: 'beforeInstall', type: 'phase' },
+        ];
+        const updated = (0, breakpoints_1.markQueueSkipped)(queue, 2);
+        (0, vitest_1.expect)(updated).toEqual(queue);
+        (0, vitest_1.expect)(updated).not.toBe(queue);
+    });
+});

package/lib/cjs/introspection/breakpoints.d.ts

@@ -0,0 +1,45 @@
+export declare const BREAKPOINT_DEFAULT_LEASE_MS: number;
+export declare const BREAKPOINT_RENEW_INCREMENT_MS: number;
+export declare const BREAKPOINT_MAX_REMAINING_MS: number;
+export type PhaseBreakpointId = 'afterInstall' | 'afterPack' | 'afterSourcePrep' | 'afterUpload' | 'beforeFinalize' | 'beforeInstall' | 'beforePack' | 'beforeUpload';
+export type HookBreakpointName = 'todesktop:afterPack' | 'todesktop:beforeBuild' | 'todesktop:beforeInstall';
+export type HookBreakpointPosition = 'after' | 'before';
+interface PhaseBreakpointConfig {
+    id: PhaseBreakpointId;
+    type: 'phase';
+}
+interface HookBreakpointConfig {
+    id: HookBreakpointName;
+    position: HookBreakpointPosition;
+    type: 'hook';
+}
+export type BreakpointConfig = HookBreakpointConfig | PhaseBreakpointConfig;
+export type BreakpointQueueEntry = {
+    autoResumed?: boolean;
+    hitAt?: string;
+    skipped?: boolean;
+} & BreakpointConfig;
+export interface BreakpointRenewal {
+    renewedAt: string;
+    renewedByUserId: string;
+}
+export type CurrentBreakpointState = {
+    createdAt: string;
+    expiresAt: string;
+    renewals?: BreakpointRenewal[];
+    resumedAt?: string;
+    resumedByUserId?: string;
+    skipped?: boolean;
+    wasAutoResumed?: boolean;
+} & BreakpointConfig;
+export interface BreakpointPauseLease {
+    createdAt: string;
+    createdByUserId: string;
+    defaultDurationMs: number;
+}
+export declare function isSameBreakpoint(a: BreakpointConfig | BreakpointQueueEntry | CurrentBreakpointState | undefined, b: BreakpointConfig | BreakpointQueueEntry | CurrentBreakpointState | undefined): boolean;
+export declare function cloneBreakpointQueue(queue?: null | ReadonlyArray<BreakpointQueueEntry>): BreakpointQueueEntry[];
+export declare function markQueueSkipped(queue: ReadonlyArray<BreakpointQueueEntry>, startIndex: number, options?: {
+    fallbackHitAt?: string;
+}): BreakpointQueueEntry[];
+export {};

package/lib/cjs/introspection/breakpoints.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BREAKPOINT_MAX_REMAINING_MS = exports.BREAKPOINT_RENEW_INCREMENT_MS = exports.BREAKPOINT_DEFAULT_LEASE_MS = void 0;
+exports.isSameBreakpoint = isSameBreakpoint;
+exports.cloneBreakpointQueue = cloneBreakpointQueue;
+exports.markQueueSkipped = markQueueSkipped;
+const MINUTE = 60 * 1000;
+exports.BREAKPOINT_DEFAULT_LEASE_MS = 20 * MINUTE; // 20 minutes
+exports.BREAKPOINT_RENEW_INCREMENT_MS = 10 * MINUTE; // 10 minutes
+exports.BREAKPOINT_MAX_REMAINING_MS = 20 * MINUTE; // 20 minutes
+function isSameBreakpoint(a, b) {
+    if (!a || !b) {
+        return false;
+    }
+    if (a.type !== b.type) {
+        return false;
+    }
+    if (a.id !== b.id) {
+        return false;
+    }
+    if (isHookBreakpointConfig(a) && isHookBreakpointConfig(b)) {
+        return a.position === b.position;
+    }
+    return true;
+}
+function isHookBreakpointConfig(config) {
+    return config.type === 'hook';
+}
+function cloneBreakpointQueue(queue) {
+    return Array.isArray(queue) ? queue.map((entry) => (Object.assign({}, entry))) : [];
+}
+function markQueueSkipped(queue, startIndex, options = {}) {
+    var _a;
+    const updated = cloneBreakpointQueue(queue);
+    const { fallbackHitAt } = options;
+    if (startIndex < 0 || startIndex >= updated.length) {
+        return updated;
+    }
+    const current = updated[startIndex];
+    const hitAt = (_a = current.hitAt) !== null && _a !== void 0 ? _a : fallbackHitAt;
+    updated[startIndex] = Object.assign(Object.assign(Object.assign({}, current), { skipped: true }), (hitAt ? { hitAt } : {}));
+    for (let i = startIndex + 1; i < updated.length; i += 1) {
+        if (!updated[i].hitAt) {
+            updated[i] = Object.assign(Object.assign({}, updated[i]), { skipped: true });
+        }
+    }
+    return updated;
+}

package/lib/esm/desktopify.d.ts

@@ -1,5 +1,6 @@
 import { Configuration, PackagerOptions, PublishOptions } from 'app-builder-lib';
 import { IApp2 } from './desktopify2';
+import { BreakpointPauseLease, BreakpointQueueEntry, CurrentBreakpointState } from './introspection/breakpoints';
 import { IApp } from './toDesktop';
 type appBuilderLib = PackagerOptions & PublishOptions;
 export interface IAppBuilderLib extends appBuilderLib {
@@ -92,6 +93,30 @@ export interface PlatformBuild {
     status: BuildStatus;
 }
 export type CIRunner = 'azure' | 'circle';
+export type IntrospectBreakpointStatus = 'error' | 'finished' | 'initializing' | 'paused' | 'ready' | 'resuming';
+export type IntrospectShellStatus = 'connected' | 'connecting' | 'disconnected' | 'error' | 'initializing' | 'ready';
+export interface IntrospectPlatformData {
+    breakpointQueue?: BreakpointQueueEntry[];
+    breakpointStatus: IntrospectBreakpointStatus;
+    connectedAt?: Date;
+    connectedUserId?: string;
+    createdAt: ISODate;
+    currentBreakpoint?: CurrentBreakpointState;
+    disconnectedAt?: Date;
+    enabled: boolean;
+    error?: string;
+    jtiExpiresAt?: Date;
+    pauseLease?: BreakpointPauseLease;
+    sessionJti?: string;
+    shellStatus: IntrospectShellStatus;
+    tunnelUrl?: string;
+    usedJti?: string;
+}
+export interface IntrospectData {
+    linux: IntrospectPlatformData;
+    mac: IntrospectPlatformData;
+    windows: IntrospectPlatformData;
+}
 export interface Build {
     appCustomDomain?: string;
     appName: string;
@@ -118,6 +143,7 @@ export interface Build {
     hash?: string;
     icon?: string;
     id: string;
+    introspect?: IntrospectData;
     isArtifactsPruned?: boolean;
     isBeingCancelled?: boolean;
     linux?: PlatformBuild;

package/lib/esm/index.d.ts

@@ -3,6 +3,7 @@ export * from './desktopify.js';
 export * from './desktopify2.js';
 export * from './getSiteInfo.js';
 export * from './hsm.js';
+export * from './introspection/breakpoints.js';
 export * from './invitePermissionLabels.js';
 export * from './personalAccessTokens.js';
 export * from './plans.js';

package/lib/esm/index.js

@@ -5,6 +5,7 @@ export * from './desktopify.js';
 export * from './desktopify2.js';
 export * from './getSiteInfo.js';
 export * from './hsm.js';
+export * from './introspection/breakpoints.js';
 export * from './invitePermissionLabels.js';
 export * from './personalAccessTokens.js';
 export * from './plans.js';

package/lib/esm/introspection/__tests__/breakpoints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/esm/introspection/__tests__/breakpoints.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { cloneBreakpointQueue, isSameBreakpoint, markQueueSkipped, } from '../breakpoints';
+describe('isSameBreakpoint', () => {
+    it('matches identical phase breakpoints', () => {
+        expect(isSameBreakpoint({ id: 'beforeInstall', type: 'phase' }, { id: 'beforeInstall', type: 'phase' })).toBe(true);
+    });
+    it('fails when breakpoint types differ', () => {
+        expect(isSameBreakpoint({ id: 'beforeInstall', type: 'phase' }, { id: 'todesktop:beforeInstall', position: 'before', type: 'hook' })).toBe(false);
+    });
+    it('considers hook positions', () => {
+        expect(isSameBreakpoint({ id: 'todesktop:beforeBuild', position: 'before', type: 'hook' }, { id: 'todesktop:beforeBuild', position: 'after', type: 'hook' })).toBe(false);
+    });
+    it('returns false when either side is undefined', () => {
+        expect(isSameBreakpoint(undefined, { id: 'afterInstall', type: 'phase' })).toBe(false);
+    });
+});
+describe('cloneBreakpointQueue', () => {
+    it('produces a deep copy of the queue', () => {
+        const original = [
+            { hitAt: undefined, id: 'beforeInstall', type: 'phase' },
+            {
+                id: 'todesktop:afterPack',
+                position: 'after',
+                skipped: true,
+                type: 'hook',
+            },
+        ];
+        const copy = cloneBreakpointQueue(original);
+        expect(copy).toEqual(original);
+        expect(copy).not.toBe(original);
+        expect(copy[0]).not.toBe(original[0]);
+    });
+});
+describe('markQueueSkipped', () => {
+    it('marks the starting entry as skipped and adds fallback timestamps', () => {
+        const queue = [
+            { id: 'beforeInstall', type: 'phase' },
+            { id: 'afterInstall', type: 'phase' },
+        ];
+        const fallbackHitAt = '2024-01-01T00:00:00.000Z';
+        const updated = markQueueSkipped(queue, 0, { fallbackHitAt });
+        expect(updated[0]).toMatchObject({
+            hitAt: fallbackHitAt,
+            skipped: true,
+        });
+        expect(updated[1]).toMatchObject({ skipped: true });
+        expect(queue[0].skipped).toBeUndefined();
+    });
+    it('returns a cloned queue when index is out of bounds', () => {
+        const queue = [
+            { id: 'beforeInstall', type: 'phase' },
+        ];
+        const updated = markQueueSkipped(queue, 2);
+        expect(updated).toEqual(queue);
+        expect(updated).not.toBe(queue);
+    });
+});

package/lib/esm/introspection/breakpoints.d.ts

@@ -0,0 +1,45 @@
+export declare const BREAKPOINT_DEFAULT_LEASE_MS: number;
+export declare const BREAKPOINT_RENEW_INCREMENT_MS: number;
+export declare const BREAKPOINT_MAX_REMAINING_MS: number;
+export type PhaseBreakpointId = 'afterInstall' | 'afterPack' | 'afterSourcePrep' | 'afterUpload' | 'beforeFinalize' | 'beforeInstall' | 'beforePack' | 'beforeUpload';
+export type HookBreakpointName = 'todesktop:afterPack' | 'todesktop:beforeBuild' | 'todesktop:beforeInstall';
+export type HookBreakpointPosition = 'after' | 'before';
+interface PhaseBreakpointConfig {
+    id: PhaseBreakpointId;
+    type: 'phase';
+}
+interface HookBreakpointConfig {
+    id: HookBreakpointName;
+    position: HookBreakpointPosition;
+    type: 'hook';
+}
+export type BreakpointConfig = HookBreakpointConfig | PhaseBreakpointConfig;
+export type BreakpointQueueEntry = {
+    autoResumed?: boolean;
+    hitAt?: string;
+    skipped?: boolean;
+} & BreakpointConfig;
+export interface BreakpointRenewal {
+    renewedAt: string;
+    renewedByUserId: string;
+}
+export type CurrentBreakpointState = {
+    createdAt: string;
+    expiresAt: string;
+    renewals?: BreakpointRenewal[];
+    resumedAt?: string;
+    resumedByUserId?: string;
+    skipped?: boolean;
+    wasAutoResumed?: boolean;
+} & BreakpointConfig;
+export interface BreakpointPauseLease {
+    createdAt: string;
+    createdByUserId: string;
+    defaultDurationMs: number;
+}
+export declare function isSameBreakpoint(a: BreakpointConfig | BreakpointQueueEntry | CurrentBreakpointState | undefined, b: BreakpointConfig | BreakpointQueueEntry | CurrentBreakpointState | undefined): boolean;
+export declare function cloneBreakpointQueue(queue?: null | ReadonlyArray<BreakpointQueueEntry>): BreakpointQueueEntry[];
+export declare function markQueueSkipped(queue: ReadonlyArray<BreakpointQueueEntry>, startIndex: number, options?: {
+    fallbackHitAt?: string;
+}): BreakpointQueueEntry[];
+export {};

package/lib/esm/introspection/breakpoints.js

@@ -0,0 +1,42 @@
+const MINUTE = 60 * 1000;
+export const BREAKPOINT_DEFAULT_LEASE_MS = 20 * MINUTE; // 20 minutes
+export const BREAKPOINT_RENEW_INCREMENT_MS = 10 * MINUTE; // 10 minutes
+export const BREAKPOINT_MAX_REMAINING_MS = 20 * MINUTE; // 20 minutes
+export function isSameBreakpoint(a, b) {
+    if (!a || !b) {
+        return false;
+    }
+    if (a.type !== b.type) {
+        return false;
+    }
+    if (a.id !== b.id) {
+        return false;
+    }
+    if (isHookBreakpointConfig(a) && isHookBreakpointConfig(b)) {
+        return a.position === b.position;
+    }
+    return true;
+}
+function isHookBreakpointConfig(config) {
+    return config.type === 'hook';
+}
+export function cloneBreakpointQueue(queue) {
+    return Array.isArray(queue) ? queue.map((entry) => (Object.assign({}, entry))) : [];
+}
+export function markQueueSkipped(queue, startIndex, options = {}) {
+    var _a;
+    const updated = cloneBreakpointQueue(queue);
+    const { fallbackHitAt } = options;
+    if (startIndex < 0 || startIndex >= updated.length) {
+        return updated;
+    }
+    const current = updated[startIndex];
+    const hitAt = (_a = current.hitAt) !== null && _a !== void 0 ? _a : fallbackHitAt;
+    updated[startIndex] = Object.assign(Object.assign(Object.assign({}, current), { skipped: true }), (hitAt ? { hitAt } : {}));
+    for (let i = startIndex + 1; i < updated.length; i += 1) {
+        if (!updated[i].hitAt) {
+            updated[i] = Object.assign(Object.assign({}, updated[i]), { skipped: true });
+        }
+    }
+    return updated;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@todesktop/shared",
-  "version": "7.191.1",
+  "version": "7.192.0",
   "description": "",
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
@@ -27,6 +27,7 @@
     "format": "prettier . --write && eslint --fix",
     "lint": "prettier . --check && eslint",
     "prepublishOnly": "npm run build",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "author": "Dave Jeffery <dave@davejeffery.com>",
@@ -45,6 +46,7 @@
     "app-builder-lib": "^25.1.8",
     "eslint": "catalog:",
     "prettier": "catalog:",
-    "typescript": "catalog:"
+    "typescript": "catalog:",
+    "vitest": "^1.6.1"
   }
 }

package/src/desktopify.ts

@@ -3,12 +3,13 @@ import {
   Configuration,
   PackagerOptions,
   PublishOptions,
-  // app-builder-lib shouldn't be installed as a dependency for dependent
-  // packages since it's too large
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-ignore
 } from 'app-builder-lib';
 import { IApp2 } from './desktopify2';
+import {
+  BreakpointPauseLease,
+  BreakpointQueueEntry,
+  CurrentBreakpointState,
+} from './introspection/breakpoints';
 import { IApp } from './toDesktop';
 
 type appBuilderLib = PackagerOptions & PublishOptions;
@@ -130,6 +131,46 @@ export interface PlatformBuild {
 
 export type CIRunner = 'azure' | 'circle';
 
+export type IntrospectBreakpointStatus =
+  | 'error'
+  | 'finished'
+  | 'initializing'
+  | 'paused'
+  | 'ready'
+  | 'resuming';
+
+export type IntrospectShellStatus =
+  | 'connected'
+  | 'connecting'
+  | 'disconnected'
+  | 'error'
+  | 'initializing'
+  | 'ready';
+
+export interface IntrospectPlatformData {
+  breakpointQueue?: BreakpointQueueEntry[];
+  breakpointStatus: IntrospectBreakpointStatus;
+  connectedAt?: Date;
+  connectedUserId?: string;
+  createdAt: ISODate;
+  currentBreakpoint?: CurrentBreakpointState;
+  disconnectedAt?: Date;
+  enabled: boolean;
+  error?: string;
+  jtiExpiresAt?: Date;
+  pauseLease?: BreakpointPauseLease;
+  sessionJti?: string;
+  shellStatus: IntrospectShellStatus;
+  tunnelUrl?: string;
+  usedJti?: string;
+}
+
+export interface IntrospectData {
+  linux: IntrospectPlatformData;
+  mac: IntrospectPlatformData;
+  windows: IntrospectPlatformData;
+}
+
 export interface Build {
   appCustomDomain?: string;
   appName: string;
@@ -161,6 +202,7 @@ export interface Build {
   hash?: string;
   icon?: string;
   id: string;
+  introspect?: IntrospectData;
   isArtifactsPruned?: boolean;
   isBeingCancelled?: boolean;
   linux?: PlatformBuild;

package/src/index.cjs.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports */
+/* eslint-disable @typescript-eslint/no-require-imports */
 // CJS-specific entry point
 // Path is relative to lib/cjs/ output directory
 const packageJson = require('../../package.json');

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './desktopify.js';
 export * from './desktopify2.js';
 export * from './getSiteInfo.js';
 export * from './hsm.js';
+export * from './introspection/breakpoints.js';
 export * from './invitePermissionLabels.js';
 export * from './personalAccessTokens.js';
 export * from './plans.js';

package/src/introspection/__tests__/breakpoints.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import {
+  cloneBreakpointQueue,
+  isSameBreakpoint,
+  markQueueSkipped,
+} from '../breakpoints';
+import type { BreakpointQueueEntry } from '../breakpoints';
+
+describe('isSameBreakpoint', () => {
+  it('matches identical phase breakpoints', () => {
+    expect(
+      isSameBreakpoint(
+        { id: 'beforeInstall', type: 'phase' },
+        { id: 'beforeInstall', type: 'phase' },
+      ),
+    ).toBe(true);
+  });
+
+  it('fails when breakpoint types differ', () => {
+    expect(
+      isSameBreakpoint(
+        { id: 'beforeInstall', type: 'phase' },
+        { id: 'todesktop:beforeInstall', position: 'before', type: 'hook' },
+      ),
+    ).toBe(false);
+  });
+
+  it('considers hook positions', () => {
+    expect(
+      isSameBreakpoint(
+        { id: 'todesktop:beforeBuild', position: 'before', type: 'hook' },
+        { id: 'todesktop:beforeBuild', position: 'after', type: 'hook' },
+      ),
+    ).toBe(false);
+  });
+
+  it('returns false when either side is undefined', () => {
+    expect(
+      isSameBreakpoint(undefined, { id: 'afterInstall', type: 'phase' }),
+    ).toBe(false);
+  });
+});
+
+describe('cloneBreakpointQueue', () => {
+  it('produces a deep copy of the queue', () => {
+    const original: ReadonlyArray<BreakpointQueueEntry> = [
+      { hitAt: undefined, id: 'beforeInstall', type: 'phase' },
+      {
+        id: 'todesktop:afterPack',
+        position: 'after',
+        skipped: true,
+        type: 'hook',
+      },
+    ];
+
+    const copy = cloneBreakpointQueue(original);
+
+    expect(copy).toEqual(original);
+    expect(copy).not.toBe(original);
+    expect(copy[0]).not.toBe(original[0]);
+  });
+});
+
+describe('markQueueSkipped', () => {
+  it('marks the starting entry as skipped and adds fallback timestamps', () => {
+    const queue: ReadonlyArray<BreakpointQueueEntry> = [
+      { id: 'beforeInstall', type: 'phase' },
+      { id: 'afterInstall', type: 'phase' },
+    ];
+    const fallbackHitAt = '2024-01-01T00:00:00.000Z';
+
+    const updated = markQueueSkipped(queue, 0, { fallbackHitAt });
+
+    expect(updated[0]).toMatchObject({
+      hitAt: fallbackHitAt,
+      skipped: true,
+    });
+    expect(updated[1]).toMatchObject({ skipped: true });
+    expect(queue[0].skipped).toBeUndefined();
+  });
+
+  it('returns a cloned queue when index is out of bounds', () => {
+    const queue: ReadonlyArray<BreakpointQueueEntry> = [
+      { id: 'beforeInstall', type: 'phase' },
+    ];
+
+    const updated = markQueueSkipped(queue, 2);
+
+    expect(updated).toEqual(queue);
+    expect(updated).not.toBe(queue);
+  });
+});

package/src/introspection/breakpoints.ts

@@ -0,0 +1,137 @@
+const MINUTE = 60 * 1000;
+export const BREAKPOINT_DEFAULT_LEASE_MS = 20 * MINUTE; // 20 minutes
+export const BREAKPOINT_RENEW_INCREMENT_MS = 10 * MINUTE; // 10 minutes
+export const BREAKPOINT_MAX_REMAINING_MS = 20 * MINUTE; // 20 minutes
+
+export type PhaseBreakpointId =
+  | 'afterInstall'
+  | 'afterPack'
+  | 'afterSourcePrep'
+  | 'afterUpload'
+  | 'beforeFinalize'
+  | 'beforeInstall'
+  | 'beforePack'
+  | 'beforeUpload';
+
+export type HookBreakpointName =
+  | 'todesktop:afterPack'
+  | 'todesktop:beforeBuild'
+  | 'todesktop:beforeInstall';
+
+export type HookBreakpointPosition = 'after' | 'before';
+
+interface PhaseBreakpointConfig {
+  id: PhaseBreakpointId;
+  type: 'phase';
+}
+
+interface HookBreakpointConfig {
+  id: HookBreakpointName;
+  position: HookBreakpointPosition;
+  type: 'hook';
+}
+
+export type BreakpointConfig = HookBreakpointConfig | PhaseBreakpointConfig;
+
+export type BreakpointQueueEntry = {
+  autoResumed?: boolean;
+  hitAt?: string;
+  skipped?: boolean;
+} & BreakpointConfig;
+
+export interface BreakpointRenewal {
+  renewedAt: string;
+  renewedByUserId: string;
+}
+
+export type CurrentBreakpointState = {
+  createdAt: string;
+  expiresAt: string;
+  renewals?: BreakpointRenewal[];
+  resumedAt?: string;
+  resumedByUserId?: string;
+  skipped?: boolean;
+  wasAutoResumed?: boolean;
+} & BreakpointConfig;
+
+export interface BreakpointPauseLease {
+  createdAt: string;
+  createdByUserId: string;
+  defaultDurationMs: number;
+}
+
+export function isSameBreakpoint(
+  a:
+    | BreakpointConfig
+    | BreakpointQueueEntry
+    | CurrentBreakpointState
+    | undefined,
+  b:
+    | BreakpointConfig
+    | BreakpointQueueEntry
+    | CurrentBreakpointState
+    | undefined,
+): boolean {
+  if (!a || !b) {
+    return false;
+  }
+
+  if (a.type !== b.type) {
+    return false;
+  }
+
+  if (a.id !== b.id) {
+    return false;
+  }
+
+  if (isHookBreakpointConfig(a) && isHookBreakpointConfig(b)) {
+    return a.position === b.position;
+  }
+
+  return true;
+}
+
+function isHookBreakpointConfig(
+  config: BreakpointConfig | BreakpointQueueEntry | CurrentBreakpointState,
+): config is HookBreakpointConfig {
+  return config.type === 'hook';
+}
+
+export function cloneBreakpointQueue(
+  queue?: null | ReadonlyArray<BreakpointQueueEntry>,
+): BreakpointQueueEntry[] {
+  return Array.isArray(queue) ? queue.map((entry) => ({ ...entry })) : [];
+}
+
+export function markQueueSkipped(
+  queue: ReadonlyArray<BreakpointQueueEntry>,
+  startIndex: number,
+  options: { fallbackHitAt?: string } = {},
+): BreakpointQueueEntry[] {
+  const updated = cloneBreakpointQueue(queue);
+  const { fallbackHitAt } = options;
+
+  if (startIndex < 0 || startIndex >= updated.length) {
+    return updated;
+  }
+
+  const current = updated[startIndex];
+  const hitAt = current.hitAt ?? fallbackHitAt;
+
+  updated[startIndex] = {
+    ...current,
+    skipped: true,
+    ...(hitAt ? { hitAt } : {}),
+  };
+
+  for (let i = startIndex + 1; i < updated.length; i += 1) {
+    if (!updated[i].hitAt) {
+      updated[i] = {
+        ...updated[i],
+        skipped: true,
+      };
+    }
+  }
+
+  return updated;
+}