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/README.md

@@ -127,6 +127,39 @@ Your plugin runs in an **isolated child process**. `ctx` is the only way to reac
 TREK, and it grants exactly the permissions your `trek-plugin.json` declares — an
 ungranted call throws `PERMISSION_DENIED`.
 
+## Settings
+
+Declare settings in `trek-plugin.json`; TREK renders the form, you write no settings UI.
+
+```json
+"settings": [
+  { "key": "api_url", "label": "API URL", "default": "https://api.example", "required": true },
+  { "key": "retries", "label": "Retries", "input_type": "number", "default": 3 },
+  { "key": "api_key", "label": "API key", "scope": "user", "secret": true, "required": true },
+  { "key": "region", "label": "Region", "input_type": "select",
+    "options": [{ "value": "eu", "label": "EU" }, { "value": "us", "label": "US" }], "default": "eu" }
+]
+```
+
+| Attribute | Meaning |
+|---|---|
+| `key` | Identifier (`^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$`). |
+| `scope` | `instance` (default) — set once by the admin, arrives in `ctx.config`. `user` — per user, read with `await ctx.settings.get(key)`. |
+| `input_type` | `text` (default), `password`, `number`, `checkbox`, `select` (with `options`). |
+| `default` | The field's value wherever nobody set one. The form pre-fills it **and the runtime resolves it** — `ctx.config.api_url` / `ctx.settings.get('region')` return it until someone saves something else — so a plugin with sensible defaults works before anyone opens the form. Satisfies `required`. Not allowed on a `secret` (the manifest is public); must be a boolean on a `checkbox` and one of the `options` when declared. `trek-plugin dev` seeds its fixtures from these too. |
+| `required` | Enforced: the form refuses Save while the field is blank, and the host answers `400 { error: 'Missing required setting "<key>"' }` if a save reaches it anyway. A `checkbox` is exempt (that would be consent, not a setting). A required `scope:'user'` field also gates whether a notification channel dispatches to that user. |
+| `secret` | Encrypted at rest, decrypted only into the server-side `ctx.config` / `ctx.settings`, masked to the browser, never sent to the iframe. |
+| `label`, `placeholder`, `hint` | Form text. |
+| `options` | `[{ "value", "label" }]` for a `select` (bare strings are accepted and coerced). |
+| `oauth` | Descriptive metadata only — for a host-brokered flow see the OAuth broker below. |
+
+Any other attribute is **silently dropped at install**. `trek-plugin validate` warns on
+one (`manifest.settings-known-keys`) so a typo like `"defalt"` doesn't quietly do nothing.
+
+`ctx.config` is frozen at activation — the host re-spawns the plugin when the admin
+saves. `ctx.settings.get()` is live per call and returns `undefined` in a userless
+context (`onLoad`, jobs, scheduler) — fall back to `ctx.config` there.
+
 ## Test without a running TREK
 
 ```js
@@ -287,6 +320,7 @@ npx trek-plugin-sdk publish --repo you/repo --tag v1.1.0 --sign   # or just answ
 - `definePlugin(def)` + all the plugin types (`PluginContext`, `PluginRoute`, `PluginJob`, `PhotoProvider`, `CalendarSource`).
 - `PLUGIN_API_VERSION` — embed as `apiVersion` in your manifest.
 - `validateManifest(json)` — the manifest rules the server loader uses.
+- `settingDefaults(manifest, scope)` — the `default`s of one settings scope, keyed by field: what the host resolves for an unset field, and what `dev` seeds `ctx.config` / `ctx.settings` with. Spread it under your own fixtures when calling `createMockHost` to mirror the host. `SETTING_FIELD_KEYS` is the attribute list the host stores.
 - `createMockHost(opts)` (from `trek-plugin-sdk/testing`).
 - `TREK_UI_CSS`, `TREK_THEME_JS`, `TREK_UI_MARKER`, `injectTrekUi(html)` — the design kit, for authors who inline it themselves (a bundler, a custom build). Most plugins just use the `<!-- trek:ui -->` marker instead.
 

plugin-sdk/src/cli/checks/offline.ts

@@ -11,7 +11,7 @@
  */
 import { createHash } from 'node:crypto';
 import path from 'node:path';
-import { validateManifest, isSatisfiableRange, isUnboundedRange, KNOWN_ADDONS } from '../../manifest.js';
+import { validateManifest, isSatisfiableRange, isUnboundedRange, KNOWN_ADDONS, SETTING_FIELD_KEYS } from '../../manifest.js';
 // The hosts a plugin can ACTUALLY reach. See `code.egress-reachable` for why this is the
 // only list that counts — and permissions.ts for why dev's egress guard uses the same one.
 import { grantedHosts } from '../../permissions.js';
@@ -216,6 +216,33 @@ const manifestAddonsKnown: OfflineCheck = {
   },
 };
 
+const manifestSettingsKnownKeys: OfflineCheck = {
+  id: 'manifest.settings-known-keys',
+  stage: 'manifest',
+  depth: 'offline',
+  severity: 'warn',
+  title: 'settings fields carry only attributes the SDK knows',
+  run: (c) => {
+    const settings = c.manifest?.settings;
+    const fields = (Array.isArray(settings) ? settings : []).filter(
+      (s): s is Record<string, unknown> => !!s && typeof s === 'object',
+    );
+    if (!fields.length) return skip();
+    const unknown: string[] = [];
+    for (const f of fields) {
+      for (const k of Object.keys(f)) {
+        if (!(SETTING_FIELD_KEYS as readonly string[]).includes(k)) unknown.push(`${String(f.key ?? '?')}.${k}`);
+      }
+    }
+    return unknown.length
+      ? fail(
+          unknown.join(', '),
+          `TREK stores only the attributes it knows and SILENTLY DROPS the rest at install — a typo ("defalt")\nor an attribute from a newer SDK simply does nothing, with no diagnostic anywhere.\nKnown: ${SETTING_FIELD_KEYS.join(', ')}.`,
+        )
+      : pass(`${fields.length} field(s) clean`);
+  },
+};
+
 const manifestNoEmoji: OfflineCheck = {
   id: 'manifest.no-emoji',
   stage: 'manifest',
@@ -592,6 +619,7 @@ export const OFFLINE_CHECKS: OfflineCheck[] = [
   manifestTrekRange,
   manifestIdMatchesDir,
   manifestAddonsKnown,
+  manifestSettingsKnownKeys,
   manifestNoEmoji,
   codeServerEntry,
   codeEgressReachable,

plugin-sdk/src/cli/dev.ts

@@ -18,6 +18,7 @@
  * Dependency-free: node:http + node:sqlite (when present) + built-ins.
  */
 import fs from 'node:fs';
+import { settingDefaults } from '../manifest.js';
 import path from 'node:path';
 import http from 'node:http';
 import { createRequire } from 'node:module';
@@ -292,6 +293,14 @@ function loadFixtures(dir: string): Fixtures {
 }
 
 /** Watch a directory tree with per-dir fs.watch (works on every platform, unlike recursive). */
+function withManifestDefaults(fx: Fixtures, manifest: unknown): Fixtures {
+  return {
+    ...fx,
+    config: { ...settingDefaults(manifest, 'instance'), ...(fx.config ?? {}) },
+    userSettings: { ...settingDefaults(manifest, 'user'), ...(fx.userSettings ?? {}) },
+  };
+}
+
 function watchTree(root: string, onChange: () => void): void {
   const skip = new Set(['node_modules', '.git', '.trek-dev']);
   const watch = (d: string) => {
@@ -310,7 +319,10 @@ export async function runDev(dir: string, opts: { port?: number } = {}): Promise
   const manifest = readJsonFile<Record<string, unknown>>(manifestPath);
   const id = String(manifest.id);
   const grants = new Set(Array.isArray(manifest.permissions) ? (manifest.permissions as string[]) : []);
-  const fx = loadFixtures(abs);
+  // Manifest `default`s are the host's effective value for anything unset, so seed the
+  // fixtures with them (a fixture value still wins) — otherwise a plugin relying on its
+  // defaults would read undefined here and only here.
+  const fx = withManifestDefaults(loadFixtures(abs), manifest);
   const { db, note: dbNote, close: closeDb } = createDevDb(path.join(abs, '.trek-dev', 'db.sqlite'));
   const broadcasts: unknown[] = [];
   installSdkInjection();

plugin-sdk/src/index.ts

@@ -30,10 +30,14 @@ export interface User { id: number; username?: string; display_name?: string | n
  * A legitimate plugin never hits the generous burst. See README § Runtime limits. */
 export interface PluginContext {
   readonly id: string;
+  /** Your `scope:'instance'` settings as the admin saved them, secrets decrypted, frozen
+   * at activation (a save re-spawns you). A field nobody set resolves to its manifest
+   * `default` — only a field with neither is absent. */
   readonly config: Readonly<Record<string, unknown>>;
   /** The ACTING USER's own value for one of this plugin's `scope:'user'` settings fields
-   * (decrypted host-side). Undefined for an unset value or a userless context (job/onLoad)
-   * — fall back to `config` (the admin-owned instance settings) there. */
+   * (decrypted host-side), or the field's manifest `default` when they never set it.
+   * Undefined for a field with neither, and in a userless context (job/onLoad) — fall
+   * back to `config` (the admin-owned instance settings) there. */
   settings: {
     get(key: string): Promise<unknown>;
   };
@@ -849,6 +853,8 @@ export function definePlugin(def: PluginDefinition): PluginDefinition {
 
 export {
   validateManifest,
+  settingDefaults,
+  SETTING_FIELD_KEYS,
   CHANNEL_EVENTS,
   type PluginManifest,
   type NormalizedManifest,

plugin-sdk/src/manifest.ts

@@ -21,6 +21,39 @@ export interface ManifestSettingField {
   scope?: 'instance' | 'user';
   options?: Array<string | number | { value: string | number; label?: string }>;
   oauth?: { initPath?: string; callbackPath?: string };
+  /** The field's value wherever nobody set one: the settings form pre-fills it AND the
+   * runtime resolves it (`ctx.config` / `ctx.settings.get()`), so the plugin works before
+   * anyone opens the form. Satisfies `required`. Not accepted on a `secret` field (the
+   * manifest is public); must be a boolean for a `checkbox` and one of `options` when
+   * those are declared. */
+  default?: string | number | boolean;
+}
+
+/** Every attribute a settings-field object may carry — the host silently drops anything else.
+ *  Mirrors `SETTING_FIELD_KEYS` in the host's install/manifest.ts (parity-tested in
+ *  test/permissions-parity.test.ts); change both together. */
+export const SETTING_FIELD_KEYS = [
+  'key', 'label', 'input_type', 'placeholder', 'hint', 'required', 'secret', 'scope', 'options', 'oauth', 'default',
+] as const;
+/**
+ * The `default`s a manifest declares for one settings scope, keyed by field — the
+ * host's effective value for any field nobody set. `trek-plugin dev` seeds `ctx.config`
+ * (instance) and `ctx.settings.get()` (user) from this so dev matches production.
+ * Secrets are skipped even if present (the host never resolves a secret from a default).
+ */
+export function settingDefaults(manifest: unknown, scope: 'instance' | 'user'): Record<string, string | number | boolean> {
+  const settings = (manifest as { settings?: unknown } | null)?.settings;
+  const out: Record<string, string | number | boolean> = {};
+  if (!Array.isArray(settings)) return out;
+  for (const s of settings as unknown[]) {
+    if (!s || typeof s !== 'object') continue;
+    const f = s as Record<string, unknown>;
+    if (typeof f.key !== 'string' || !f.key || f.secret === true) continue;
+    if ((f.scope === 'user' ? 'user' : 'instance') !== scope) continue;
+    const d = f.default;
+    if (typeof d === 'string' || typeof d === 'number' || typeof d === 'boolean') out[f.key] = d;
+  }
+  return out;
 }
 export interface ManifestAction {
   key: string;
@@ -380,6 +413,23 @@ export function validateManifest(raw: unknown): ValidationResult {
           }
         }
       }
+      if (s.default !== undefined) {
+        const d = s.default;
+        if (typeof d !== 'string' && typeof d !== 'number' && typeof d !== 'boolean') {
+          errors.push(`settings["${key}"].default must be a string, number or boolean`);
+        } else if (s.secret === true) {
+          errors.push(`settings["${key}"].default is not allowed on a secret field (the manifest is public — it would ship the secret in plaintext)`);
+        } else if (s.input_type === 'checkbox' && typeof d !== 'boolean') {
+          errors.push(`settings["${key}"].default must be a boolean for a checkbox field`);
+        } else if (Array.isArray(s.options) && s.options.length > 0) {
+          const values = (s.options as unknown[]).map((o) =>
+            o && typeof o === 'object' ? String((o as { value?: unknown }).value) : String(o),
+          );
+          if (!values.includes(String(d))) {
+            errors.push(`settings["${key}"].default must be one of the declared options (${values.join(', ')})`);
+          }
+        }
+      }
     }
   }
   // Settings-page action buttons ("Test connection"). Keys share the settings-key rules.

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' });
+  });
+});