@deveye/types 0.15.1 → 0.15.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deveye/types",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Shared contracts (types + zod schemas) for DevEye apps",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -41,9 +41,10 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "tsc --noEmit",
-    "ci": "npm run lint && npm run typecheck",
+    "ci": "npm run lint && npm run typecheck && npm test",
     "prettier": "prettier --check .",
-    "prettier:fix": "prettier --write ."
+    "prettier:fix": "prettier --write .",
+    "test": "tsx --test \"src/**/*.test.ts\""
   },
   "dependencies": {
     "zod": "^4.4.3"
@@ -54,11 +55,13 @@
   },
   "devDependencies": {
     "@eslint/js": "^8.0.0",
+    "@types/node": "^26.3.0",
     "@types/react": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.0.0",
     "eslint-plugin-prettier": "^5.5.4",
+    "tsx": "^4.23.12",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.39.1"
   },

package/src/sdk/client-ambient.d.ts

@@ -78,6 +78,15 @@ declare module 'deveye-sdk-client' {
         fill?: boolean;
         holdSecrecy?: boolean;
     }>;
+    /** Request the enclosing Dialog's guarded close (the unsaved-changes prompt included). */
+    export function useDialogClose(): () => void;
+    /** Register `fn` as the enclosing Dialog's primary action (Enter triggers it); `null` clears it. */
+    export function useDialogSubmit(fn: (() => void) | null): void;
+    /**
+     * Register `onEscape` as the topmost dismissible layer while `open`, so
+     * Escape closes overlays innermost first. `null` absorbs Escape without closing.
+     */
+    export function useDismissLayer(open: boolean, onEscape: (() => void) | null): void;
     export const StatusBadge: ComponentType<{
         tone?: 'online' | 'offline' | 'success' | 'warning' | 'danger' | 'accent' | 'neutral';
         /** Show the leading status dot (default true). */
@@ -158,8 +167,14 @@ declare module 'deveye-sdk-client' {
     export interface SecrecyState {
         /** True when password-based encryption is enabled for the account. */
         enabled: boolean;
-        /** True while the session holds the unlocked key. */
+        /** True while the session holds the unlocked key (no prompt needed). */
         unlocked: boolean;
+        /** True while the unlock dialog is open. */
+        prompting: boolean;
+        /** Epoch ms at which the grace window expires, or null when nothing counts down. */
+        unlockedUntil: number | null;
+        /** "Validate on every action": the key is never cached, unlocking ahead of time is pointless. */
+        alwaysPrompt: boolean;
     }
     /** Live lock state of the session (shared with the topbar widget and the global prompt). */
     export function useSecrecy(): SecrecyState;

package/src/sdk/manifest.test.ts

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { z } from 'zod';
+
+import {
+    externalDescriptorOf,
+    resolveExtras,
+    validateManifest,
+    type FeatureManifest
+} from './manifest';
+
+const base: FeatureManifest = {
+    id: 'x-demo',
+    label: 'Demo',
+    description: 'A demo module.',
+    icon: 'x-demo-icon',
+    category: 'daily',
+    notifies: false,
+    hasItems: false,
+    shareTier: 'never',
+    resources: ['x-demo.state'],
+    commands: [{ command: 'x-demo.get', input: z.object({}), output: z.object({}) }]
+};
+
+test('validateManifest accepts a minimal external manifest', () => {
+    assert.doesNotThrow(() => validateManifest(base));
+});
+
+test('validateManifest rejects the classic mistakes', () => {
+    const rejects = (patch: Partial<FeatureManifest>, fragment: string) =>
+        assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
+    rejects({ label: '  ' }, 'empty label');
+    rejects({ hasItems: true }, 'itemNoun');
+    rejects({ itemSegment: (id) => `item:${id}` }, 'itemSegment');
+    rejects({ shareTier: 'open' }, "shareTier 'never'");
+    rejects({ commandPrefix: 'x-demo.' }, 'commandPrefix');
+    rejects(
+        { commands: [{ command: 'other.get', input: z.object({}), output: z.object({}) }] },
+        'x-demo'
+    );
+});
+
+test('externalDescriptorOf projects the identity fields only, and refuses a native id', () => {
+    assert.deepEqual(
+        externalDescriptorOf({ ...base, itemNoun: 'thing', sources: { hint: 'keys' } }),
+        {
+            id: 'x-demo',
+            label: 'Demo',
+            description: 'A demo module.',
+            icon: 'x-demo-icon',
+            notifies: false,
+            hasItems: false,
+            itemNoun: 'thing',
+            sources: { hint: 'keys' },
+            shareTier: 'never'
+        }
+    );
+    assert.throws(() => externalDescriptorOf({ ...base, id: 'weather' }), /not an external id/);
+});
+
+test('resolveExtras: the owner holds everything, a member what the grant says, unknown keys nothing', () => {
+    const specs: FeatureManifest['extraPermissions'] = [
+        { key: 'reset', type: 'toggle', label: 'Reset', description: '' },
+        {
+            key: 'limit',
+            type: 'choice',
+            label: 'Limit',
+            description: '',
+            options: [
+                { value: 'low', label: 'Low' },
+                { value: 'high', label: 'High' }
+            ],
+            default: 'low',
+            ownerValue: 'high'
+        }
+    ];
+    const owner = resolveExtras(specs, true, {});
+    assert.equal(owner.canExtra('reset'), true);
+    assert.equal(owner.extraValue('limit'), 'high');
+
+    const member = resolveExtras(specs, false, { reset: true, limit: 'high' });
+    assert.equal(member.canExtra('reset'), true);
+    assert.equal(member.extraValue('limit'), 'high');
+
+    const restricted = resolveExtras(specs, false, { reset: false, limit: 'bogus' });
+    assert.equal(restricted.canExtra('reset'), false);
+    assert.equal(
+        restricted.extraValue('limit'),
+        'low',
+        'a value outside the options falls back to the default'
+    );
+
+    // Wrong kind or undeclared: nothing, owner or not.
+    assert.equal(owner.canExtra('limit'), false);
+    assert.equal(owner.extraValue('reset'), '');
+    assert.equal(resolveExtras(undefined, true, { reset: true }).canExtra('reset'), false);
+});

package/src/sdk/manifest.ts

@@ -1,7 +1,9 @@
 import type { ZodType } from 'zod';
+import type { FeatureDescriptor } from '../domain/featureRegistry';
 import {
     EXTERNAL_FEATURE_ID_PATTERN,
     isExternalFeatureId,
+    type ExternalFeatureId,
     type FeatureId
 } from '../domain/workspaceRole';
 
@@ -324,3 +326,67 @@ export function validateManifest(m: FeatureManifest): void {
         }
     }
 }
+
+/**
+ * The registry descriptor of an EXTERNAL module, read off its manifest: what
+ * the roles screen, the settings shell and the catalog need to know without
+ * opening the module. Natives keep their published descriptor; the app's
+ * server and client registries both project through here.
+ */
+export function externalDescriptorOf(
+    m: FeatureManifest
+): FeatureDescriptor & { id: ExternalFeatureId } {
+    if (!isExternalFeatureId(m.id)) {
+        throw new Error(`externalDescriptorOf: « ${m.id} » is not an external id`);
+    }
+    return {
+        id: m.id,
+        label: m.label,
+        description: m.description,
+        icon: m.icon,
+        notifies: m.notifies,
+        hasItems: m.hasItems,
+        itemNoun: m.itemNoun,
+        sources: m.sources,
+        shareTier: m.shareTier
+    };
+}
+
+export interface ExtrasResolver {
+    canExtra(key: string): boolean;
+    extraValue(key: string): string;
+}
+
+/**
+ * The runtime rules of extra permissions, shared by the app's request context
+ * and the test harness so the two can never drift:
+ *  - a key the manifest does not declare, or of the other kind, yields
+ *    `false` / `''`;
+ *  - the workspace owner holds every toggle and gets `ownerValue` of every
+ *    choice;
+ *  - a member holds a toggle when the grant says `true`, and gets a choice's
+ *    granted value when it is one of the options, `default` otherwise.
+ */
+export function resolveExtras(
+    specs: readonly ExtraPermissionSpec[] | undefined,
+    isOwner: boolean,
+    granted: Readonly<Record<string, boolean | string>>
+): ExtrasResolver {
+    const byKey = new Map((specs ?? []).map((spec) => [spec.key, spec]));
+    return {
+        canExtra(key) {
+            const spec = byKey.get(key);
+            if (!spec || spec.type !== 'toggle') return false;
+            return isOwner || granted[key] === true;
+        },
+        extraValue(key) {
+            const spec = byKey.get(key);
+            if (!spec || spec.type !== 'choice') return '';
+            if (isOwner) return spec.ownerValue;
+            const value = granted[key];
+            return typeof value === 'string' && spec.options.some((o) => o.value === value)
+                ? value
+                : spec.default;
+        }
+    };
+}

package/src/sdk/testing.test.ts

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { z } from 'zod';
+
+import { createTestContext, createTestServiceDeps } from './testing';
+
+test('createTestContext follows the manifest for extras, and records what handlers do', async () => {
+    const manifest = {
+        extraPermissions: [
+            { key: 'reset', type: 'toggle' as const, label: 'Reset', description: '' }
+        ]
+    };
+    const member = createTestContext({ manifest, isOwner: false, extras: { reset: true } });
+    assert.equal(member.canExtra('reset'), true);
+    assert.equal(createTestContext({ manifest, isOwner: false }).canExtra('reset'), false);
+    assert.equal(
+        createTestContext({ isOwner: true }).canExtra('reset'),
+        false,
+        'no manifest, no extra'
+    );
+
+    await member.deveye.notify.send({ subject: 's', body: 'b' }, { itemId: 3 });
+    member.audit({ action: 'x.did', description: 'did' });
+    assert.deepEqual(member.recorded.notifications, [{ subject: 's', body: 'b', itemId: 3 }]);
+    assert.deepEqual(member.recorded.audits, [{ action: 'x.did', description: 'did' }]);
+
+    await member.store.putJson(
+        'k',
+        z.object({ n: z.number() }),
+        { n: 1 },
+        { encryption: 'private' }
+    );
+    assert.equal(member.store.rows.get('k')?.mode, 'private');
+});
+
+test('createTestServiceDeps: one store per workspace, hand-driven tickers, a wrapper that round-trips', async () => {
+    const deps = createTestServiceDeps({
+        workspaceIds: [1, 2],
+        devices: [{ id: 'd1', name: 'One', online: false }]
+    });
+    assert.deepEqual(await deps.listWorkspaceIds(), [1, 2]);
+    await deps.storeFor(1).put('a', '1');
+    assert.equal(await deps.storeFor(2).get('a'), null);
+    assert.equal(deps.stores.size, 2);
+
+    let beats = 0;
+    const service = deps.createTicker({
+        intervalMs: 1000,
+        tick: () => Promise.resolve(void beats++)
+    });
+    await service.start();
+    assert.equal(beats, 0, 'a ticker never starts on its own');
+    await deps.recorded.tickers[0].tick();
+    assert.equal(beats, 1);
+
+    const sealed = deps.keys.sealBytes(new Uint8Array([1, 2, 3]));
+    assert.deepEqual(deps.keys.openBytes(sealed), new Uint8Array([1, 2, 3]));
+    assert.equal(deps.keys.openBytes('nope'), null);
+
+    assert.equal(deps.devicesFor(1).isOnline('d1'), false);
+    assert.equal((await deps.devicesFor(1).list()).length, 1);
+});

package/src/sdk/testing.ts

@@ -1,22 +1,30 @@
 import type { ZodType } from 'zod';
+import { resolveExtras, type FeatureManifest } from './manifest';
 import type {
     DevEyeFacade,
+    FeatureServiceDeps,
     FeatureStore,
     SdkCipher,
+    SdkDevice,
     SdkFeatureContext,
     SdkLogger,
     StorageEncryption
 } from './server';
 
 /**
- * Test harness for feature handlers: a fully in-memory {@link SdkFeatureContext}
- * with identity ciphers, a recording facade, and a silent logger. Call your
- * handlers directly from `node:test` files; no app, no database, no socket.
+ * Test harnesses: a fully in-memory {@link SdkFeatureContext} for handlers and
+ * a matching {@link FeatureServiceDeps} for background services, with
+ * identity ciphers, a recording facade, and a silent logger. Call your code
+ * directly from `node:test` files; no app, no database, no socket.
  *
  * ```ts
- * const ctx = createTestContext({ repo: fakeRepo() });
+ * const ctx = createTestContext({ repo: fakeRepo(), manifest });
  * const out = await myFeature.features[0].handler(ctx, { name: 'x' });
  * assert.equal(ctx.recorded.notifications.length, 1);
+ *
+ * const deps = createTestServiceDeps({ repo: fakeRepo() });
+ * const service = myServer.createService(deps);
+ * await deps.recorded.tickers[0].tick();
  * ```
  */
 
@@ -76,6 +84,31 @@ export interface RecordedCalls {
     agentRequests: { method: string; deviceId: string }[];
 }
 
+function recordingNotify(recorded: RecordedCalls, hasRoute: boolean): DevEyeFacade['notify'] {
+    return {
+        hasRoute: () => Promise.resolve(hasRoute),
+        send(alert, opts) {
+            recorded.notifications.push({
+                subject: alert.subject,
+                body: alert.body,
+                itemId: opts?.itemId
+            });
+            return Promise.resolve(true);
+        }
+    };
+}
+
+function recordingDevices(devices: readonly SdkDevice[]): DevEyeFacade['devices'] {
+    return {
+        authorize: (id) =>
+            Promise.resolve(
+                devices.find((d) => d.id === id) ?? { id, name: 'Test device', online: true }
+            ),
+        list: () => Promise.resolve([...devices]),
+        isOnline: (id) => devices.find((d) => d.id === id)?.online ?? true
+    };
+}
+
 function recordingAgents(recorded: RecordedCalls): DevEyeFacade['agents'] {
     const req = (method: string) => (deviceId: string) => {
         recorded.agentRequests.push({ method, deviceId });
@@ -111,8 +144,16 @@ export interface TestContextOverrides<Repo> {
     canWrite?: boolean;
     /** Extra permissions the caller holds, as the grant would carry them. */
     extras?: Record<string, boolean | string>;
+    /**
+     * Your manifest: `canExtra` / `extraValue` then follow the exact runtime
+     * rules ({@link resolveExtras}). Without it no extra is declared, so
+     * every key answers `false` / `''`, owner or not.
+     */
+    manifest?: Pick<FeatureManifest, 'extraPermissions'>;
     /** What `deveye.notify.hasRoute` answers. Default true. */
     hasRoute?: boolean;
+    /** Devices `deveye.devices` reveals. Default none listed, any id authorized. */
+    devices?: readonly SdkDevice[];
     /** Override facade members entirely when the defaults are not enough. */
     deveye?: Partial<DevEyeFacade>;
 }
@@ -121,30 +162,16 @@ export function createTestContext<Repo = undefined>(
     overrides: TestContextOverrides<Repo> = {}
 ): TestContext<Repo> {
     const recorded: RecordedCalls = { notifications: [], audits: [], agentRequests: [] };
-    const extras = overrides.extras ?? {};
+    const isOwner = overrides.isOwner ?? true;
     const workspaceId = overrides.workspaceId ?? 1;
     const deveye: DevEyeFacade = {
-        notify: {
-            hasRoute: () => Promise.resolve(overrides.hasRoute ?? true),
-            send(alert, opts) {
-                recorded.notifications.push({
-                    subject: alert.subject,
-                    body: alert.body,
-                    itemId: opts?.itemId
-                });
-                return Promise.resolve(true);
-            }
-        },
+        notify: recordingNotify(recorded, overrides.hasRoute ?? true),
         mail: { listAccounts: () => Promise.resolve([]) },
         members: {
             list: () =>
                 Promise.resolve([{ userId: overrides.userId ?? 1, name: 'Test', isOwner: true }])
         },
-        devices: {
-            authorize: (id) => Promise.resolve({ id, name: 'Test device', online: true }),
-            list: () => Promise.resolve([]),
-            isOnline: () => true
-        },
+        devices: recordingDevices(overrides.devices ?? []),
         agents: recordingAgents(recorded),
         ...overrides.deveye
     };
@@ -153,13 +180,9 @@ export function createTestContext<Repo = undefined>(
         userId: overrides.userId ?? 1,
         workspaceId,
         workspace: { id: workspaceId, kind: overrides.kind ?? 'personal', name: 'Test' },
-        isOwner: overrides.isOwner ?? true,
+        isOwner,
         canWrite: overrides.canWrite ?? true,
-        canExtra: (key) => (overrides.isOwner ?? true) || extras[key] === true,
-        extraValue: (key) => {
-            const value = extras[key];
-            return typeof value === 'string' ? value : '';
-        },
+        ...resolveExtras(overrides.manifest?.extraPermissions, isOwner, overrides.extras ?? {}),
         repo: overrides.repo as Repo,
         store: memoryStore(),
         cipher: () => identityCipher,
@@ -177,3 +200,80 @@ export function createTestContext<Repo = undefined>(
         requestId: '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> }[];
+}
+
+export interface TestServiceDeps<Repo> extends FeatureServiceDeps<Repo> {
+    recorded: RecordedServiceCalls;
+    /** One in-memory store per workspace touched, keyed by workspace id. */
+    stores: Map<number, TestFeatureStore>;
+}
+
+export interface TestServiceOverrides<Repo> {
+    repo?: Repo;
+    /** What `listWorkspaceIds` answers. Default `[1]`. */
+    workspaceIds?: readonly number[];
+    /** Devices every workspace reveals. Default none. */
+    devices?: readonly SdkDevice[];
+    /** What `deveyeFor(...).notify.hasRoute` answers. Default true. */
+    hasRoute?: boolean;
+}
+
+/**
+ * The service twin of {@link createTestContext}: sessionless, so no guarded
+ * cipher and no `'private'` rows, exactly like the app. Tickers never start on
+ * their own; the test calls `recorded.tickers[i].tick()` when it wants a beat.
+ */
+export function createTestServiceDeps<Repo = undefined>(
+    overrides: TestServiceOverrides<Repo> = {}
+): TestServiceDeps<Repo> {
+    const recorded: RecordedServiceCalls = {
+        notifications: [],
+        audits: [],
+        agentRequests: [],
+        tickers: []
+    };
+    const stores = new Map<number, TestFeatureStore>();
+    const sealedBytes = new Map<string, Uint8Array>();
+    const notify = recordingNotify(recorded, overrides.hasRoute ?? true);
+    const devices = recordingDevices(overrides.devices ?? []);
+    return {
+        recorded,
+        stores,
+        repo: overrides.repo as Repo,
+        listWorkspaceIds: () => Promise.resolve([...(overrides.workspaceIds ?? [1])]),
+        storeFor(workspaceId) {
+            let store = stores.get(workspaceId);
+            if (!store) {
+                store = memoryStore();
+                stores.set(workspaceId, store);
+            }
+            return store;
+        },
+        cipherFor: () => identityCipher,
+        deveyeFor: () => ({ notify }),
+        devicesFor: () => ({ list: devices.list, isOnline: devices.isOnline }),
+        audit: (entry) => {
+            recorded.audits.push({ action: entry.action, description: entry.description });
+        },
+        agents: recordingAgents(recorded),
+        // A fake wrapper: the sealed string is a handle to the bytes, and an
+        // unknown handle opens to `null` exactly like a tampered blob would.
+        keys: {
+            sealBytes(plain) {
+                const handle = `sealed:${sealedBytes.size}`;
+                sealedBytes.set(handle, Uint8Array.from(plain));
+                return handle;
+            },
+            openBytes: (sealed) => sealedBytes.get(sealed) ?? null
+        },
+        createTicker({ intervalMs, tick }) {
+            recorded.tickers.push({ intervalMs, tick });
+            return { start: () => undefined, stop: () => undefined };
+        },
+        logger: silentLogger
+    };
+}