Fix/sdk default (#2199)

* feat(plugin-sdk): settings-field default + unknown-attribute warning

* feat(shared): default on the plugin settings-field contract

* feat(server): persist and serve plugin settings-field defaults

* feat(client): pre-fill plugin settings defaults in the admin and user forms

* feat(server): enforce required plugin settings on both save paths

* feat(client): block plugin-settings save on an empty required field

* feat(server): resolve plugin settings defaults at runtime

A settings-field `default` was stored and served to the form but never
reached the plugin: the child's init envelope, `ctx.settings.get()`, the
channel dispatch's readAll and the OAuth provider config all read the
stored blob only. Fold `stored ?? default` in on every path that hands
config to a plugin (settings-defaults.ts), and let a default satisfy
`required` on both save gates — refusing a save the runtime would have
accepted was a contradiction.

Also: one `isFilled` rule shared by the save gate and `hasRequired`
(checkbox exempt, whitespace empty); the install parser drops a
non-boolean checkbox default or a select default outside its options,
matching what the SDK already refuses; export SETTING_FIELD_KEYS so the
SDK's mirror can be parity-tested.

* feat(client): share the plugin settings form rules across all three forms

The mobile user settings screen was a third consumer of the fields/config
contract that never got `default` pre-fill or the required check, and
the seed/patch loops lived in five hand copies. Extract
seedSettingsValues / findMissingRequired / settingsPatch into one module
and use it from the admin instance form, the desktop user tab and the
mobile screen. The user forms now surface a 4xx `{ error }` from the
server (the required-field refusal) instead of the generic toast.

* feat(plugin-sdk): seed dev fixtures from manifest defaults

`trek-plugin dev` handed the plugin only the fixture values, so a plugin
relying on its manifest defaults read undefined in dev and only in dev.
Seed ctx.config / ctx.settings from the declared defaults (a fixture
value still wins) via a new exported settingDefaults(manifest, scope).
SETTING_FIELD_KEYS is now parity-tested against the host's list.

* docs(plugins): document settings defaults as runtime fallbacks

A `default` is the field's effective value wherever nobody set one, not
just a form pre-fill; `required` is enforced on both ends; unknown
attributes are dropped at install and warned on by validate. Add a
Settings section with the attribute table to the SDK README and update
the ctx type comments, the shared schema, and the wiki guide.

* add missing exports

plugin-sdk/test/checks.test.ts

@@ -230,6 +230,20 @@ describe('what blocks what', () => {
   });
 });
 
+describe('manifest.settings-known-keys', () => {
+  it('warns on an attribute the SDK does not know', () => {
+    const r = runOffline(ctx({ manifest: { ...GOOD_MANIFEST, settings: [{ key: 'api_url', defalt: 'oops' }] } }));
+    expect(warned(r, 'manifest.settings-known-keys')).toBe(true);
+    const outcome = r.outcomes.find((o) => o.id === 'manifest.settings-known-keys');
+    expect(outcome?.detail).toMatch(/api_url\.defalt/);
+  });
+
+  it('passes when every attribute is known', () => {
+    const r = runOffline(ctx({ manifest: { ...GOOD_MANIFEST, settings: [{ key: 'api_url', default: 'https://x' }] } }));
+    expect(warned(r, 'manifest.settings-known-keys')).toBe(false);
+  });
+});
+
 describe('README helpers mirror the registry exactly', () => {
   it('strips headings, tables, links, images and code fences before measuring prose', () => {
     const md = '# Title\n\n![x](y.png)\n\n| a | b |\n|---|---|\n\n```js\nconst x = 1;\n```\n\n[link](u)\n';

plugin-sdk/test/manifest-settings.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { validateManifest } from '../src/manifest.js';
+import { validateManifest, settingDefaults } from '../src/manifest.js';
 
 const base = () => ({ id: 'my-plugin', name: 'My Plugin', version: '1.0.0', type: 'integration', trek: '>=4.0.0 <5.0.0' });
 const withSetting = (extra: object) => ({ ...base(), settings: [{ key: 'mode', ...extra }] });
@@ -33,3 +33,53 @@ describe('validateManifest settings[].options / settings[].oauth', () => {
     expect(validateManifest(withSetting({ oauth: { initPath: '/oauth/init' } })).ok).toBe(true);
   });
 });
+
+describe('settings default', () => {
+  it('accepts a string/number/boolean default', () => {
+    expect(validateManifest(withSetting({ default: 'https://x' })).ok).toBe(true);
+    expect(validateManifest(withSetting({ default: 42 })).ok).toBe(true);
+    expect(validateManifest(withSetting({ default: true })).ok).toBe(true);
+  });
+  it('carries the default through onto the normalized manifest', () => {
+    const r = validateManifest(withSetting({ default: 'https://x' }));
+    expect(r.manifest?.settings?.[0]?.default).toBe('https://x');
+  });
+  it('rejects an object default', () => {
+    const r = validateManifest(withSetting({ key: 'a', default: { nope: 1 } }));
+    expect(r.errors.join()).toMatch(/settings\["a"\]\.default must be a string, number or boolean/);
+  });
+  it('rejects default on a secret field', () => {
+    const r = validateManifest(withSetting({ key: 'tok', secret: true, default: 'x' }));
+    expect(r.errors.join()).toMatch(/not allowed on a secret field/);
+  });
+  it('rejects a non-boolean default on a checkbox', () => {
+    const r = validateManifest(withSetting({ key: 'on', input_type: 'checkbox', default: 'yes' }));
+    expect(r.errors.join()).toMatch(/must be a boolean/);
+  });
+  it('rejects a default that is not one of the declared options', () => {
+    const r = validateManifest(withSetting({ key: 's', input_type: 'select', options: ['a', 'b'], default: 'c' }));
+    expect(r.errors.join()).toMatch(/one of the declared options/);
+  });
+});
+
+describe('settingDefaults (what `trek-plugin dev` seeds ctx.config / ctx.settings with)', () => {
+  const manifest = () => ({
+    ...base(),
+    settings: [
+      { key: 'api_url', default: 'https://api.example' },
+      { key: 'retries', input_type: 'number', default: 3 },
+      { key: 'region', scope: 'user', default: 'eu' },
+      { key: 'token', secret: true, default: 'never' }, // invalid anyway, but must never leak through
+      { key: 'note' },
+    ],
+  });
+  it('collects the instance-scope defaults (scope omitted = instance)', () => {
+    expect(settingDefaults(manifest(), 'instance')).toEqual({ api_url: 'https://api.example', retries: 3 });
+  });
+  it('collects the user-scope defaults', () => {
+    expect(settingDefaults(manifest(), 'user')).toEqual({ region: 'eu' });
+  });
+  it('is empty for a manifest without settings', () => {
+    expect(settingDefaults(base(), 'instance')).toEqual({});
+  });
+});

plugin-sdk/test/permissions-parity.test.ts

@@ -15,6 +15,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { HOOK_PERMISSION } from '../src/permissions.js';
+import { SETTING_FIELD_KEYS } from '../src/manifest.js';
 import { PLUGIN_SESSION_MAX_KEYS, PLUGIN_SESSION_MAX_KEY_LENGTH, PLUGIN_SESSION_MAX_VALUE_BYTES, EVENT_FAMILIES, EVENT_SNAPSHOT_GRANT, KNOWN_PERMISSIONS } from '../src/index.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -96,3 +97,16 @@ describe.skipIf(!inMonorepo)('core event catalog', () => {
     }
   });
 });
+
+describe.skipIf(!inMonorepo)('settings-field attribute parity', () => {
+  it("SETTING_FIELD_KEYS matches the host's install/manifest.ts", () => {
+    // The `manifest.settings-known-keys` check warns on an attribute the host would
+    // silently drop, so the list must be the host's — compared whole, both ways round.
+    const theirsFile = path.resolve(here, '../../server/src/nest/plugins/install/manifest.ts');
+    const src = fs.readFileSync(theirsFile, 'utf8');
+    const block = src.match(/export const SETTING_FIELD_KEYS = \[([\s\S]*?)\] as const/);
+    expect(block, 'SETTING_FIELD_KEYS not found in install/manifest.ts').toBeTruthy();
+    const theirs = [...block![1].matchAll(/'([^']+)'/g)].map((m) => m[1]);
+    expect([...SETTING_FIELD_KEYS]).toEqual(theirs);
+  });
+});

plugin-sdk/test/sdk.test.ts

@@ -1151,3 +1151,12 @@ describe('validateManifest: the trek range', () => {
     expect(isUnboundedRange('>=3.2.0 <4.0.0')).toBe(false);
   });
 });
+
+describe('settingDefaults is part of the package surface', () => {
+  it('is exported from the index so a plugin test can seed createMockHost like the host does', async () => {
+    const sdk = await import('../src/index.js');
+    const manifest = { settings: [{ key: 'a', default: 1 }, { key: 'u', scope: 'user', default: 'x' }] };
+    expect(sdk.settingDefaults(manifest, 'instance')).toEqual({ a: 1 });
+    expect(sdk.settingDefaults(manifest, 'user')).toEqual({ u: 'x' });
+  });
+});