@camstack/server 0.1.6 → 0.1.7

package/src/__tests__/cap-routers/cap-route-error-formatter.spec.ts

@@ -0,0 +1,123 @@
+/**
+ * Unit tests for the cap-route-error-formatter.
+ *
+ * `formatTrpcError` is a pure function — no tRPC plumbing required.
+ * We hand-craft minimal TRPCError-like / DefaultErrorShape-like objects
+ * to verify the augmentation logic.
+ */
+import { describe, it, expect } from 'vitest'
+import { TRPCError } from '@trpc/server'
+import { CapRouteError } from '@camstack/kernel'
+import { formatTrpcError } from '../../api/trpc/cap-route-error-formatter.js'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Minimal DefaultErrorShape stub. */
+function makeShape(overrides: Partial<{ message: string }> = {}): Parameters<typeof formatTrpcError>[0]['shape'] {
+  return {
+    message: overrides.message ?? 'Something went wrong',
+    code: -32603, // INTERNAL_SERVER_ERROR code number
+    data: {
+      code: 'INTERNAL_SERVER_ERROR',
+      httpStatus: 500,
+    },
+  }
+}
+
+/** Build a TRPCError-like object that formatTrpcError accepts. */
+function makeTrpcError(
+  message: string,
+  cause?: Error,
+): Parameters<typeof formatTrpcError>[0]['error'] {
+  return new TRPCError({
+    code: 'PRECONDITION_FAILED',
+    message,
+    cause,
+  })
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('formatTrpcError', () => {
+  it('returns shape unchanged when error is not a CapRouteError', () => {
+    const shape = makeShape({ message: 'Boom' })
+    const error = makeTrpcError('Some generic error')
+    const result = formatTrpcError({ error, shape })
+    expect(result).toStrictEqual(shape)
+    expect(result.data).not.toHaveProperty('capRouteReason')
+  })
+
+  it('augments shape with capRouteReason when error.cause is a CapRouteError', () => {
+    const capRouteErr = new CapRouteError('my-cap', undefined, {
+      reason: 'no-provider',
+      rejected: [{ kind: 'hub-in-process', why: 'no provider bound' }],
+    })
+    const shape = makeShape()
+    const error = makeTrpcError('Capability "my-cap" provider not available', capRouteErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('no-provider')
+    expect(result.data.capRouteRejected).toStrictEqual([
+      { kind: 'hub-in-process', why: 'no provider bound' },
+    ])
+    expect(result.data.capRouteNodeId).toBeUndefined()
+    // Original shape fields preserved
+    expect(result.message).toBe(shape.message)
+    expect(result.code).toBe(shape.code)
+  })
+
+  it('augments shape with capRouteReason when error itself is a CapRouteError', () => {
+    const capRouteErr = new CapRouteError('some-cap', undefined, {
+      reason: 'node-offline',
+      nodeId: 'node-abc',
+      rejected: [{ kind: 'remote-moleculer', why: 'node node-abc is offline' }],
+    })
+    const shape = makeShape()
+    // Wrap as TRPCError with the CapRouteError AS the cause
+    const error = makeTrpcError('Transport failed', capRouteErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('node-offline')
+    expect(result.data.capRouteNodeId).toBe('node-abc')
+    expect(result.data.capRouteRejected).toHaveLength(1)
+  })
+
+  it('surfaces transport-failed reason correctly (not absent provider)', () => {
+    const capRouteErr = new CapRouteError('stream-params', 'getStatus', {
+      reason: 'transport-failed',
+      rejected: [{ kind: 'hub-local-uds', why: 'socket closed' }],
+    })
+    const shape = makeShape()
+    const error = makeTrpcError('Transport failed', capRouteErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('transport-failed')
+    expect(result.data.capRouteRejected).toStrictEqual([
+      { kind: 'hub-local-uds', why: 'socket closed' },
+    ])
+  })
+
+  it('walks a nested cause chain to find a CapRouteError', () => {
+    const capRouteErr = new CapRouteError('ptz', undefined, {
+      reason: 'cap-unknown',
+      rejected: [],
+    })
+    // Wrap two levels deep
+    const innerError = new Error('dispatch failed', { cause: capRouteErr })
+    const shape = makeShape()
+    const error = makeTrpcError('Outer error', innerError)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('cap-unknown')
+  })
+
+  it('returns shape unchanged for a plain Error (non-CapRouteError cause)', () => {
+    const plainErr = new Error('plain cause')
+    const shape = makeShape()
+    const error = makeTrpcError('Wrapper', plainErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data).not.toHaveProperty('capRouteReason')
+    expect(result).toStrictEqual(shape)
+  })
+})

package/src/__tests__/cap-routers/capabilities-node.spec.ts

@@ -0,0 +1,55 @@
+/**
+ * Spec for the per-node singleton extension in capabilities.router.
+ *
+ * Exercises:
+ *  - setActiveSingleton with nodeId → calls registry with (cap, addonId, nodeId)
+ *    + persists `capabilities.singletonNode.<cap>.<nodeId>`
+ *  - setActiveSingleton without nodeId → persists `capabilities.singleton.<cap>` (global key)
+ *  - clearSingletonNodeOverride → calls registry.clearSingletonNodeOverride(cap, nodeId)
+ *    + persists the per-node key as null
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import type { ConfigService } from '../../core/config/config.service.js'
+import { createCapabilitiesRouter } from '../../api/core/capabilities.router.js'
+import { makeCtx } from './harness.js'
+
+function harness() {
+  const calls: { setActiveSingleton: unknown[][]; clear: unknown[][] } = { setActiveSingleton: [], clear: [] }
+  const sets: Record<string, unknown> = {}
+  const registry = {
+    setActiveSingleton: vi.fn(async (...a: unknown[]) => { calls.setActiveSingleton.push(a) }),
+    clearSingletonNodeOverride: vi.fn((...a: unknown[]) => { calls.clear.push(a) }),
+    listCapabilities: () => [],
+  } as unknown as CapabilityRegistry
+  const config = { set: (k: string, v: unknown) => { sets[k] = v } } as unknown as ConfigService
+  const router = createCapabilitiesRouter(registry, config)
+  return { router, calls, sets, registry }
+}
+
+describe('capabilities.router — per-node singleton', () => {
+  it('setActiveSingleton with nodeId persists the per-node key', async () => {
+    const { router, calls, sets } = harness()
+    const caller = router.createCaller(makeCtx('admin'))
+    await caller.setActiveSingleton({
+      capability: 'webrtc-session', addonId: 'webrtc-native', nodeId: 'dev-agent-0',
+    })
+    expect(calls.setActiveSingleton[0]).toEqual(['webrtc-session', 'webrtc-native', 'dev-agent-0'])
+    expect(sets['capabilities.singletonNode.webrtc-session.dev-agent-0']).toBe('webrtc-native')
+  })
+
+  it('setActiveSingleton without nodeId persists the global key', async () => {
+    const { router, sets } = harness()
+    const caller = router.createCaller(makeCtx('admin'))
+    await caller.setActiveSingleton({ capability: 'webrtc-session', addonId: 'stream-broker' })
+    expect(sets['capabilities.singleton.webrtc-session']).toBe('stream-broker')
+  })
+
+  it('clearSingletonNodeOverride clears the per-node key', async () => {
+    const { router, calls, sets } = harness()
+    const caller = router.createCaller(makeCtx('admin'))
+    await caller.clearSingletonNodeOverride({ capability: 'webrtc-session', nodeId: 'dev-agent-0' })
+    expect(calls.clear[0]).toEqual(['webrtc-session', 'dev-agent-0'])
+    expect(sets['capabilities.singletonNode.webrtc-session.dev-agent-0']).toBe(null)
+  })
+})

package/src/__tests__/dev-bootstrap-shm-ring.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+describe('dev bootstrap — shm-ring prebuild availability', () => {
+  it('has at least one .node prebuild for the current platform-arch', () => {
+    const platform = process.platform
+    const arch = process.arch
+    const triple = `${platform}-${arch}`
+    const prebuildsDir = join(__dirname, '..', '..', '..', '..', 'packages', 'shm-ring', 'prebuilds', triple)
+    expect(existsSync(prebuildsDir)).toBe(true)
+    const files = readdirSync(prebuildsDir)
+    const nodeBinaries = files.filter(f => f.endsWith('.node'))
+    expect(nodeBinaries.length).toBeGreaterThan(0)
+  })
+
+  it('@camstack/shm-ring resolves and loads (smoke test)', () => {
+    // If this require() throws "No native build was found...", the
+    // dev bootstrap is broken — the regression Bug-2 is back.
+    let mod: unknown
+    expect(() => {
+      mod = require('@camstack/shm-ring')
+    }).not.toThrow()
+    expect(mod).toBeDefined()
+    // Should expose at least FrameRingReader/Writer (per the published API)
+    const m = mod as Record<string, unknown>
+    expect(typeof m['FrameRingReader']).toBe('function')
+    expect(typeof m['FrameRingWriter']).toBe('function')
+  })
+})

package/src/__tests__/device-settings-contribution-dispatch.spec.ts

@@ -0,0 +1,249 @@
+/**
+ * device-settings-contribution-dispatch.spec.ts
+ *
+ * Regression tests for Bug-3: snapshot `getDeviceSettingsContribution` not
+ * found on native provider.
+ *
+ * Root cause: device-manager.addon.ts used `getProviderForDevice` for the
+ * three `exposesDeviceSettings` contribution methods. `getProviderForDevice`
+ * returns the native first when present (e.g. Reolink/ONVIF); the native
+ * only implements camera-specific operations (getSnapshot, invalidateCache),
+ * NOT the contribution methods. The cross-process dispatch then throws
+ * "native-provider: method 'getDeviceSettingsContribution' not found on
+ * 'snapshot'".
+ *
+ * Fix: device-manager now uses `getProvider(capName)` — the active system
+ * singleton (the wrapper, e.g. SnapshotAddon) — for all contribution method
+ * calls. The native is never touched for these methods.
+ *
+ * Spec: docs/superpowers/plans/2026-05-21-addons-bulk-update-progress.md (Bug-3)
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { DeviceManagerAddon } from '@camstack/core'
+import { CapabilityRegistry, DeviceRegistry } from '@camstack/kernel'
+import { snapshotCapability } from '@camstack/types'
+import type {
+  AddonContext, ConfigUISchemaWithValues,
+  IScopedLogger, IEventBus, ProviderRegistration,
+  IDeviceManagerProvider,
+} from '@camstack/types'
+
+// ── Fakes ────────────────────────────────────────────────────────────────────
+
+function makeLogger(): IScopedLogger {
+  const l: IScopedLogger = {
+    info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn(),
+    child: vi.fn(() => l), withTags: vi.fn(() => l),
+  }
+  return l
+}
+
+function makeEventBus(): IEventBus {
+  return { emit: vi.fn(), subscribe: () => () => {}, getRecent: () => [] } as unknown as IEventBus
+}
+
+function makeSettings() {
+  return {
+    readAddonStore: vi.fn(async () => ({})),
+    writeAddonStore: vi.fn(async () => {}),
+    readDeviceStore: vi.fn(async () => ({})),
+    writeDeviceStore: vi.fn(async () => {}),
+  }
+}
+
+/**
+ * Wrapper provider (SnapshotAddon equivalent): registered as a system
+ * singleton via `registerProvider`. Implements ALL three contribution
+ * methods plus the cap-specific operations (getSnapshot, invalidateCache).
+ */
+function makeSnapshotWrapperProvider() {
+  return {
+    // Cap-specific methods
+    getSnapshot: vi.fn(async () => null),
+    invalidateCache: vi.fn(async () => undefined),
+
+    // Contribution methods — owned by the wrapper
+    getDeviceSettingsContribution: vi.fn(async (_input: { deviceId: number }): Promise<ConfigUISchemaWithValues | null> => ({
+      sections: [{
+        id: 'snapshot-settings',
+        title: 'Snapshot',
+        tab: 'general',
+        order: 99,
+        fields: [
+          { type: 'text' as const, key: 'preferredStreamId', label: 'Preferred Stream', default: '', value: '' },
+        ],
+      }],
+    })),
+    getDeviceLiveContribution: vi.fn(async (_input: { deviceId: number }): Promise<ConfigUISchemaWithValues | null> => null),
+    applyDeviceSettingsPatch: vi.fn(async () => ({ success: true as const })),
+  }
+}
+
+/**
+ * Native provider (Reolink/ONVIF/Hikvision equivalent): registered per-device
+ * via `registerNativeProvider`. Implements ONLY the camera-specific operations
+ * (getSnapshot, invalidateCache). Does NOT implement contribution methods.
+ *
+ * Calling any of the three contribution methods on this object simulates the
+ * "method not found" scenario that was Bug-3.
+ */
+function makeSnapshotNativeProvider() {
+  return {
+    getSnapshot: vi.fn(async () => ({
+      base64: 'abc123',
+      contentType: 'image/jpeg',
+    })),
+    invalidateCache: vi.fn(async () => undefined),
+    // Deliberately omit getDeviceSettingsContribution / getDeviceLiveContribution /
+    // applyDeviceSettingsPatch — these don't exist on native providers.
+  }
+}
+
+// ── Scenario setup ────────────────────────────────────────────────────────────
+
+async function setupBug3Scenario() {
+  const addon = new DeviceManagerAddon()
+  const settings = makeSettings()
+  const deviceRegistry = new DeviceRegistry()
+  const capabilityRegistry = new CapabilityRegistry(makeLogger())
+
+  const wrapperProvider = makeSnapshotWrapperProvider()
+  const nativeProvider = makeSnapshotNativeProvider()
+
+  // Declare the snapshot capability (kind:'wrapper', defaultActive:true,
+  // exposesDeviceSettings:true, mode:'singleton').
+  capabilityRegistry.declareCapability(snapshotCapability)
+
+  // Register the WRAPPER as the system singleton — this is what SnapshotAddon does.
+  capabilityRegistry.registerProvider(snapshotCapability.name, 'snapshot-addon', wrapperProvider)
+
+  // Register the default wrapper so auto-bind picks it up in getBindings step 2.
+  capabilityRegistry.registerWrapper(snapshotCapability.name, 'snapshot-addon', { defaultActive: true })
+
+  const ctx = {
+    id: 'device-manager',
+    logger: makeLogger(),
+    eventBus: makeEventBus(),
+    addonConfig: {},
+    dataDir: '/tmp',
+    settings,
+    kernel: { deviceRegistry, capabilityRegistry },
+  }
+
+  const initResult = await addon.initialize(ctx as unknown as AddonContext)
+  let providers: readonly ProviderRegistration[] = []
+  if (Array.isArray(initResult)) {
+    providers = initResult as readonly ProviderRegistration[]
+  } else if (initResult && typeof initResult === 'object' && 'providers' in initResult) {
+    providers = (initResult.providers ?? []) as readonly ProviderRegistration[]
+  }
+  const provider = providers[0]!.provider as IDeviceManagerProvider
+
+  // Allocate and register the device.
+  const { id: deviceId } = await provider.allocateDeviceId({ addonId: 'reolink-addon', stableId: 'cam-reolink-1' })
+  await provider.registerDevice({
+    addonId: 'reolink-addon', stableId: 'cam-reolink-1', id: deviceId,
+    type: 'camera', name: 'Reolink Camera', parentDeviceId: null, config: {},
+  })
+
+  // Register the NATIVE provider for the device — this is what a Reolink/ONVIF
+  // driver does. The native does NOT implement contribution methods.
+  capabilityRegistry.registerNativeProvider(snapshotCapability.name, deviceId, 'reolink-addon', nativeProvider)
+
+  capabilityRegistry.ready()
+
+  return { provider, wrapperProvider, nativeProvider, deviceId }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('device-manager contribution dispatch — Bug-3 regression (snapshot wrapper vs native)', () => {
+  it('routes getDeviceSettingsContribution to the wrapper, never to the native', async () => {
+    const { provider, wrapperProvider, nativeProvider, deviceId } = await setupBug3Scenario()
+
+    // This MUST NOT throw "method not found on native" — the fix routes to the wrapper.
+    const aggregate = await provider.getDeviceSettingsAggregate({ deviceId })
+
+    expect(aggregate).not.toBeNull()
+    // The wrapper's contribution section must be present.
+    const snapshotSection = aggregate!.sections.find(s => s.id === 'snapshot-settings')
+    expect(snapshotSection).toBeDefined()
+    expect(snapshotSection!.title).toBe('Snapshot')
+
+    // Wrapper was called exactly once.
+    expect(wrapperProvider.getDeviceSettingsContribution).toHaveBeenCalledTimes(1)
+    expect(wrapperProvider.getDeviceSettingsContribution).toHaveBeenCalledWith({ deviceId })
+
+    // Native was NOT called — it doesn't implement contribution methods.
+    expect(nativeProvider.getSnapshot).not.toHaveBeenCalled()
+  })
+
+  it('routes getDeviceLiveContribution to the wrapper, never to the native', async () => {
+    const { provider, wrapperProvider, nativeProvider, deviceId } = await setupBug3Scenario()
+
+    // This MUST NOT throw "method not found on native".
+    const liveAggregate = await provider.getDeviceLiveInfoAggregate({ deviceId })
+
+    // The wrapper returns null for live contributions in our fake (acceptable).
+    // Key assertion: the wrapper was invoked, and no error was thrown.
+    expect(wrapperProvider.getDeviceLiveContribution).toHaveBeenCalledTimes(1)
+    expect(wrapperProvider.getDeviceLiveContribution).toHaveBeenCalledWith({ deviceId })
+
+    // Native was NOT called for live contributions.
+    expect(nativeProvider.getSnapshot).not.toHaveBeenCalled()
+    // liveAggregate may be null (wrapper returned null for live) — that's fine.
+    // The important thing is no throw occurred.
+    expect(() => liveAggregate).not.toThrow()
+  })
+
+  it('routes applyDeviceSettingsPatch to the wrapper, never to the native', async () => {
+    const { provider, wrapperProvider, nativeProvider, deviceId } = await setupBug3Scenario()
+
+    // First get the aggregate to confirm the contribution fields are tagged correctly.
+    const aggregate = await provider.getDeviceSettingsAggregate({ deviceId })
+    expect(aggregate).not.toBeNull()
+
+    const field = aggregate!.sections
+      .find(s => s.id === 'snapshot-settings')
+      ?.fields
+      .find(f => (f as Record<string, unknown>)['key'] === 'preferredStreamId') as Record<string, unknown> | undefined
+
+    expect(field).toBeDefined()
+    expect(field!['writerCapName']).toBe('snapshot')
+
+    // Now apply a settings patch — must go to the wrapper, NOT the native.
+    await provider.updateDeviceField({
+      deviceId,
+      writerCapName: 'snapshot',
+      writerAddonId: field!['writerAddonId'] as string,
+      key: 'preferredStreamId',
+      value: 'high',
+    })
+
+    // Wrapper's applyDeviceSettingsPatch was called with the correct patch.
+    expect(wrapperProvider.applyDeviceSettingsPatch).toHaveBeenCalledWith({
+      deviceId,
+      patch: { preferredStreamId: 'high' },
+    })
+
+    // Native was NOT called for the settings write.
+    expect(nativeProvider.getSnapshot).not.toHaveBeenCalled()
+  })
+
+  it('does not throw when both a native and a wrapper provider are registered for the same cap', async () => {
+    // This is the exact Bug-3 scenario: native registered for device, wrapper
+    // registered as system singleton. Before the fix, calling
+    // getDeviceSettingsAggregate would throw because getProviderForDevice
+    // returned the native which lacks contribution methods.
+    const { provider, deviceId } = await setupBug3Scenario()
+
+    // Must complete without throwing.
+    await expect(
+      provider.getDeviceSettingsAggregate({ deviceId }),
+    ).resolves.not.toBeNull()
+
+    await expect(
+      provider.getDeviceLiveInfoAggregate({ deviceId }),
+    ).resolves.toBeDefined()
+  })
+})

package/src/__tests__/framework-installer-defer-restart.spec.ts

@@ -0,0 +1,165 @@
+/**
+ * deferRestart flag on AddonPackageService.updateFrameworkPackage
+ *
+ * Spec: docs/superpowers/specs/2026-05-21-addons-bulk-update-progress-design.md
+ *
+ * Invariants:
+ *   - deferRestart: true  → npm install runs normally; marker write AND
+ *     scheduleSelfRestart are SKIPPED; restartingAt is 0 (sentinel).
+ *   - deferRestart omitted (default) → marker write AND scheduleSelfRestart
+ *     both fire; restartingAt > 0.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import type { IScopedLogger } from '@camstack/types'
+
+// ── Module-level mocks ──────────────────────────────────────────────────────
+// Must be hoisted before any import that loads the module under test.
+// vi.mock is statically hoisted by vitest's transform, so the factories
+// run before the module graph is resolved.
+
+vi.mock('@camstack/kernel', async (importOriginal) => {
+  const real = await importOriginal<typeof import('@camstack/kernel')>()
+  return {
+    ...real,
+    scheduleSelfRestart: vi.fn(),
+    writePendingRestart: vi.fn(),
+    // resolveNpmVersion and resolveFrameworkPackageAppRoot are private module
+    // functions inside addon-package.service.ts — they are NOT exported from
+    // @camstack/kernel, so we don't need to stub them here.
+  }
+})
+
+// Mock node:child_process so no actual `npm install` / `npm view` is executed.
+vi.mock('node:child_process', async (importOriginal) => {
+  const real = await importOriginal<typeof import('node:child_process')>()
+  return {
+    ...real,
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: string[],
+        _opts: unknown,
+        callback: (err: null, result: { stdout: string; stderr: string }) => void,
+      ) => {
+        // Simulate `npm view @camstack/types@0.1.40 version` → '0.1.40'
+        callback(null, { stdout: '0.1.40\n', stderr: '' })
+        return { kill: () => undefined }
+      },
+    ),
+  }
+})
+
+// ── Imports that depend on the mocked modules ───────────────────────────────
+import { scheduleSelfRestart, writePendingRestart } from '@camstack/kernel'
+import { AddonPackageService } from '../core/addon/addon-package.service.js'
+import { EventCategory } from '@camstack/types'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger(): IScopedLogger {
+  const logger: IScopedLogger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    fatal: vi.fn(),
+    child: (() => logger) as IScopedLogger['child'],
+  } as unknown as IScopedLogger
+  return logger
+}
+
+interface ServiceEnv {
+  readonly service: AddonPackageService
+  readonly tmpDir: string
+  readonly scheduleSelfRestartMock: ReturnType<typeof vi.fn>
+  readonly writePendingRestartMock: ReturnType<typeof vi.fn>
+}
+
+function createEnv(): ServiceEnv {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'defer-restart-spec-'))
+
+  const logger = makeLogger()
+
+  const loggingService = {
+    createLogger: () => logger,
+  }
+
+  const eventBusService = {
+    emit: vi.fn(),
+  }
+
+  const configService = {}
+  const addonRegistry = {}
+  const notificationService = {}
+  const toastService = {}
+
+  const service = new AddonPackageService(
+    loggingService as never,
+    eventBusService as never,
+    configService as never,
+    addonRegistry as never,
+    notificationService as never,
+    toastService as never,
+  )
+
+  // Point the framework-package app-root resolver at our tmp dir so
+  // `npm install --prefix <appRoot>` (which is mocked anyway) has a
+  // valid-looking path without requiring the real workspace layout.
+  process.env['CAMSTACK_FRAMEWORK_APP_ROOT_OVERRIDE'] = tmpDir
+
+  return {
+    service,
+    tmpDir,
+    scheduleSelfRestartMock: scheduleSelfRestart as ReturnType<typeof vi.fn>,
+    writePendingRestartMock: writePendingRestart as ReturnType<typeof vi.fn>,
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('AddonPackageService.updateFrameworkPackage — deferRestart flag', () => {
+  let env: ServiceEnv
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    env = createEnv()
+  })
+
+  afterEach(() => {
+    fs.rmSync(env.tmpDir, { recursive: true, force: true })
+    delete process.env['CAMSTACK_FRAMEWORK_APP_ROOT_OVERRIDE']
+    vi.restoreAllMocks()
+  })
+
+  it('skips restart seam (writePendingRestart + scheduleSelfRestart) when deferRestart is true', async () => {
+    const result = await env.service.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+      deferRestart: true,
+    })
+
+    expect(env.writePendingRestartMock).not.toHaveBeenCalled()
+    expect(env.scheduleSelfRestartMock).not.toHaveBeenCalled()
+    expect(result.packageName).toBe('@camstack/types')
+    expect(result.toVersion).toBe('0.1.40')
+    // Sentinel: 0 signals "no restart scheduled"
+    expect(result.restartingAt).toBe(0)
+  })
+
+  it('fires writePendingRestart + scheduleSelfRestart when deferRestart is omitted', async () => {
+    const result = await env.service.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+    })
+
+    expect(env.writePendingRestartMock).toHaveBeenCalledOnce()
+    expect(env.scheduleSelfRestartMock).toHaveBeenCalledOnce()
+    expect(result.packageName).toBe('@camstack/types')
+    expect(result.toVersion).toBe('0.1.40')
+    expect(result.restartingAt).toBeGreaterThan(0)
+  })
+})