@williamzujkowski/live-coding-music-mcp 3.0.0 → 4.1.0

package/dist/utils/PatternValidator.js

@@ -47,10 +47,81 @@ export class PatternValidator {
             suggestions
         };
     }
+    /**
+     * The pattern with comments and string bodies blanked out.
+     *
+     * Both are text, not code, and scanning them as code went wrong in
+     * both directions. Measured before this:
+     *
+     *   s("bd*4") // sounds sad :(      -> BLOCKED, "Unclosed '('"
+     *   s("bd*4") // yay :)             -> BLOCKED, "Unexpected closing ')'"
+     *   s("bd*4") // try gain(10) later -> BLOCKED, "Dangerous gain value"
+     *   s(" eval(x)")                   -> BLOCKED, "eval() is not allowed"
+     *
+     * Every one of those is a valid pattern, and `edit_pattern` refuses
+     * the write on a validation error — so a smiley in a comment stopped
+     * the music. #334 taught `checkBalancedQuotes` about comments for
+     * exactly this reason and stopped there; these are the halves it did
+     * not reach (#445).
+     *
+     * Lengths and offsets are preserved, so positions reported to the user
+     * still point at the right character.
+     *
+     * @param pattern - Pattern source
+     * @returns The same string with comment and string contents replaced
+     *   by spaces, delimiters kept
+     */
+    codeOnly(pattern) {
+        const out = pattern.split('');
+        let quote = null;
+        for (let i = 0; i < pattern.length; i++) {
+            const char = pattern[i];
+            if (quote !== null) {
+                // Count the backslash run: an escaped backslash does not escape
+                // the quote that follows it.
+                if (char === '\\') {
+                    out[i] = ' ';
+                    if (i + 1 < pattern.length)
+                        out[i + 1] = ' ';
+                    i++;
+                    continue;
+                }
+                if (char === quote) {
+                    quote = null;
+                    continue;
+                }
+                out[i] = ' ';
+                continue;
+            }
+            if (char === '"' || char === "'" || char === '`') {
+                quote = char;
+                continue;
+            }
+            if (char === '/' && pattern[i + 1] === '/') {
+                const newline = pattern.indexOf('\n', i);
+                const end = newline === -1 ? pattern.length : newline;
+                for (let j = i; j < end; j++)
+                    out[j] = ' ';
+                i = end;
+                continue;
+            }
+            if (char === '/' && pattern[i + 1] === '*') {
+                const close = pattern.indexOf('*/', i + 2);
+                const end = close === -1 ? pattern.length : close + 2;
+                for (let j = i; j < end; j++)
+                    out[j] = ' ';
+                i = end - 1;
+                continue;
+            }
+        }
+        return out.join('');
+    }
     /**
      * Checks if parentheses, brackets, and braces are balanced
      */
-    checkBalancedParentheses(pattern) {
+    checkBalancedParentheses(source) {
+        // Brackets inside a comment or a sample name are not structure.
+        const pattern = this.codeOnly(source);
         const stack = [];
         const pairs = { '(': ')', '[': ']', '{': '}' };
         const opening = Object.keys(pairs);
@@ -89,6 +160,28 @@ export class PatternValidator {
             if (prevChar === '\\') {
                 continue;
             }
+            // Comments are not code, and an apostrophe in one is not a quote.
+            // Without this, `s("bd*4") // don't stop the beat` was reported as
+            // having an unclosed single quote — and writePatternWithValidation
+            // refuses the write outright on a validation error, so a comment
+            // containing an ordinary English contraction blocked the pattern
+            // (#334).
+            if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
+                if (char === '/' && pattern[i + 1] === '/') {
+                    const newline = pattern.indexOf('\n', i);
+                    if (newline === -1)
+                        break;
+                    i = newline;
+                    continue;
+                }
+                if (char === '/' && pattern[i + 1] === '*') {
+                    const end = pattern.indexOf('*/', i + 2);
+                    if (end === -1)
+                        break;
+                    i = end + 1;
+                    continue;
+                }
+            }
             if (char === "'" && !inDoubleQuote && !inBacktick) {
                 inSingleQuote = !inSingleQuote;
             }
@@ -156,28 +249,54 @@ export class PatternValidator {
     /**
      * Checks for potentially dangerous operations
      */
-    checkSafety(pattern) {
+    checkSafety(source) {
         const errors = [];
         const warnings = [];
-        // Check for excessive gain that could damage speakers
-        const gainMatches = pattern.match(/\.gain\(([0-9.]+)\)/g);
-        if (gainMatches) {
-            gainMatches.forEach(match => {
-                const gainValue = parseFloat(match.match(/([0-9.]+)/)?.[0] || '0');
-                if (gainValue > 2) {
-                    warnings.push(`High gain value detected: ${gainValue} - may be too loud`);
-                }
-                if (gainValue > 5) {
-                    errors.push(`Dangerous gain value: ${gainValue} - reduced to 2.0 for safety`);
-                }
-            });
+        // A comment mentioning gain(10), or a sample called " eval(x)", is
+        // not a dangerous pattern — and both used to be refused (#445).
+        const pattern = this.codeOnly(source);
+        // Check for excessive gain that could damage speakers.
+        //
+        // This never fired for any input. The outer match used /g, which
+        // discards capture groups and returns the whole ".gain(9)"; the
+        // inner /([0-9.]+)/ then matched the LEADING DOT of ".gain", and
+        // parseFloat(".") is NaN. Both NaN > 2 and NaN > 5 are false, so
+        // neither branch was reachable — gain(99) validated clean while
+        // CLAUDE.md advertised "prevents dangerous patterns (gain > 2.0)".
+        //
+        // Four tests in PatternValidator.test.ts documented the bug in
+        // detail and asserted the broken behaviour, for coverage. Coverage
+        // measured that these lines ran; nothing measured that they did
+        // anything (#334).
+        //
+        // Now matchAll with the capture, an optional leading dot so bare
+        // `gain(9)` is caught too, whitespace tolerance, and a number
+        // pattern that accepts exponent form.
+        // `\s*` before the paren, and an optional sign.
+        //
+        // One space defeated every rule below: `gain (10)`, `eval ("x")` and
+        // `while ( true )` all passed as safe while their unspaced forms
+        // were errors. #334 fixed this regex's capture group and left the
+        // shape of the match, so the advertised guarantee still did not hold
+        // (#445). `+10` is the same evasion by a different character.
+        const GAIN = /(?:^|[.\s(])gain\s*\(\s*\+?(\d*\.?\d+(?:e[+-]?\d+)?)\s*\)/gi;
+        for (const match of pattern.matchAll(GAIN)) {
+            const gainValue = Number.parseFloat(match[1]);
+            if (!Number.isFinite(gainValue))
+                continue;
+            if (gainValue > 5) {
+                errors.push(`Dangerous gain value: ${String(gainValue)} - above the safe maximum of 2.0`);
+            }
+            else if (gainValue > 2) {
+                warnings.push(`High gain value detected: ${String(gainValue)} - may be too loud`);
+            }
         }
         // Check for potentially infinite loops
-        if (/while\s*\(true\)/.test(pattern) || /for\s*\(.*;;.*\)/.test(pattern)) {
+        if (/while\s*\(\s*true\s*\)/.test(pattern) || /for\s*\(.*;;.*\)/.test(pattern)) {
             errors.push('Potential infinite loop detected');
         }
         // Check for eval or similar dangerous functions
-        if (/\beval\(/.test(pattern) || /Function\(/.test(pattern)) {
+        if (/\beval\s*\(/.test(pattern) || /\bFunction\s*\(/.test(pattern)) {
             errors.push('Use of eval() or Function() is not allowed');
         }
         return {
@@ -204,7 +323,7 @@ export class PatternValidator {
             return match;
         });
         // Add missing quotes around sound patterns
-        fixed = fixed.replace(/s\(([a-z0-9*]+)\)/gi, (match, sound) => {
+        fixed = fixed.replace(/(?<![a-z])s\(([a-z0-9*]+)\)/gi, (match, sound) => {
             if (!sound.includes('"') && !sound.includes("'")) {
                 fixes.push(`Added quotes around sound: ${sound}`);
                 return `s("${sound}")`;

package/dist/utils/SafePath.js

@@ -0,0 +1,112 @@
+/**
+ * SafePath - filename sanitization and directory confinement for file writes
+ *
+ * Every filename this server writes to disk originates in MCP tool
+ * arguments, which are model-generated. Anything that reaches an agent's
+ * context — a web page it summarized, a pattern it loaded, a MIDI file it
+ * imported — can therefore steer a path. Confining writes is not
+ * defense against the user; it is defense against the user's agent being
+ * talked into something.
+ *
+ * `PatternStore.sanitizeFilename()` already did this correctly for saved
+ * patterns. The export paths did not: `MIDIExportService.exportToFile()`
+ * called bare `resolve(filename)` (#224) and `takeScreenshot()` had an
+ * inverted guard that passed any filename *containing* a separator
+ * through unsanitized (#234). This module is the shared implementation so
+ * there is one place to get it right.
+ *
+ * Behaviour is *neutralize, then report* rather than throw: a traversal
+ * attempt is reduced to a safe basename and `wasModified` is set, so the
+ * caller can tell the agent where the file actually landed. Failing
+ * silently would let a model believe it wrote to `../../secrets/x.mid`;
+ * failing loudly on every odd character would make ordinary filenames
+ * unusable. Reporting the real path does both jobs.
+ *
+ * @module utils/SafePath
+ * @nist si-10 "Information input validation"
+ * @nist ac-3 "Access enforcement"
+ */
+import * as path from 'path';
+/** Windows device names, which are unusable as files even on POSIX shares. */
+const RESERVED_NAMES = new Set([
+    'con', 'prn', 'aux', 'nul',
+    'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
+    'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
+]);
+const MAX_STEM_LENGTH = 100;
+/**
+ * Reduces an arbitrary string to a safe filename stem.
+ *
+ * Strips every path component, then replaces anything outside
+ * `[A-Za-z0-9._-]` so separators, null bytes, and shell metacharacters
+ * cannot survive in any encoding.
+ *
+ * @param requested - Caller-supplied name
+ * @param extension - Extension to strip before sanitizing
+ * @returns Safe stem, or empty string if nothing usable remained
+ */
+function sanitizeStem(requested, extension) {
+    // basename first: strips `../`, absolute roots, and Windows separators
+    // once path.basename has normalized them.
+    let stem = path.basename(requested.replace(/\\/g, '/'));
+    if (stem.toLowerCase().endsWith(extension.toLowerCase())) {
+        stem = stem.slice(0, -extension.length);
+    }
+    stem = stem.replace(/[^A-Za-z0-9._-]/g, '_');
+    // A name that is only dots would resolve back to a directory.
+    stem = stem.replace(/^\.+/, '');
+    if (RESERVED_NAMES.has(stem.toLowerCase())) {
+        stem = `_${stem}`;
+    }
+    return stem.slice(0, MAX_STEM_LENGTH);
+}
+/**
+ * Sanitizes a requested filename and confines it to a directory.
+ *
+ * @param requested - Caller-supplied filename, possibly hostile or absent
+ * @param options - Target directory, required extension, and default name
+ * @returns The resolved path plus whether the request had to be altered
+ * @throws {Error} If the result would escape `directory` — a belt-and-braces
+ *   check that should be unreachable after sanitization
+ *
+ * @example
+ * resolveSafeOutputPath('../../etc/passwd', {
+ *   directory: './exports', extension: '.mid', defaultName: 'pattern.mid',
+ * });
+ * // -> { filename: 'passwd.mid', wasModified: true, path: '<cwd>/exports/passwd.mid' }
+ *
+ * @nist si-10 "Information input validation"
+ * @nist ac-3 "Access enforcement"
+ */
+export function resolveSafeOutputPath(requested, options) {
+    const { directory, extension, defaultName } = options;
+    const root = path.resolve(directory);
+    const stem = requested ? sanitizeStem(requested, extension) : '';
+    const filename = stem.length > 0 ? `${stem}${extension}` : defaultName;
+    const resolved = path.resolve(root, filename);
+    // Should be unreachable — sanitizeStem removes every separator — but a
+    // containment check is cheap and this is the last line before a write.
+    if (path.dirname(resolved) !== root) {
+        throw new Error(`Refusing to write outside the export directory: ${String(requested)}`);
+    }
+    const wasModified = requested !== undefined && requested !== filename;
+    return {
+        filename,
+        path: resolved,
+        wasModified,
+        ...(wasModified ? { requested } : {}),
+    };
+}
+/**
+ * Directory exports are written to.
+ *
+ * Defaults to `./exports`, overridable via `exports_dir` in config.json.
+ *
+ * @param configuredDir - Value of `exports_dir`, if set
+ * @returns Absolute export directory path
+ */
+export function resolveExportDirectory(configuredDir) {
+    return path.resolve(typeof configuredDir === 'string' && configuredDir.trim().length > 0
+        ? configuredDir
+        : './exports');
+}

package/dist/utils/ServerConfig.js

@@ -0,0 +1,248 @@
+/**
+ * ServerConfig - parsing and validation for config.json
+ *
+ * `config.json` shipped four keys and the code read two of them.
+ * `strudel_url` and `patterns_dir` were documented in the README as
+ * working and silently ignored (#227), so anyone pointing the server at a
+ * self-hosted Strudel build, or at an existing pattern library, got the
+ * defaults with no warning and went debugging the wrong thing.
+ *
+ * Silently-ignored configuration is worse than none: it actively misleads.
+ * So this module both reads the keys and warns about ones it does not
+ * recognise, which is what stops the next dead key from being silent.
+ *
+ * @module utils/ServerConfig
+ * @nist si-10 "Information input validation"
+ */
+import * as path from 'path';
+/** Default Strudel REPL, used when `strudel_url` is absent or unusable. */
+export const DEFAULT_STRUDEL_URL = 'https://strudel.cc/';
+/** Default on-disk pattern library. */
+export const DEFAULT_PATTERNS_DIR = './patterns';
+/** Every key config.json may contain. Anything else earns a warning. */
+const KNOWN_KEYS = new Set([
+    'headless',
+    'strudel_url',
+    'patterns_dir',
+    'exports_dir',
+    'audio_analysis',
+    'viewport',
+    'block_resources',
+]);
+/**
+ * Default page setup, unchanged from the historic hardcoding (#514).
+ *
+ * Both values exist for headless CI: a pinned viewport keeps
+ * screenshots deterministic, and aborting fonts and images speeds up
+ * page load. In a headed window the same choices degrade the live
+ * editor (fallback-font button metrics, canvases that ignore window
+ * resizes), which is why both are now configurable.
+ */
+export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+/** Resource types the page route aborts by default (#514). */
+export const DEFAULT_BLOCK_RESOURCES = ['image', 'font', 'media'];
+/**
+ * Resource types Playwright may report; `block_resources` values are
+ * validated against this set so a typo earns a warning instead of a
+ * silently unblocked resource class.
+ */
+const KNOWN_RESOURCE_TYPES = new Set([
+    'document',
+    'stylesheet',
+    'image',
+    'media',
+    'font',
+    'script',
+    'texttrack',
+    'xhr',
+    'fetch',
+    'eventsource',
+    'websocket',
+    'manifest',
+    'other',
+]);
+/**
+ * Validates a Strudel URL.
+ *
+ * The value reaches `page.goto()`, so restrict it to http/https rather
+ * than letting `file:`, `javascript:` or similar through.
+ *
+ * @param value - Raw `strudel_url` from config.json
+ * @param warnings - Collector for problems found
+ * @returns A usable URL, falling back to the default
+ * @nist si-10 "Information input validation"
+ */
+function parseStrudelUrl(value, warnings) {
+    if (value === undefined)
+        return DEFAULT_STRUDEL_URL;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        warnings.push(`config.strudel_url must be a non-empty string; using ${DEFAULT_STRUDEL_URL}`);
+        return DEFAULT_STRUDEL_URL;
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        warnings.push(`config.strudel_url is not a valid URL: ${value}; using ${DEFAULT_STRUDEL_URL}`);
+        return DEFAULT_STRUDEL_URL;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        warnings.push(`config.strudel_url must use http or https, got '${parsed.protocol}'; ` +
+            `using ${DEFAULT_STRUDEL_URL}`);
+        return DEFAULT_STRUDEL_URL;
+    }
+    return value;
+}
+/**
+ * Validates a directory path from config.
+ *
+ * @param value - Raw value from config.json
+ * @param key - Key name, for the warning message
+ * @param fallback - Value to use when unusable
+ * @param warnings - Collector for problems found
+ * @returns A usable directory path
+ */
+function parseDirectory(value, key, fallback, warnings) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        warnings.push(`config.${key} must be a non-empty string; using ${fallback}`);
+        return fallback;
+    }
+    return path.resolve(value);
+}
+/**
+ * Parses raw config.json contents into validated settings.
+ *
+ * Never throws: a bad value falls back to its default and records a
+ * warning, so a typo in config.json cannot stop the server from starting.
+ *
+ * @param raw - Parsed contents of config.json, or undefined if absent
+ * @returns Validated config plus any warnings to log
+ *
+ * @example
+ * const config = parseServerConfig({ strudel_url: 'file:///etc/passwd' });
+ * // -> strudelUrl: 'https://strudel.cc/', warnings: ['...must use http or https...']
+ */
+/** Keys `audio_analysis` may contain. Anything else earns a warning. */
+const KNOWN_AUDIO_KEYS = new Set(['fft_size', 'smoothing']);
+/**
+ * Parses the `audio_analysis` block, saying so when it cannot.
+ *
+ * Three ways this used to go wrong in silence, all measured:
+ *
+ *   audio_analysis: "enabled"      -> undefined, indistinguishable from
+ *                                     leaving the block out entirely
+ *   audio_analysis: []             -> {} — an array passes a bare
+ *                                     `typeof === 'object'` test
+ *   audio_analysis: {fftSize: ...} -> {} — the natural camelCase
+ *                                     spelling of `fft_size`, dropped
+ *
+ * The last is the sharpest: the same typo one level up IS warned about
+ * by the unknown-key loop above, so the file was strict about its own
+ * keys and silent about the nested ones (#442).
+ */
+function parseAudioAnalysis(raw, warnings) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        warnings.push('config.audio_analysis must be an object with fft_size and/or smoothing; ignoring it');
+        return undefined;
+    }
+    const audio = raw;
+    for (const key of Object.keys(audio)) {
+        if (!KNOWN_AUDIO_KEYS.has(key)) {
+            warnings.push(`Unknown config key 'audio_analysis.${key}' — it will be ignored. ` +
+                `Known keys: ${[...KNOWN_AUDIO_KEYS].join(', ')}`);
+        }
+    }
+    if (audio.fft_size !== undefined && typeof audio.fft_size !== 'number') {
+        warnings.push('config.audio_analysis.fft_size must be a number; ignoring it');
+    }
+    if (audio.smoothing !== undefined && typeof audio.smoothing !== 'number') {
+        warnings.push('config.audio_analysis.smoothing must be a number; ignoring it');
+    }
+    return {
+        fftSize: typeof audio.fft_size === 'number' ? audio.fft_size : undefined,
+        smoothing: typeof audio.smoothing === 'number' ? audio.smoothing : undefined,
+    };
+}
+/**
+ * Parses the `viewport` block (#514).
+ *
+ * `null` is meaningful, not missing: Playwright treats a null viewport
+ * as "use the real window size", which is what makes window resizes
+ * reach the page. A malformed value falls back to the pinned default
+ * rather than to null, so a typo cannot silently unpin the layout in
+ * headless runs.
+ */
+function parseViewport(raw, warnings) {
+    if (raw === undefined)
+        return DEFAULT_VIEWPORT;
+    if (raw === null)
+        return null;
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        const vp = raw;
+        if (typeof vp.width === 'number' &&
+            typeof vp.height === 'number' &&
+            Number.isFinite(vp.width) &&
+            Number.isFinite(vp.height) &&
+            vp.width > 0 &&
+            vp.height > 0) {
+            return { width: vp.width, height: vp.height };
+        }
+    }
+    warnings.push('config.viewport must be null or an object with positive numeric width and height; ' +
+        `using ${DEFAULT_VIEWPORT.width}x${DEFAULT_VIEWPORT.height}`);
+    return DEFAULT_VIEWPORT;
+}
+/**
+ * Parses the `block_resources` array (#514).
+ *
+ * An empty array is valid and means "abort nothing" — the live-coding
+ * recommendation is `["media"]`, keeping large audio fetches out while
+ * letting fonts and images render.
+ */
+function parseBlockResources(raw, warnings) {
+    if (raw === undefined)
+        return [...DEFAULT_BLOCK_RESOURCES];
+    const valid = Array.isArray(raw) &&
+        raw.every((t) => typeof t === 'string' && KNOWN_RESOURCE_TYPES.has(t));
+    if (valid)
+        return [...raw];
+    warnings.push('config.block_resources must be an array of Playwright resource types ' +
+        `(${[...KNOWN_RESOURCE_TYPES].join(', ')}); using ` +
+        `[${DEFAULT_BLOCK_RESOURCES.map((t) => `'${t}'`).join(', ')}]`);
+    return [...DEFAULT_BLOCK_RESOURCES];
+}
+export function parseServerConfig(raw) {
+    const warnings = [];
+    const obj = raw !== null && typeof raw === 'object' ? raw : {};
+    if (raw !== undefined && (raw === null || typeof raw !== 'object' || Array.isArray(raw))) {
+        warnings.push('config.json must contain a JSON object; using defaults');
+    }
+    // A key nothing reads is how #227 happened. Say so rather than ignore it.
+    for (const key of Object.keys(obj)) {
+        if (!KNOWN_KEYS.has(key)) {
+            warnings.push(`Unknown config key '${key}' — it will be ignored. ` +
+                `Known keys: ${[...KNOWN_KEYS].join(', ')}`);
+        }
+    }
+    if (obj.headless !== undefined && typeof obj.headless !== 'boolean') {
+        warnings.push(`config.headless must be a boolean; using false`);
+    }
+    const audioAnalysis = parseAudioAnalysis(obj.audio_analysis, warnings);
+    return {
+        headless: obj.headless === true,
+        strudelUrl: parseStrudelUrl(obj.strudel_url, warnings),
+        patternsDir: parseDirectory(obj.patterns_dir, 'patterns_dir', DEFAULT_PATTERNS_DIR, warnings),
+        exportsDir: obj.exports_dir === undefined
+            ? undefined
+            : parseDirectory(obj.exports_dir, 'exports_dir', './exports', warnings),
+        audioAnalysis,
+        viewport: parseViewport(obj.viewport, warnings),
+        blockResources: parseBlockResources(obj.block_resources, warnings),
+        warnings,
+    };
+}

package/dist/utils/TableLookup.js

@@ -0,0 +1,41 @@
+/**
+ * Safe lookup in a plain-object table keyed by caller-supplied text.
+ *
+ * `TABLE[key] || fallback` returns an inherited value when `key` is
+ * 'constructor', '__proto__', 'toString' and friends — those are
+ * neither falsy nor nullish, so neither `||` nor `??` fires, and the
+ * inherited value flows on as if it were data.
+ *
+ * That bug has been found eight separate times in this codebase, one at
+ * a time, with symptoms ranging from a TypeError that failed a whole
+ * MIDI export (#308) to `s("bd*4").slow(NaN).lpf(NaN)` written into the
+ * editor and reported as success (#308) to wrong musical intervals
+ * (#318). Finding the ninth by hand is not a plan.
+ *
+ * @param table - A plain object literal used as a lookup table
+ * @param key - Caller-supplied key
+ * @param fallback - Value to use when the key is not an own property
+ * @returns The table's own value for `key`, or `fallback`
+ * @example
+ * lookup(FILLS, style, FILLS.techno);
+ * @nist si-10 "Information input validation"
+ */
+export function lookup(table, key, fallback) {
+    if (typeof key !== 'string')
+        return fallback;
+    return Object.hasOwn(table, key) ? table[key] : fallback;
+}
+/**
+ * As `lookup`, but with no fallback — returns undefined for a key the
+ * table does not own, so the caller can distinguish "absent" from a
+ * legitimately falsy value.
+ *
+ * @param table - A plain object literal used as a lookup table
+ * @param key - Caller-supplied key
+ * @returns The table's own value for `key`, or undefined
+ */
+export function lookupOrUndefined(table, key) {
+    if (typeof key !== 'string')
+        return undefined;
+    return Object.hasOwn(table, key) ? table[key] : undefined;
+}