@matatbread/matbot-core 0.4.9 → 0.4.10

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.9",
+  "version": "0.4.10",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.9"
+    "@matatbread/matbot-plugin-api": "^0.4.10"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/config/loader.ts

@@ -14,6 +14,13 @@ export interface MatbotConfig {
   /** Install-default boot identity. The lowest-precedence source for the entry's principal
    *  (a `--principal` flag or `MATBOT_PRINCIPAL` env override it); absent ⇒ the system principal. */
   principal?:        Principal;
+  /**
+   * Install-supplied floor for plugin settings, keyed by plugin NAME (the settings namespace), read
+   * by {@link installSettingsDefaults}. Read-only: matbot never writes it back, so a default cannot
+   * be destroyed by a plugin or provider update, and it applies to every principal because it is
+   * config rather than data. A stored value always wins; `delete` reverts to the default here.
+   */
+  defaultSettings?:  ReadonlyMap<string, Readonly<Record<string, unknown>>>;
 }
 
 function asString(v: YamlValue | undefined, label: string): string {
@@ -104,6 +111,18 @@ export function parseConfig(
     }
   }
 
+  // Keyed by plugin name, not by the specifier written in `plugins:` — the name IS the settings
+  // namespace, and the same plugin can be reached by several specifiers (a local path, the package
+  // name, a version range). A key naming no loaded plugin is warned about at boot by the host: it is
+  // otherwise the one silent failure mode here, and reads as "I set the default and nothing happened".
+  const defaultSettingsRaw = doc['default_settings'];
+  const defaultSettings    = new Map<string, Readonly<Record<string, unknown>>>();
+  if (defaultSettingsRaw !== undefined && defaultSettingsRaw !== null) {
+    for (const [name, raw] of Object.entries(asRecord(defaultSettingsRaw, 'default_settings'))) {
+      defaultSettings.set(name, { ...asRecord(raw, `default_settings.${name}`) });
+    }
+  }
+
   const prompt           = typeof doc['prompt']            === 'string' ? doc['prompt']            : undefined;
   const ephemeral        = doc['ephemeral'] === true ? true : undefined;
   const defaultProvider  = typeof doc['default_provider'] === 'string' ? doc['default_provider']  : undefined;
@@ -116,6 +135,7 @@ export function parseConfig(
     ...(ephemeral        !== undefined ? { ephemeral        } : {}),
     ...(defaultProvider  !== undefined ? { defaultProvider  } : {}),
     ...(principal        !== undefined ? { principal        } : {}),
+    ...(defaultSettings.size > 0       ? { defaultSettings  } : {}),
   };
 }
 

package/src/config/yaml.ts

@@ -3,14 +3,27 @@
  *
  * Supports:
  *   - Nested block mappings (key: value / key: followed by indented block)
- *   - Block sequences (- item)
+ *   - Block sequences (- item), including an item whose value is an indented block under a bare `-`
  *   - Scalar types: string, number, boolean, null
- *   - Quoted strings (single and double)
+ *   - Quoted strings (single and double), as values and as keys
  *   - Comments (# ...)
  *
  * Does NOT support anchors, aliases, flow syntax, or ${NAME} expansion.
  * ${NAME} placeholders are left intact for the Vault to resolve.
  * Supports literal block scalars (|) and folded block scalars (>).
+ *
+ * Deliberately NOT supported: YAML's compact mapping in a sequence entry (`- key: value` with the
+ * mapping starting on the dash's own line). It is legal YAML, but telling it from a plugin specifier
+ * needs the spec's rule that a key separator is a colon followed by SPACE or end-of-line — without
+ * which `- https://host/plugin.ts` parses as the key `https`. This tokenizer works on the first colon
+ * in a line, so the compact form is rejected (below) rather than guessed at.
+ *
+ * An unparseable construct THROWS naming the line. It used to `break` the enclosing loop, which
+ * returned what had been read so far and left the rest of the document silently discarded — a stray
+ * `-` in `plugins:` dropped every plugin after it and every top-level section below it, including
+ * `providers:`, with no error. A config parser that returns a subset of the file the user wrote is
+ * worse than one that fails: the failure is one message, the subset is an install that boots and
+ * behaves as though half its configuration were never written.
  */
 
 type YamlScalar = string | number | boolean | null;
@@ -20,24 +33,34 @@ export type YamlMap   = { [key: string]: YamlValue };
 interface Token {
   indent: number;
   raw:    string;
+  line:   number;
 }
 
 function tokenize(text: string): Token[] {
   const tokens: Token[] = [];
-  for (const line of text.split('\n')) {
-    const stripped = line.replace(/#.*$/, '').trimEnd();
+  const lines = text.split('\n');
+  for (let n = 0; n < lines.length; n++) {
+    const stripped = lines[n]!.replace(/#.*$/, '').trimEnd();
     if (stripped.trim() === '') continue;
     const indent = stripped.length - stripped.trimStart().length;
-    tokens.push({ indent, raw: stripped.trimStart() });
+    tokens.push({ indent, raw: stripped.trimStart(), line: n + 1 });
   }
   return tokens;
 }
 
+function fail(tok: Token, what: string): never {
+  throw new Error(`Config: could not parse line ${tok.line} ("${tok.raw}") — ${what}`);
+}
+
+function unquote(raw: string): string {
+  return (raw.length > 1 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))))
+    ? raw.slice(1, -1)
+    : raw;
+}
+
 function parseScalar(raw: string): YamlScalar {
-  if ((raw.startsWith('"') && raw.endsWith('"')) ||
-      (raw.startsWith("'") && raw.endsWith("'"))) {
-    return raw.slice(1, -1);
-  }
+  const unquoted = unquote(raw);
+  if (unquoted !== raw) return unquoted;
 
   if (raw === 'null' || raw === '~') return null;
   if (raw === 'true')  return true;
@@ -49,29 +72,44 @@ function parseScalar(raw: string): YamlScalar {
   return raw;
 }
 
+// A sequence item is `- value`, or a bare `-` whose value is the block indented beneath it.
+function isSeqItem(raw: string): boolean {
+  return raw === '-' || raw.startsWith('- ');
+}
+
 function parse(tokens: Token[], pos: number, baseIndent: number): { value: YamlValue; next: number } {
   if (pos >= tokens.length) return { value: null, next: pos };
 
   const first = tokens[pos]!;
 
-  if (first.raw.startsWith('- ')) {
+  if (isSeqItem(first.raw)) {
     const items: YamlValue[] = [];
     let i = pos;
     while (i < tokens.length) {
       const tok = tokens[i]!;
       if (tok.indent < first.indent) break;
-      if (tok.indent === first.indent && tok.raw.startsWith('- ')) {
-        const itemRaw = tok.raw.slice(2).trim();
-        if (itemRaw === '') {
+      // A sibling key at the sequence's own indent ends it — the flush-left style, where `plugins:`
+      // and its `-` items share a column, is legal and common.
+      if (tok.indent === first.indent && !isSeqItem(tok.raw)) break;
+      if (tok.indent > first.indent) {
+        fail(tok, 'it is indented further than the sequence item above it. A mapping inside a ' +
+                  'sequence entry must start on its own line, under a bare "-".');
+      }
+      const itemRaw = tok.raw === '-' ? '' : tok.raw.slice(2).trim();
+      if (itemRaw === '') {
+        // `-` alone: its value is the block indented beneath it, or null if there is no such block.
+        const next = tokens[i + 1];
+        if (next === undefined || next.indent <= tok.indent) {
+          items.push(null);
+          i++;
+        } else {
           const sub = parse(tokens, i + 1, tok.indent + 2);
           items.push(sub.value);
           i = sub.next;
-        } else {
-          items.push(parseScalar(itemRaw));
-          i++;
         }
       } else {
-        break;
+        items.push(parseScalar(itemRaw));
+        i++;
       }
     }
     return { value: items, next: i };
@@ -83,10 +121,10 @@ function parse(tokens: Token[], pos: number, baseIndent: number): { value: YamlV
     while (i < tokens.length) {
       const tok = tokens[i]!;
       if (tok.indent < baseIndent) break;
-      if (!tok.raw.includes(':')) break;
+      if (!tok.raw.includes(':')) fail(tok, 'a mapping was expected here (no "key:").');
 
       const colonIdx = tok.raw.indexOf(':');
-      const key      = tok.raw.slice(0, colonIdx).trim();
+      const key      = unquote(tok.raw.slice(0, colonIdx).trim());
       const rest     = tok.raw.slice(colonIdx + 1).trimStart();
 
       if (rest === '|' || rest === '>') {

package/src/settings.ts

@@ -22,6 +22,29 @@ export function slugSettingsNamespace(name: string): string {
   return name.replace(/[^\w-]+/g, '_');
 }
 
+/**
+ * The install's config-supplied floor for plugin settings, keyed by plugin name (the settings
+ * namespace). Installed once by the host at boot from `default_settings:` in matbot.yaml (node) or
+ * `BrowserConfig.defaultSettings` (browser); empty otherwise.
+ *
+ * Module state consulted INSIDE {@link makePluginSettings}, rather than a parameter it takes, because
+ * a parameter is a thing a call site forgets with no error and no symptom — and there is already a
+ * call site that would: `plugins/browser` builds its own facade over a concrete backend on purpose,
+ * to pin its plugin list to local storage across a StorageBackend swap. A default it silently didn't
+ * see would be indistinguishable from one the user never wrote.
+ */
+let installDefaults: ReadonlyMap<string, Readonly<Record<string, unknown>>> = new Map();
+
+/** Host boot assembly: install the read-only defaults. Call before any plugin loads. */
+export function installSettingsDefaults(byPlugin: ReadonlyMap<string, Readonly<Record<string, unknown>>> | undefined): void {
+  installDefaults = byPlugin ?? new Map();
+}
+
+/** The plugin names the install supplies defaults for — the host checks these against what loaded. */
+export function settingsDefaultNamespaces(): readonly string[] {
+  return [...installDefaults.keys()];
+}
+
 /**
  * Build a PluginSettings facade over the shared settings store, scoped to one document id.
  *
@@ -30,6 +53,12 @@ export function slugSettingsNamespace(name: string): string {
  * upgrade with `set` instead of `cas` — a three-site migration paid for on every `settings.get()` by
  * every plugin, forever. Dropped at 0.4.0: an unrecognised document is treated as absent, so a flat one
  * would be re-created on first write rather than read. Nothing in the wild is still flat.
+ *
+ * Reads are layered over {@link installDefaults}: a stored key wins, else the install's default, else
+ * undefined (and then whatever the plugin's own code defaults to — so config beats code). Writes are
+ * NOT layered: `update` reads the stored document only, so setting one key never persists another
+ * key's default. Seeding on write would make a later config edit work or not work depending on
+ * unrelated write history, which is unexplainable to whoever edits the yaml.
  */
 export function makePluginSettings(store: Store<SettingsDoc>, namespace: string): PluginSettings {
   const id = slugSettingsNamespace(namespace);
@@ -55,7 +84,11 @@ export function makePluginSettings(store: Store<SettingsDoc>, namespace: string)
 
   return {
     async get<T>(key: string): Promise<T | undefined> {
-      return (await getDoc())?.data[key] as T | undefined;
+      const doc = await getDoc();
+      // `in`, not a truthiness or undefined test: a stored null is an override the plugin gets to
+      // interpret, and `delete` — not writing null — is how a caller reverts to the install default.
+      if (doc !== null && key in doc.data) return doc.data[key] as T | undefined;
+      return installDefaults.get(namespace)?.[key] as T | undefined;
     },
     set<T>(key: string, value: T): Promise<void> {
       return update(data => ({ ...data, [key]: value as unknown }));