@todesktop/shared 7.191.1 → 7.193.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.d.ts

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

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');
@@ -24,6 +24,8 @@ __exportStar(require("./desktopify"), exports);
 __exportStar(require("./desktopify2"), exports);
 __exportStar(require("./getSiteInfo"), exports);
 __exportStar(require("./hsm"), exports);
+__exportStar(require("./introspection/breakpoints"), exports);
+__exportStar(require("./introspection/status"), exports);
 __exportStar(require("./invitePermissionLabels"), exports);
 __exportStar(require("./personalAccessTokens"), exports);
 __exportStar(require("./plans"), exports);

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/cjs/introspection/status.d.ts

@@ -0,0 +1,18 @@
+import type { Build } from '../desktopify';
+import type { IntrospectBreakpointStatus, IntrospectShellStatus } from '../desktopify';
+export type IntrospectPlatformName = 'mac' | 'windows' | 'linux';
+/**
+ * Check if a build was introspected (has connectedAt or disconnectedAt on any platform).
+ * Builds that were introspected cannot be released.
+ */
+export declare function wasIntrospected(build: Build): boolean;
+/**
+ * Get list of platform names that were introspected (have connectedAt or disconnectedAt).
+ * Returns capitalized platform names (e.g., ['Mac', 'Windows']).
+ */
+export declare function getIntrospectedPlatformNames(build: Build): string[];
+/**
+ * Format introspection status as a human-readable string.
+ * Combines breakpoint status and shell status into a single label.
+ */
+export declare function formatIntrospectionStatus(breakpointStatus?: IntrospectBreakpointStatus, shellStatus?: IntrospectShellStatus): string;

package/lib/cjs/introspection/status.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wasIntrospected = wasIntrospected;
+exports.getIntrospectedPlatformNames = getIntrospectedPlatformNames;
+exports.formatIntrospectionStatus = formatIntrospectionStatus;
+const PLATFORM_LABELS = {
+    mac: 'Mac',
+    windows: 'Windows',
+    linux: 'Linux',
+};
+/**
+ * Check if a build was introspected (has connectedAt or disconnectedAt on any platform).
+ * Builds that were introspected cannot be released.
+ */
+function wasIntrospected(build) {
+    const introspect = build.introspect;
+    if (!introspect)
+        return false;
+    const platforms = ['mac', 'windows', 'linux'];
+    for (const platform of platforms) {
+        const data = introspect[platform];
+        if ((data === null || data === void 0 ? void 0 : data.connectedAt) || (data === null || data === void 0 ? void 0 : data.disconnectedAt)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get list of platform names that were introspected (have connectedAt or disconnectedAt).
+ * Returns capitalized platform names (e.g., ['Mac', 'Windows']).
+ */
+function getIntrospectedPlatformNames(build) {
+    const introspect = build.introspect;
+    if (!introspect)
+        return [];
+    const platforms = ['mac', 'windows', 'linux'];
+    const result = [];
+    for (const platform of platforms) {
+        const data = introspect[platform];
+        if ((data === null || data === void 0 ? void 0 : data.connectedAt) || (data === null || data === void 0 ? void 0 : data.disconnectedAt)) {
+            result.push(PLATFORM_LABELS[platform]);
+        }
+    }
+    return result;
+}
+/**
+ * Format introspection status as a human-readable string.
+ * Combines breakpoint status and shell status into a single label.
+ */
+function formatIntrospectionStatus(breakpointStatus, shellStatus) {
+    if (breakpointStatus === 'paused') {
+        if (shellStatus === 'connected') {
+            return 'paused (shell connected)';
+        }
+        if (shellStatus === 'disconnected') {
+            return 'paused (shell disconnected)';
+        }
+        return 'paused';
+    }
+    if (breakpointStatus === 'ready') {
+        if (shellStatus === 'connected') {
+            return 'ready (shell connected)';
+        }
+        if (shellStatus === 'disconnected') {
+            return 'ready (shell disconnected)';
+        }
+        return 'ready';
+    }
+    if (breakpointStatus === 'resuming') {
+        return 'resuming';
+    }
+    if (breakpointStatus === 'initializing') {
+        return 'initializing';
+    }
+    if (breakpointStatus === 'finished') {
+        return 'finished';
+    }
+    if (breakpointStatus === 'error' || shellStatus === 'error') {
+        return 'error';
+    }
+    return 'status unknown';
+}

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,8 @@ export * from './desktopify.js';
 export * from './desktopify2.js';
 export * from './getSiteInfo.js';
 export * from './hsm.js';
+export * from './introspection/breakpoints.js';
+export * from './introspection/status.js';
 export * from './invitePermissionLabels.js';
 export * from './personalAccessTokens.js';
 export * from './plans.js';

package/lib/esm/index.js

@@ -5,6 +5,8 @@ export * from './desktopify.js';
 export * from './desktopify2.js';
 export * from './getSiteInfo.js';
 export * from './hsm.js';
+export * from './introspection/breakpoints.js';
+export * from './introspection/status.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/lib/esm/introspection/status.d.ts

@@ -0,0 +1,18 @@
+import type { Build } from '../desktopify';
+import type { IntrospectBreakpointStatus, IntrospectShellStatus } from '../desktopify';
+export type IntrospectPlatformName = 'mac' | 'windows' | 'linux';
+/**
+ * Check if a build was introspected (has connectedAt or disconnectedAt on any platform).
+ * Builds that were introspected cannot be released.
+ */
+export declare function wasIntrospected(build: Build): boolean;
+/**
+ * Get list of platform names that were introspected (have connectedAt or disconnectedAt).
+ * Returns capitalized platform names (e.g., ['Mac', 'Windows']).
+ */
+export declare function getIntrospectedPlatformNames(build: Build): string[];
+/**
+ * Format introspection status as a human-readable string.
+ * Combines breakpoint status and shell status into a single label.
+ */
+export declare function formatIntrospectionStatus(breakpointStatus?: IntrospectBreakpointStatus, shellStatus?: IntrospectShellStatus): string;

package/lib/esm/introspection/status.js

@@ -0,0 +1,77 @@
+const PLATFORM_LABELS = {
+    mac: 'Mac',
+    windows: 'Windows',
+    linux: 'Linux',
+};
+/**
+ * Check if a build was introspected (has connectedAt or disconnectedAt on any platform).
+ * Builds that were introspected cannot be released.
+ */
+export function wasIntrospected(build) {
+    const introspect = build.introspect;
+    if (!introspect)
+        return false;
+    const platforms = ['mac', 'windows', 'linux'];
+    for (const platform of platforms) {
+        const data = introspect[platform];
+        if ((data === null || data === void 0 ? void 0 : data.connectedAt) || (data === null || data === void 0 ? void 0 : data.disconnectedAt)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get list of platform names that were introspected (have connectedAt or disconnectedAt).
+ * Returns capitalized platform names (e.g., ['Mac', 'Windows']).
+ */
+export function getIntrospectedPlatformNames(build) {
+    const introspect = build.introspect;
+    if (!introspect)
+        return [];
+    const platforms = ['mac', 'windows', 'linux'];
+    const result = [];
+    for (const platform of platforms) {
+        const data = introspect[platform];
+        if ((data === null || data === void 0 ? void 0 : data.connectedAt) || (data === null || data === void 0 ? void 0 : data.disconnectedAt)) {
+            result.push(PLATFORM_LABELS[platform]);
+        }
+    }
+    return result;
+}
+/**
+ * Format introspection status as a human-readable string.
+ * Combines breakpoint status and shell status into a single label.
+ */
+export function formatIntrospectionStatus(breakpointStatus, shellStatus) {
+    if (breakpointStatus === 'paused') {
+        if (shellStatus === 'connected') {
+            return 'paused (shell connected)';
+        }
+        if (shellStatus === 'disconnected') {
+            return 'paused (shell disconnected)';
+        }
+        return 'paused';
+    }
+    if (breakpointStatus === 'ready') {
+        if (shellStatus === 'connected') {
+            return 'ready (shell connected)';
+        }
+        if (shellStatus === 'disconnected') {
+            return 'ready (shell disconnected)';
+        }
+        return 'ready';
+    }
+    if (breakpointStatus === 'resuming') {
+        return 'resuming';
+    }
+    if (breakpointStatus === 'initializing') {
+        return 'initializing';
+    }
+    if (breakpointStatus === 'finished') {
+        return 'finished';
+    }
+    if (breakpointStatus === 'error' || shellStatus === 'error') {
+        return 'error';
+    }
+    return 'status unknown';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@todesktop/shared",
-  "version": "7.191.1",
+  "version": "7.193.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');
@@ -8,6 +8,8 @@ export * from './desktopify';
 export * from './desktopify2';
 export * from './getSiteInfo';
 export * from './hsm';
+export * from './introspection/breakpoints';
+export * from './introspection/status';
 export * from './invitePermissionLabels';
 export * from './personalAccessTokens';
 export * from './plans';

package/src/index.ts

@@ -6,6 +6,8 @@ export * from './desktopify.js';
 export * from './desktopify2.js';
 export * from './getSiteInfo.js';
 export * from './hsm.js';
+export * from './introspection/breakpoints.js';
+export * from './introspection/status.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;
+}

package/src/introspection/status.ts

@@ -0,0 +1,101 @@
+import type { Build } from '../desktopify';
+import type {
+  IntrospectBreakpointStatus,
+  IntrospectShellStatus,
+} from '../desktopify';
+
+export type IntrospectPlatformName = 'mac' | 'windows' | 'linux';
+
+const PLATFORM_LABELS: Record<IntrospectPlatformName, string> = {
+  mac: 'Mac',
+  windows: 'Windows',
+  linux: 'Linux',
+};
+
+/**
+ * Check if a build was introspected (has connectedAt or disconnectedAt on any platform).
+ * Builds that were introspected cannot be released.
+ */
+export function wasIntrospected(build: Build): boolean {
+  const introspect = build.introspect;
+  if (!introspect) return false;
+
+  const platforms: IntrospectPlatformName[] = ['mac', 'windows', 'linux'];
+
+  for (const platform of platforms) {
+    const data = introspect[platform];
+    if (data?.connectedAt || data?.disconnectedAt) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get list of platform names that were introspected (have connectedAt or disconnectedAt).
+ * Returns capitalized platform names (e.g., ['Mac', 'Windows']).
+ */
+export function getIntrospectedPlatformNames(build: Build): string[] {
+  const introspect = build.introspect;
+  if (!introspect) return [];
+
+  const platforms: IntrospectPlatformName[] = ['mac', 'windows', 'linux'];
+  const result: string[] = [];
+
+  for (const platform of platforms) {
+    const data = introspect[platform];
+    if (data?.connectedAt || data?.disconnectedAt) {
+      result.push(PLATFORM_LABELS[platform]);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format introspection status as a human-readable string.
+ * Combines breakpoint status and shell status into a single label.
+ */
+export function formatIntrospectionStatus(
+  breakpointStatus?: IntrospectBreakpointStatus,
+  shellStatus?: IntrospectShellStatus,
+): string {
+  if (breakpointStatus === 'paused') {
+    if (shellStatus === 'connected') {
+      return 'paused (shell connected)';
+    }
+    if (shellStatus === 'disconnected') {
+      return 'paused (shell disconnected)';
+    }
+    return 'paused';
+  }
+
+  if (breakpointStatus === 'ready') {
+    if (shellStatus === 'connected') {
+      return 'ready (shell connected)';
+    }
+    if (shellStatus === 'disconnected') {
+      return 'ready (shell disconnected)';
+    }
+    return 'ready';
+  }
+
+  if (breakpointStatus === 'resuming') {
+    return 'resuming';
+  }
+
+  if (breakpointStatus === 'initializing') {
+    return 'initializing';
+  }
+
+  if (breakpointStatus === 'finished') {
+    return 'finished';
+  }
+
+  if (breakpointStatus === 'error' || shellStatus === 'error') {
+    return 'error';
+  }
+
+  return 'status unknown';
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+// eslint-disable-next-line import-x/no-extraneous-dependencies
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    exclude: ['lib/**', 'node_modules/**'],
+    include: ['src/**/*.test.ts'],
+  },
+});