@jbarket/loomai 0.7.0 → 0.9.0

package/dist/ui/vocab.js

@@ -0,0 +1,360 @@
+/**
+ * The page vocabulary (docs/extensions.md, "The page").
+ *
+ * loom's page is built from these shapes, both loom's own pages and the
+ * installed pieces'. A piece answers `ui --json` (a manifest), `ui page --json`
+ * (a page) and `ui act --json` (an action's result) in this vocabulary. Pieces
+ * send data, never markup: loom renders every block itself and escapes every
+ * string, so a piece can't put HTML or script on loom's page. Anything that
+ * doesn't validate is dropped whole (a piece that sends garbage just isn't
+ * shown), never half-rendered.
+ */
+export const LIMITS = {
+    sections: 10,
+    blocks: 20,
+    items: 200,
+    columns: 12,
+    string: 2000,
+    asks: 10,
+    fields: 30,
+    hidden: 20,
+    options: 50,
+    query: 10,
+    queryValue: 200,
+    path: 200,
+};
+const TONES = new Set(['ok', 'warn', 'bad', 'muted']);
+export const ID = /^[a-z][a-z0-9-]{0,39}$/;
+const NAME = /^[a-z][a-z0-9_-]{0,39}$/;
+export const QUERY_KEY = /^[a-z][a-z0-9_-]{0,31}$/;
+const PATH_CHARS = /^[a-z0-9._~/-]*$/;
+class Invalid extends Error {
+}
+/** loom's own pages a link may name with `loom:`. */
+const CORE_PAGES = /^(|mind|people|people\/[a-z0-9][a-z0-9-]*|memory\/.+)$/;
+/** A page path: `""` (the main page) or lowercase segments, never `..`, never absolute. */
+export function validPath(p) {
+    if (p.length > LIMITS.path || !PATH_CHARS.test(p))
+        return false;
+    if (p === '')
+        return true;
+    if (p.startsWith('/') || p.endsWith('/'))
+        return false;
+    return p.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
+}
+function str(v, what) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return String(v);
+    if (typeof v !== 'string')
+        throw new Invalid(`${what} must be a string`);
+    if (v.length > LIMITS.string)
+        throw new Invalid(`${what} is longer than ${LIMITS.string}`);
+    return v;
+}
+function optStr(v, what) {
+    return v === undefined || v === null ? undefined : str(v, what);
+}
+function bool(v) {
+    return v === undefined ? undefined : v === true;
+}
+function tone(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'string' || !TONES.has(v))
+        throw new Invalid(`tone must be one of ${[...TONES].join(', ')}`);
+    return v;
+}
+function arr(v, what, max) {
+    if (!Array.isArray(v))
+        throw new Invalid(`${what} must be an array`);
+    if (v.length > max)
+        throw new Invalid(`${what} has more than ${max} entries`);
+    return v;
+}
+function obj(v, what) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        throw new Invalid(`${what} must be an object`);
+    return v;
+}
+function name(v, what) {
+    const s = str(v, what);
+    if (!NAME.test(s))
+        throw new Invalid(`${what} ${JSON.stringify(s)} must be lowercase letters, digits, _ and -`);
+    return s;
+}
+/**
+ * A page link: `[loom:]<path>[?<query>]`. Split into the source (loom's own or
+ * this piece's), the path and the query, or null when it isn't valid.
+ */
+export function splitPage(s) {
+    const core = s.startsWith('loom:');
+    const rest = core ? s.slice(5) : s;
+    const q = rest.indexOf('?');
+    const path = q === -1 ? rest : rest.slice(0, q);
+    if (!validPath(path))
+        return null;
+    // Into loom, only loom's own pages: not another piece's, and not login,
+    // logout, actions or the JSON endpoints.
+    if (core && !CORE_PAGES.test(path))
+        return null;
+    const query = {};
+    if (q !== -1) {
+        const params = new URLSearchParams(rest.slice(q + 1));
+        let n = 0;
+        for (const [k, v] of params) {
+            if (!QUERY_KEY.test(k) || v.length > LIMITS.queryValue || ++n > LIMITS.query)
+                return null;
+            query[k] = v;
+        }
+    }
+    return { core, path, query };
+}
+/** A link to a page: this source's path, or `loom:<path>` for one of loom's own, either with an optional query. */
+function page(v, what) {
+    if (v === undefined || v === null)
+        return undefined;
+    const s = str(v, what);
+    if (!splitPage(s))
+        throw new Invalid(`${what} ${JSON.stringify(s)} is not a valid page link`);
+    return s;
+}
+/** Only http(s): no javascript:, data:, or relative tricks. */
+function href(v, what) {
+    if (v === undefined || v === null)
+        return undefined;
+    const s = str(v, what);
+    let url;
+    try {
+        url = new URL(s);
+    }
+    catch {
+        throw new Invalid(`${what} must be an absolute URL`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        throw new Invalid(`${what} must be http(s)`);
+    return url.href;
+}
+function target(o, what) {
+    const p = page(o.page, `${what}.page`);
+    const h = href(o.href, `${what}.href`);
+    if (p !== undefined && h !== undefined)
+        throw new Invalid(`${what} has both page and href`);
+    return { ...(p !== undefined ? { page: p } : {}), ...(h !== undefined ? { href: h } : {}) };
+}
+function strMap(v, what, max) {
+    if (v === undefined || v === null)
+        return undefined;
+    const o = obj(v, what);
+    const keys = Object.keys(o);
+    if (keys.length > max)
+        throw new Invalid(`${what} has more than ${max} entries`);
+    const out = {};
+    for (const k of keys)
+        out[name(k, `${what} key`)] = str(o[k], `${what}.${k}`);
+    return out;
+}
+function field(v) {
+    const o = obj(v, 'field');
+    const kind = o.kind;
+    if (kind !== 'text' && kind !== 'textarea' && kind !== 'choice' && kind !== 'secret') {
+        throw new Invalid('field.kind must be text, textarea, choice or secret');
+    }
+    const f = { name: name(o.name, 'field.name'), label: str(o.label, 'field.label'), kind };
+    const hint = optStr(o.hint, 'field.hint');
+    if (hint !== undefined)
+        f.hint = hint;
+    // A secret field never carries a value: the page must not be able to show one.
+    if (kind !== 'secret') {
+        const value = optStr(o.value, 'field.value');
+        if (value !== undefined)
+            f.value = value;
+    }
+    if (bool(o.required))
+        f.required = true;
+    if (kind === 'choice') {
+        f.options = arr(o.options, 'field.options', LIMITS.options).map((x) => {
+            const opt = obj(x, 'option');
+            return { value: str(opt.value, 'option.value'), label: str(opt.label, 'option.label'), detail: optStr(opt.detail, 'option.detail') };
+        });
+    }
+    return f;
+}
+function block(v, depth = 0) {
+    const b = obj(v, 'block');
+    switch (b.type) {
+        case 'stats':
+            return {
+                type: 'stats',
+                items: arr(b.items, 'stats.items', LIMITS.items).map((i) => {
+                    const o = obj(i, 'stat');
+                    return {
+                        label: str(o.label, 'stat.label'), value: str(o.value, 'stat.value'),
+                        detail: optStr(o.detail, 'stat.detail'), tone: tone(o.tone), page: page(o.page, 'stat.page'),
+                    };
+                }),
+            };
+        case 'list':
+            return {
+                type: 'list',
+                items: arr(b.items, 'list.items', LIMITS.items).map((i) => {
+                    const o = obj(i, 'list item');
+                    return {
+                        text: str(o.text, 'list.text'), meta: optStr(o.meta, 'list.meta'), badge: optStr(o.badge, 'list.badge'),
+                        tone: tone(o.tone), ...target(o, 'list item'),
+                    };
+                }),
+            };
+        case 'table': {
+            const columns = arr(b.columns, 'table.columns', LIMITS.columns).map((c) => str(c, 'table column'));
+            const rows = arr(b.rows, 'table.rows', LIMITS.items).map((r) => arr(r, 'table row', columns.length).map((c) => {
+                if (typeof c === 'string' || typeof c === 'number')
+                    return str(c, 'table cell');
+                const o = obj(c, 'table cell');
+                const p = page(o.page, 'table cell.page');
+                return p !== undefined ? { text: str(o.text, 'table cell.text'), page: p } : str(o.text, 'table cell.text');
+            }));
+            return { type: 'table', columns, rows };
+        }
+        case 'kv':
+            return {
+                type: 'kv',
+                items: arr(b.items, 'kv.items', LIMITS.items).map((i) => {
+                    const o = obj(i, 'kv item');
+                    return { label: str(o.label, 'kv.label'), value: str(o.value, 'kv.value'), page: page(o.page, 'kv.page') };
+                }),
+            };
+        case 'text':
+            return { type: 'text', text: str(b.text, 'text'), tone: tone(b.tone) };
+        case 'callout':
+            return { type: 'callout', text: str(b.text, 'callout.text'), title: optStr(b.title, 'callout.title'), tone: tone(b.tone) };
+        case 'link': {
+            const t = target(b, 'link');
+            if (t.page === undefined && t.href === undefined)
+                throw new Invalid('link needs page or href');
+            return { type: 'link', text: str(b.text, 'link.text'), ...t };
+        }
+        case 'filters': {
+            const param = str(b.param, 'filters.param');
+            if (!QUERY_KEY.test(param))
+                throw new Invalid('filters.param must be a query key');
+            return {
+                type: 'filters',
+                param,
+                options: arr(b.options, 'filters.options', LIMITS.options).map((x) => {
+                    const o = obj(x, 'filter option');
+                    const value = str(o.value, 'filter.value');
+                    if (value.length > LIMITS.queryValue)
+                        throw new Invalid('filter.value is too long');
+                    return { value, label: str(o.label, 'filter.label') };
+                }),
+            };
+        }
+        case 'details':
+            if (depth > 0)
+                throw new Invalid('details can\'t contain details');
+            return {
+                type: 'details',
+                summary: str(b.summary, 'details.summary'),
+                meta: optStr(b.meta, 'details.meta'),
+                blocks: arr(b.blocks, 'details.blocks', LIMITS.blocks).map((x) => block(x, depth + 1)),
+            };
+        case 'form':
+            return {
+                type: 'form',
+                action: name(b.action, 'form.action'),
+                submit: str(b.submit, 'form.submit'),
+                fields: arr(b.fields, 'form.fields', LIMITS.fields).map(field),
+                title: optStr(b.title, 'form.title'),
+                note: optStr(b.note, 'form.note'),
+                hidden: strMap(b.hidden, 'form.hidden', LIMITS.hidden),
+            };
+        case 'buttons':
+            return {
+                type: 'buttons',
+                items: arr(b.items, 'buttons.items', LIMITS.fields).map((x) => {
+                    const o = obj(x, 'button');
+                    const t = o.tone;
+                    if (t !== undefined && t !== 'primary' && t !== 'danger')
+                        throw new Invalid('button.tone must be primary or danger');
+                    return {
+                        action: name(o.action, 'button.action'),
+                        label: str(o.label, 'button.label'),
+                        tone: t,
+                        fields: strMap(o.fields, 'button.fields', LIMITS.hidden),
+                    };
+                }),
+            };
+        default:
+            throw new Invalid(`unknown block type ${JSON.stringify(b.type)}`);
+    }
+}
+function section(v) {
+    const o = obj(v, 'section');
+    const id = str(o.id, 'section.id');
+    if (!ID.test(id))
+        throw new Invalid(`section.id ${JSON.stringify(id)} must be lowercase letters, digits and dashes`);
+    return {
+        id,
+        title: optStr(o.title, 'section.title'),
+        side: bool(o.side),
+        tone: tone(o.tone),
+        blocks: arr(o.blocks, 'section.blocks', LIMITS.blocks).map((x) => block(x)),
+    };
+}
+function sections(v) {
+    return arr(v, 'sections', LIMITS.sections).map(section);
+}
+function attempt(f) {
+    try {
+        return f();
+    }
+    catch (err) {
+        if (err instanceof Invalid)
+            return err.message;
+        throw err;
+    }
+}
+/** Validate a piece's `ui --json` answer (v2, or a first-version `{sections}`). */
+export function parseManifest(value) {
+    return attempt(() => {
+        const top = obj(value, 'answer');
+        if (top.v === undefined && top.sections !== undefined) {
+            return { asks: [], legacy: sections(top.sections) };
+        }
+        if (top.v !== 2)
+            throw new Invalid('v must be 2');
+        const m = { asks: [] };
+        if (top.tab !== undefined)
+            m.tab = { label: str(obj(top.tab, 'tab').label, 'tab.label') };
+        if (top.tile !== undefined) {
+            const t = obj(top.tile, 'tile');
+            m.tile = {
+                label: str(t.label, 'tile.label'), value: str(t.value, 'tile.value'),
+                detail: optStr(t.detail, 'tile.detail'), tone: tone(t.tone), page: page(t.page, 'tile.page'),
+            };
+        }
+        if (top.asks !== undefined) {
+            m.asks = arr(top.asks, 'asks', LIMITS.asks).map((x) => {
+                const a = obj(x, 'ask');
+                return { text: str(a.text, 'ask.text'), meta: optStr(a.meta, 'ask.meta'), page: page(a.page, 'ask.page'), label: optStr(a.label, 'ask.label') };
+            });
+        }
+        return m;
+    });
+}
+/** Validate a piece's `ui page --json` answer. */
+export function parsePage(value) {
+    return attempt(() => {
+        const top = obj(value, 'page');
+        return { title: str(top.title, 'title'), intro: optStr(top.intro, 'intro'), sections: sections(top.sections) };
+    });
+}
+/** Validate a piece's `ui act --json` answer. */
+export function parseActResult(value) {
+    return attempt(() => {
+        const top = obj(value, 'result');
+        if (typeof top.ok !== 'boolean')
+            throw new Invalid('ok must be true or false');
+        return { ok: top.ok, message: str(top.message, 'message'), page: page(top.page, 'page') };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbarket/loomai",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "MCP server for persistent AI agent identity and memory. Single-file sqlite-vec + local ONNX embeddings; zero external services.",
   "type": "module",
   "main": "dist/index.js",