@deveye/types 0.15.2 → 0.16.1

package/src/sdk/testing.ts

@@ -1,14 +1,20 @@
 import type { ZodType } from 'zod';
+import type { ItemAccess } from '../domain/sharing';
 import { resolveExtras, type FeatureManifest } from './manifest';
-import type {
-    DevEyeFacade,
-    FeatureServiceDeps,
-    FeatureStore,
-    SdkCipher,
-    SdkDevice,
-    SdkFeatureContext,
-    SdkLogger,
-    StorageEncryption
+import {
+    FeatureError,
+    type DevEyeFacade,
+    type FeatureServiceDeps,
+    type FeatureStore,
+    type SdkCipher,
+    type SdkDevice,
+    type SdkFeatureContext,
+    type SdkLogger,
+    type SdkProviders,
+    type SdkTelemetry,
+    type SdkTelemetrySnapshot,
+    type StorageEncryption,
+    SdkWorkspaceSummary
 } from './server';
 
 /**
@@ -34,6 +40,17 @@ const identityCipher: SdkCipher = {
     tryDecrypt: (blob) => Promise.resolve(blob)
 };
 
+/**
+ * The guarded cipher of a SEALED session: `encrypt` and `decrypt` throw
+ * `locked`, `tryDecrypt` answers null. Handed out for `'private'` when the
+ * harness says `unlocked: false`.
+ */
+const sealedCipher: SdkCipher = {
+    encrypt: () => Promise.reject(new FeatureError('locked', 'Password encryption is locked')),
+    decrypt: () => Promise.reject(new FeatureError('locked', 'Password encryption is locked')),
+    tryDecrypt: () => Promise.resolve(null)
+};
+
 const silentLogger: SdkLogger = {
     debug: () => undefined,
     info: () => undefined,
@@ -78,37 +95,96 @@ function memoryStore(): TestFeatureStore {
 }
 
 export interface RecordedCalls {
-    notifications: { subject: string; body: string; itemId?: number }[];
+    notifications: {
+        subject: string;
+        body: string;
+        itemId?: number;
+        embeds?: number;
+        except?: readonly number[];
+    }[];
+    /** Live messages posted (`messageId: null`) or edited through `notify.postLive`. */
+    liveMessages: { channelId: number; messageId: string | null; embeds?: number }[];
     audits: { action: string; description: string }[];
     /** Outbound agent frames, as `{ method, deviceId }` (payloads dropped for brevity). */
     agentRequests: { method: string; deviceId: string }[];
+    /** Instants pinned through `telemetry.pinInstant`. */
+    pinnedInstants: { deviceId: string; ts: number }[];
 }
 
-function recordingNotify(recorded: RecordedCalls, hasRoute: boolean): DevEyeFacade['notify'] {
+function recordingNotify(
+    recorded: RecordedCalls,
+    hasRoute: boolean,
+    accepted: boolean,
+    liveChannels: readonly number[]
+): DevEyeFacade['notify'] {
+    let posted = 0;
     return {
         hasRoute: () => Promise.resolve(hasRoute),
         send(alert, opts) {
             recorded.notifications.push({
                 subject: alert.subject,
                 body: alert.body,
-                itemId: opts?.itemId
+                itemId: opts?.itemId,
+                // Only when the alert carries a layout: a test that
+                // deep-equals the plain record must not see the key appear.
+                ...(alert.embeds ? { embeds: alert.embeds.length } : {}),
+                ...(opts?.except ? { except: opts.except } : {})
+            });
+            // Recorded either way (the module did try), but a refused delivery
+            // answers false, so a test sees what the module does with it.
+            return Promise.resolve(accepted);
+        },
+        liveChannels: () => Promise.resolve(liveChannels.map((id) => ({ id }))),
+        postLive(channelId, message, messageId) {
+            recorded.liveMessages.push({
+                channelId,
+                messageId: messageId ?? null,
+                ...(message.embeds ? { embeds: message.embeds.length } : {})
             });
-            return Promise.resolve(true);
+            // A post mints an id (`live-1`, `live-2`...), an edit keeps the
+            // one it was given; a refusing host answers null either way.
+            if (!accepted) return Promise.resolve(null);
+            return Promise.resolve(messageId ?? `live-${++posted}`);
         }
     };
 }
 
+/** A device the harness invents for an id nothing listed: active, online, unreported. */
+export function testDevice(over: Partial<SdkDevice> & { id: string }): SdkDevice {
+    return {
+        name: 'Test device',
+        online: true,
+        status: 'active',
+        ownerUserId: 1,
+        workspaceId: 1,
+        metricIntervalSeconds: null,
+        report: null,
+        ...over
+    };
+}
+
 function recordingDevices(devices: readonly SdkDevice[]): DevEyeFacade['devices'] {
     return {
-        authorize: (id) =>
-            Promise.resolve(
-                devices.find((d) => d.id === id) ?? { id, name: 'Test device', online: true }
-            ),
+        authorize: (id) => Promise.resolve(devices.find((d) => d.id === id) ?? testDevice({ id })),
         list: () => Promise.resolve([...devices]),
         isOnline: (id) => devices.find((d) => d.id === id)?.online ?? true
     };
 }
 
+function recordingTelemetry(
+    recorded: RecordedCalls,
+    snapshots: readonly SdkTelemetrySnapshot[]
+): SdkTelemetry {
+    return {
+        snapshot: (_deviceId, ts) =>
+            Promise.resolve(snapshots.find((s) => Math.abs(s.ts - ts) <= 1000) ?? null),
+        pinInstant(deviceId, ts) {
+            recorded.pinnedInstants.push({ deviceId, ts });
+            return Promise.resolve();
+        }
+    };
+}
+
 function recordingAgents(recorded: RecordedCalls): DevEyeFacade['agents'] {
     const req = (method: string) => (deviceId: string) => {
         recorded.agentRequests.push({ method, deviceId });
@@ -116,6 +192,8 @@ function recordingAgents(recorded: RecordedCalls): DevEyeFacade['agents'] {
     };
     return {
         isOnline: () => true,
+        requestScan: req('requestScan'),
+        pushConfig: (deviceId) => Promise.resolve(req('pushConfig')(deviceId)),
         requestSyncConfig: req('requestSyncConfig'),
         requestSyncScan: req('requestSyncScan'),
         requestSyncPush: req('requestSyncPush'),
@@ -126,13 +204,46 @@ function recordingAgents(recorded: RecordedCalls): DevEyeFacade['agents'] {
         requestSyncMove: req('requestSyncMove'),
         requestSyncDelete: req('requestSyncDelete'),
         publishSyncProgress: () => undefined,
-        publishSyncState: () => undefined
+        publishSyncState: () => undefined,
+        requestDestroy: req('requestDestroy'),
+        disconnectAgent: req('disconnectAgent'),
+        resetAgentSession: req('resetAgentSession'),
+        // Nothing synced: a test of the self-update flag feeds a manifest to
+        // the module's own pure helper.
+        servedManifest: () => Promise.resolve(null),
+        requestFilesMutate: req('requestFilesMutate'),
+        requestFilesUpload: req('requestFilesUpload'),
+        // Every file order succeeds at once: a test of what a module does
+        // with a refusal injects its own facade through `deveye`.
+        awaitFilesOp: () => Promise.resolve({ ok: true }),
+        cancelFilesOp: () => undefined,
+        buffered: () => 0
     };
 }
 
+/**
+ * A deterministic stand-in for `keys.derive`: the same (salt, info) yields
+ * the same bytes, distinct pairs distinct bytes, and nothing here is secret.
+ */
+function fakeDerive(salt: string, info: string, length: number): Uint8Array {
+    const out = new Uint8Array(length);
+    const seed = `${salt}|${info}`;
+    for (let i = 0; i < length; i += 1) {
+        out[i] = (seed.charCodeAt(i % seed.length) * (i + 1)) & 0xff;
+    }
+    return out;
+}
+
+/** The named contracts a test hands to the module (`providers` override). */
+function fakeProviders(table: Readonly<Record<string, unknown>>): SdkProviders {
+    return { get: <T>(key: string) => table[key] as T | undefined };
+}
+
 export interface TestContext<Repo> extends SdkFeatureContext<Repo> {
     recorded: RecordedCalls;
     store: TestFeatureStore;
+    /** Item ids passed to `items.forget`, in order. */
+    forgotten: number[];
 }
 
 export interface TestContextOverrides<Repo> {
@@ -141,6 +252,10 @@ export interface TestContextOverrides<Repo> {
     workspaceId?: number;
     kind?: 'personal' | 'shared';
     isOwner?: boolean;
+    /** Global administrator. Default false. */
+    isAdmin?: boolean;
+    /** What `deveye.workspaces.list()` answers. Default none. */
+    workspaces?: readonly SdkWorkspaceSummary[];
     canWrite?: boolean;
     /** Extra permissions the caller holds, as the grant would carry them. */
     extras?: Record<string, boolean | string>;
@@ -152,40 +267,135 @@ export interface TestContextOverrides<Repo> {
     manifest?: Pick<FeatureManifest, 'extraPermissions'>;
     /** What `deveye.notify.hasRoute` answers. Default true. */
     hasRoute?: boolean;
+    /** What `deveye.notify.send` resolves (no usable channel: false). Default true; recorded either way. */
+    notifyAccepted?: boolean;
+    /** What `ctx.origins` answers. Default `https://deveye.test` / `https://public.deveye.test`. */
+    origins?: { app: string; public: string };
+    /** The channel ids `deveye.notify.liveChannels` lists. Default none. */
+    liveChannels?: readonly number[];
     /** Devices `deveye.devices` reveals. Default none listed, any id authorized. */
     devices?: readonly SdkDevice[];
+    /** Instants `deveye.telemetry.snapshot` answers (matched within a second). Default none. */
+    snapshots?: readonly SdkTelemetrySnapshot[];
     /** Override facade members entirely when the defaults are not enough. */
     deveye?: Partial<DevEyeFacade>;
+    /**
+     * What `secrecy.isUnlocked` answers. Default true. When false, the
+     * `'private'` cipher is sealed too (`decrypt` throws `locked`,
+     * `tryDecrypt` answers null), exactly like the app's guarded tier in a
+     * locked session; the `'server'` cipher stays the identity.
+     */
+    unlocked?: boolean;
+    /** The caller's role restrictions on items, by item id. Default none. */
+    itemRestrictions?: Readonly<Record<number, ItemAccess>>;
+    /**
+     * Items projected INTO the workspace, as `itemId → home workspace id`.
+     * Default none: every item is at home. `sharing.scope().cipherFor` is the
+     * identity cipher either way.
+     */
+    shares?: Readonly<Record<number, number>>;
+    /** The named contracts the host holds (`ctx.providers.get(key)`). */
+    providers?: Readonly<Record<string, unknown>>;
 }
 
 export function createTestContext<Repo = undefined>(
     overrides: TestContextOverrides<Repo> = {}
 ): TestContext<Repo> {
-    const recorded: RecordedCalls = { notifications: [], audits: [], agentRequests: [] };
+    const recorded: RecordedCalls = {
+        notifications: [],
+        liveMessages: [],
+        audits: [],
+        agentRequests: [],
+        pinnedInstants: []
+    };
     const isOwner = overrides.isOwner ?? true;
     const workspaceId = overrides.workspaceId ?? 1;
+    const canWrite = overrides.canWrite ?? true;
     const deveye: DevEyeFacade = {
-        notify: recordingNotify(recorded, overrides.hasRoute ?? true),
+        notify: recordingNotify(
+            recorded,
+            overrides.hasRoute ?? true,
+            overrides.notifyAccepted ?? true,
+            overrides.liveChannels ?? []
+        ),
         mail: { listAccounts: () => Promise.resolve([]) },
         members: {
             list: () =>
-                Promise.resolve([{ userId: overrides.userId ?? 1, name: 'Test', isOwner: true }])
+                Promise.resolve([
+                    { userId: overrides.userId ?? 1, name: 'Test', isOwner: true, color: null }
+                ])
         },
+        workspaces: { list: () => Promise.resolve(overrides.workspaces ?? []) },
         devices: recordingDevices(overrides.devices ?? []),
+        telemetry: recordingTelemetry(recorded, overrides.snapshots ?? []),
         agents: recordingAgents(recorded),
         ...overrides.deveye
     };
+    const restrictions = new Map<number, ItemAccess>(
+        Object.entries(overrides.itemRestrictions ?? {}).map(([id, access]) => [Number(id), access])
+    );
+    const homes = new Map<number, number>(
+        Object.entries(overrides.shares ?? {}).map(([id, home]) => [Number(id), home])
+    );
+    const forgotten: number[] = [];
     return {
         recorded,
+        forgotten,
+        secrecy: {
+            isUnlocked: () => Promise.resolve(overrides.unlocked ?? true),
+            // Un ticket lisible tel quel : le harnais ne signe rien, il
+            // sérialise, et `createTestServiceDeps().secrecy.redeem` relit.
+            ticket: (payload) =>
+                Promise.resolve(
+                    `ticket:${JSON.stringify({ userId: overrides.userId ?? 1, workspaceId, payload, unlocked: overrides.unlocked ?? true })}`
+                )
+        },
+        keys: {
+            sealBytes: (plain) => `sealed:${Buffer.from(plain).toString('base64')}`,
+            openBytes: () => null,
+            derive: fakeDerive
+        },
+        items: {
+            restrictions: () => Promise.resolve(restrictions),
+            // The exact rule of the app's dispatcher: the feature first (a
+            // restriction can only lower), then the row.
+            assert(itemId, level = 'read') {
+                if (level === 'write' && !canWrite) {
+                    return Promise.reject(new FeatureError('forbidden', 'write required'));
+                }
+                const restriction = restrictions.get(itemId);
+                if (restriction === 'none') {
+                    return Promise.reject(new FeatureError('forbidden', 'item hidden'));
+                }
+                if (restriction === 'read' && level === 'write') {
+                    return Promise.reject(new FeatureError('forbidden', 'item read-only'));
+                }
+                return Promise.resolve();
+            },
+            forget(itemId) {
+                forgotten.push(itemId);
+                return Promise.resolve();
+            }
+        },
+        sharing: {
+            scope: () =>
+                Promise.resolve({
+                    foreignIds: new Set(homes.keys()),
+                    homeOf: (itemId) => homes.get(itemId) ?? null,
+                    cipherFor: () => Promise.resolve(identityCipher)
+                })
+        },
         userId: overrides.userId ?? 1,
         workspaceId,
         workspace: { id: workspaceId, kind: overrides.kind ?? 'personal', name: 'Test' },
         isOwner,
+        isAdmin: overrides.isAdmin ?? false,
         canWrite: overrides.canWrite ?? true,
         ...resolveExtras(overrides.manifest?.extraPermissions, isOwner, overrides.extras ?? {}),
         repo: overrides.repo as Repo,
         store: memoryStore(),
-        cipher: () => identityCipher,
+        cipher: (mode) =>
+            mode === 'private' && overrides.unlocked === false ? sealedCipher : identityCipher,
         deveye,
         transport: {
             subscribeSync: () => undefined,
@@ -193,17 +403,26 @@ export function createTestContext<Repo = undefined>(
             sendSyncChunk: () => 0,
             syncChunkBuffered: () => 0
         },
+        providers: fakeProviders(overrides.providers ?? {}),
         audit: (entry) => {
             recorded.audits.push({ action: entry.action, description: entry.description });
         },
         logger: silentLogger,
-        requestId: 'test'
+        requestId: 'test',
+        origins: overrides.origins ?? {
+            app: 'https://deveye.test',
+            public: 'https://public.deveye.test'
+        }
     };
 }
 
 export interface RecordedServiceCalls extends RecordedCalls {
     /** Every `createTicker` call, so a test drives ticks by hand: `await tickers[0].tick()`. */
     tickers: { intervalMs: number; tick(): Promise<void> }[];
+    /** Workspaces passed to `live.changed`, in order. */
+    liveChanges: number[];
+    /** `live.changed` calls that named topics, as `{ workspaceId, topics }` (a bare beat is not listed here). */
+    liveTopicChanges: { workspaceId: number; topics: readonly string[] }[];
 }
 
 export interface TestServiceDeps<Repo> extends FeatureServiceDeps<Repo> {
@@ -220,6 +439,16 @@ export interface TestServiceOverrides<Repo> {
     devices?: readonly SdkDevice[];
     /** What `deveyeFor(...).notify.hasRoute` answers. Default true. */
     hasRoute?: boolean;
+    /** What `deveyeFor(...).notify.send` resolves. Default true; recorded either way. */
+    notifyAccepted?: boolean;
+    /** The channel ids `deveyeFor(...).notify.liveChannels` lists. Default none. */
+    liveChannels?: readonly number[];
+    /** What `deps.origins` answers. Default `https://deveye.test` / `https://public.deveye.test`. */
+    origins?: { app: string; public: string };
+    /** Instants `telemetry.snapshot` answers (matched within a second). Default none. */
+    snapshots?: readonly SdkTelemetrySnapshot[];
+    /** The named contracts the host holds (`deps.providers.get(key)`). */
+    providers?: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -232,13 +461,22 @@ export function createTestServiceDeps<Repo = undefined>(
 ): TestServiceDeps<Repo> {
     const recorded: RecordedServiceCalls = {
         notifications: [],
+        liveMessages: [],
         audits: [],
         agentRequests: [],
-        tickers: []
+        pinnedInstants: [],
+        tickers: [],
+        liveChanges: [],
+        liveTopicChanges: []
     };
     const stores = new Map<number, TestFeatureStore>();
     const sealedBytes = new Map<string, Uint8Array>();
-    const notify = recordingNotify(recorded, overrides.hasRoute ?? true);
+    const notify = recordingNotify(
+        recorded,
+        overrides.hasRoute ?? true,
+        overrides.notifyAccepted ?? true,
+        overrides.liveChannels ?? []
+    );
     const devices = recordingDevices(overrides.devices ?? []);
     return {
         recorded,
@@ -255,7 +493,43 @@ export function createTestServiceDeps<Repo = undefined>(
         },
         cipherFor: () => identityCipher,
         deveyeFor: () => ({ notify }),
+        origins: overrides.origins ?? {
+            app: 'https://deveye.test',
+            public: 'https://public.deveye.test'
+        },
+        secrecy: {
+            redeem: (ticket) => {
+                if (!ticket.startsWith('ticket:')) return Promise.resolve(null);
+                const parsed = JSON.parse(ticket.slice('ticket:'.length)) as {
+                    userId: number;
+                    workspaceId: number;
+                    payload: unknown;
+                    unlocked: boolean;
+                };
+                return Promise.resolve({
+                    userId: parsed.userId,
+                    workspaceId: parsed.workspaceId,
+                    payload: parsed.payload,
+                    cipher: {
+                        server: identityCipher,
+                        private: parsed.unlocked ? identityCipher : null
+                    }
+                });
+            }
+        },
         devicesFor: () => ({ list: devices.list, isOnline: devices.isOnline }),
+        devices: {
+            find: (id) =>
+                Promise.resolve((overrides.devices ?? []).find((d) => d.id === id) ?? null),
+            isOnline: devices.isOnline
+        },
+        telemetry: recordingTelemetry(recorded, overrides.snapshots ?? []),
+        live: {
+            changed(workspaceId, topics) {
+                recorded.liveChanges.push(workspaceId);
+                if (topics) recorded.liveTopicChanges.push({ workspaceId, topics });
+            }
+        },
         audit: (entry) => {
             recorded.audits.push({ action: entry.action, description: entry.description });
         },
@@ -268,8 +542,10 @@ export function createTestServiceDeps<Repo = undefined>(
                 sealedBytes.set(handle, Uint8Array.from(plain));
                 return handle;
             },
-            openBytes: (sealed) => sealedBytes.get(sealed) ?? null
+            openBytes: (sealed) => sealedBytes.get(sealed) ?? null,
+            derive: fakeDerive
         },
+        providers: fakeProviders(overrides.providers ?? {}),
         createTicker({ intervalMs, tick }) {
             recorded.tickers.push({ intervalMs, tick });
             return { start: () => undefined, stop: () => undefined };

package/src/utils/version.ts

@@ -1,13 +1,10 @@
 /**
- * Dotted-numeric version helpers shared by the server (which decides whether to
- * offer/push an agent self-update) and the web client (which decides whether to
- * show the affordance). Keeping a single implementation here means both ends agree
- * on what "newer" means — a self-update is only ever offered/pushed as an UPGRADE,
- * never a downgrade, even if the served manifest happens to lag a running agent.
+ * Dotted-numeric version helpers shared by the server (offers/pushes an agent
+ * self-update) and the web client (shows the affordance), so both agree on what
+ * "newer" means: a self-update is only ever an upgrade, never a downgrade.
  *
- * Non-numeric segments are treated as 0 and missing segments as 0, so `1.2` and
- * `1.2.0` compare equal. No pre-release/build-metadata handling: DevEye versions
- * come from a single `package.json`, so plain dotted integers are enough.
+ * Non-numeric and missing segments count as 0, so `1.2` equals `1.2.0`. No
+ * pre-release handling: DevEye versions are plain dotted integers.
  */
 
 /** Compare dotted numeric versions: <0 if a<b, >0 if a>b, 0 if equal. */