glirastes 0.4.0 → 0.5.0

package/dist/agent/workspace.js

@@ -0,0 +1,264 @@
+import { lstat, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { agenticContentProblem } from '../codegen/tools/agentic.js';
+/**
+ * The repository as the managed skill runner sees it (spec 4.6): read inside
+ * the checkout only, never through a symlink, never a git-ignored or denied
+ * file, with secrets redacted and a byte budget; write only the agentic data
+ * files and the new `contract.ts` files the work list names. There is no
+ * shell and no network behind any of these operations.
+ */
+export const READ_FILE_LIMIT_BYTES = 64 * 1024;
+export const READ_RUN_LIMIT_BYTES = 400 * 1024;
+const LIST_LIMIT = 1000;
+const GREP_MATCH_LIMIT = 100;
+const GREP_LINE_LIMIT = 200;
+const GREP_FILE_LIMIT_BYTES = 1024 * 1024;
+const WRITE_JSON_LIMIT_BYTES = 512 * 1024;
+export class WorkspaceRefusal extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'WorkspaceRefusal';
+    }
+}
+/** Directory names the runner never enters, at any depth (compared in lower case). */
+const DENIED_DIRECTORIES = new Set([
+    '.git', 'node_modules', '.secrets', 'dist', 'build', 'out', '.next', '.nuxt', '.svelte-kit',
+    '.turbo', '.vercel', '.output', 'coverage', '.cache', '.venv', '__pycache__',
+]);
+/** File names the runner never reads or lists. */
+const DENIED_FILES = [
+    /^\.env(?:\..*)?$/i,
+    /^\.npmrc$/i,
+    /^\.yarnrc(?:\.yml)?$/i,
+    /^\.netrc$/i,
+    /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?$/i,
+    /\.(?:pem|key|p12|pfx|crt|cer|der|keystore|jks)$/i,
+];
+/** Connection, receipt and state files of Glirastes itself. */
+const DENIED_GLIRASTES_FILES = new Set([
+    '.glirastes/platform-connection.json',
+    '.glirastes/platform-tool-bindings.json',
+    '.glirastes/setup-receipt.json',
+    '.glirastes/setup-wizard-state.json',
+    '.glirastes/installed-skills.json',
+]);
+const REDACTIONS = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, '[redacted private key]'],
+    [/\bBearer\s+[A-Za-z0-9._~+/-]{16,}={0,2}/gi, 'Bearer [redacted]'],
+    [/\bsk-[A-Za-z0-9_-]{16,}/g, '[redacted key]'],
+    [/\bgl_[A-Za-z0-9]{32}\b/g, '[redacted key]'],
+    [/\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{20,}/g, '[redacted token]'],
+    [/\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^\s'"`]+/gi, '[redacted connection string]'],
+    [
+        /((?:password|passwd|secret|token|api[_-]?key|private[_-]?key|client[_-]?secret)["']?\s*[:=]\s*)(["'`])[^"'`\n]{8,}\2/gi,
+        '$1$2[redacted]$2',
+    ],
+];
+export function redactSecrets(text) {
+    return REDACTIONS.reduce((current, [pattern, replacement]) => current.replace(pattern, replacement), text);
+}
+function normalize(path) {
+    if (path === '' || path === '.')
+        return '';
+    if (typeof path !== 'string' || path.length > 500 || path.includes('\0')) {
+        throw new WorkspaceRefusal('path_invalid');
+    }
+    if (path.startsWith('/') || path.startsWith('\\') || /^[A-Za-z]:/.test(path) || path.includes('\\')) {
+        throw new WorkspaceRefusal('path_invalid');
+    }
+    const segments = path.split('/').filter((segment) => segment !== '' && segment !== '.');
+    if (segments.includes('..'))
+        throw new WorkspaceRefusal('path_invalid');
+    return segments.join('/');
+}
+export function deniedPath(path) {
+    if (path === '')
+        return false;
+    // Case-insensitive file systems (macOS, Windows) reach `.git` as `.GIT`.
+    const lower = path.toLowerCase();
+    const segments = lower.split('/');
+    const name = segments[segments.length - 1];
+    return segments.some((segment) => DENIED_DIRECTORIES.has(segment))
+        || DENIED_FILES.some((pattern) => pattern.test(name))
+        || DENIED_GLIRASTES_FILES.has(lower);
+}
+export class Workspace {
+    options;
+    read = 0;
+    created = new Set();
+    changed = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get bytesRead() {
+        return this.read;
+    }
+    /** Every path this run wrote, relative to the root. */
+    get written() {
+        return this.changed;
+    }
+    async listFiles(dir = '', recursive = false) {
+        const start = await this.accessible(dir, true);
+        const found = [];
+        const queue = [start];
+        while (queue.length > 0 && found.length < LIST_LIMIT) {
+            const current = queue.shift();
+            const entries = await readdir(join(this.options.root, current), { withFileTypes: true });
+            const candidates = entries
+                .filter((entry) => !entry.isSymbolicLink() && (entry.isDirectory() || entry.isFile()))
+                .map((entry) => ({ path: current === '' ? entry.name : `${current}/${entry.name}`, directory: entry.isDirectory() }))
+                .filter((entry) => !deniedPath(entry.path))
+                .sort((left, right) => left.path.localeCompare(right.path));
+            const ignored = await this.options.isIgnored(candidates.map((entry) => entry.path));
+            for (const entry of candidates) {
+                if (ignored.has(entry.path) || found.length >= LIST_LIMIT)
+                    continue;
+                found.push(entry.directory ? `${entry.path}/` : entry.path);
+                if (entry.directory && recursive)
+                    queue.push(entry.path);
+            }
+        }
+        return found;
+    }
+    async readFile(path) {
+        const relative = await this.accessible(path, false);
+        const raw = await readFile(join(this.options.root, relative));
+        const slice = raw.subarray(0, READ_FILE_LIMIT_BYTES);
+        if (this.read + slice.length > READ_RUN_LIMIT_BYTES)
+            throw new WorkspaceRefusal('read_budget_exhausted');
+        this.read += slice.length;
+        return { path: relative, content: redactSecrets(slice.toString('utf8')), truncated: raw.length > slice.length, bytes: slice.length };
+    }
+    async grep(text, dir = '') {
+        if (typeof text !== 'string' || text.length < 2 || text.length > 200)
+            throw new WorkspaceRefusal('path_invalid');
+        const files = (await this.listFiles(dir, true)).filter((path) => !path.endsWith('/'));
+        const matches = [];
+        for (const path of files) {
+            if (matches.length >= GREP_MATCH_LIMIT)
+                break;
+            const stats = await lstat(join(this.options.root, path));
+            if (stats.size > GREP_FILE_LIMIT_BYTES)
+                continue;
+            const raw = await readFile(join(this.options.root, path));
+            if (raw.includes(0))
+                continue;
+            const lines = raw.toString('utf8').split('\n');
+            for (let index = 0; index < lines.length && matches.length < GREP_MATCH_LIMIT; index += 1) {
+                if (!lines[index].includes(text))
+                    continue;
+                const line = redactSecrets(lines[index]).slice(0, GREP_LINE_LIMIT);
+                if (this.read + line.length > READ_RUN_LIMIT_BYTES)
+                    throw new WorkspaceRefusal('read_budget_exhausted');
+                this.read += line.length;
+                matches.push({ path, line: index + 1, text: line });
+            }
+        }
+        return matches;
+    }
+    async writeFile(path, content) {
+        const relative = normalize(path);
+        const rewrite = this.options.writableFiles.includes(relative);
+        const create = this.options.creatableFiles.includes(relative);
+        if (!rewrite && !create)
+            throw new WorkspaceRefusal('write_not_allowed');
+        if (typeof content !== 'string')
+            throw new WorkspaceRefusal('write_invalid_json');
+        const bytes = Buffer.byteLength(content);
+        if (bytes > (relative.endsWith('.json') ? WRITE_JSON_LIMIT_BYTES : READ_FILE_LIMIT_BYTES)) {
+            throw new WorkspaceRefusal('write_too_large');
+        }
+        let value = content;
+        if (relative.endsWith('.json')) {
+            try {
+                value = JSON.parse(content);
+            }
+            catch {
+                throw new WorkspaceRefusal('write_invalid_json');
+            }
+            if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+                throw new WorkspaceRefusal('write_invalid_json');
+            }
+        }
+        if (agenticContentProblem(value))
+            throw new WorkspaceRefusal('write_content_refused');
+        const existing = await this.status(relative);
+        if (existing === 'symlink')
+            throw new WorkspaceRefusal('path_symlink');
+        if (create && !rewrite && existing === 'file' && !this.created.has(relative)) {
+            throw new WorkspaceRefusal('write_exists');
+        }
+        await this.assertNoSymlinkParents(relative);
+        await writeFile(join(this.options.root, relative), content.endsWith('\n') ? content : `${content}\n`, 'utf8');
+        if (create && existing === 'missing')
+            this.created.add(relative);
+        this.changed.add(relative);
+        return { path: relative, bytes };
+    }
+    /**
+     * Rewrites one writable JSON file from its current content, so a caller can
+     * add entries without the model resending the whole file. A missing or
+     * unreadable file starts as `{}`; the result passes the checks of writeFile.
+     */
+    async updateJson(path, update) {
+        const relative = normalize(path);
+        if (!this.options.writableFiles.includes(relative))
+            throw new WorkspaceRefusal('write_not_allowed');
+        // One update at a time: tasks that run side by side must not overwrite each other's entries.
+        const turn = this.updates.then(async () => {
+            let current = {};
+            try {
+                const value = JSON.parse(await readFile(join(this.options.root, relative), 'utf8'));
+                if (value !== null && typeof value === 'object' && !Array.isArray(value))
+                    current = value;
+            }
+            catch {
+                current = {};
+            }
+            return this.writeFile(relative, JSON.stringify(update(current), null, 2));
+        });
+        this.updates = turn.catch(() => undefined);
+        return turn;
+    }
+    updates = Promise.resolve();
+    async accessible(path, directory) {
+        const relative = normalize(path);
+        if (deniedPath(relative))
+            throw new WorkspaceRefusal('path_denied');
+        await this.assertNoSymlinkParents(relative);
+        const status = await this.status(relative);
+        if (status === 'symlink')
+            throw new WorkspaceRefusal('path_symlink');
+        if (status !== (directory ? 'directory' : 'file'))
+            throw new WorkspaceRefusal('path_missing');
+        if (relative !== '' && (await this.options.isIgnored([relative])).has(relative)) {
+            throw new WorkspaceRefusal('path_ignored');
+        }
+        return relative;
+    }
+    async assertNoSymlinkParents(relative) {
+        const segments = relative.split('/').slice(0, -1);
+        for (let index = 1; index <= segments.length; index += 1) {
+            const status = await this.status(segments.slice(0, index).join('/'));
+            if (status === 'symlink')
+                throw new WorkspaceRefusal('path_symlink');
+            if (status === 'missing')
+                throw new WorkspaceRefusal('path_missing');
+        }
+    }
+    async status(relative) {
+        try {
+            const stats = await lstat(join(this.options.root, relative));
+            if (stats.isSymbolicLink())
+                return 'symlink';
+            return stats.isDirectory() ? 'directory' : 'file';
+        }
+        catch {
+            return 'missing';
+        }
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/agent/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/agent/workspace.ts"],"names":[],"mappings":"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"}

package/dist/browser/client-actions.d.ts

@@ -0,0 +1,26 @@
+import { type UiActionBus } from './ui-action-bus.js';
+/** Any schema with `safeParse`, e.g. a Zod object; it types and validates the payload. */
+export interface PayloadContract<T> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error?: unknown;
+    };
+}
+export interface ClientActionOptions {
+    bus?: UiActionBus;
+}
+/**
+ * Registers a client action the chat may run (`ui.<actionId>`). The literal
+ * id and the contract are read by `glirastes tools refresh`; at runtime the
+ * contract validates the payload before the handler runs.
+ */
+export declare function registerAiClientAction<T = Record<string, unknown>>(actionId: string, handler: (payload: T) => void | Promise<void>, contract?: PayloadContract<T>, options?: ClientActionOptions): () => void;
+/**
+ * Hands the UI actions of a successful tool result to the bus. Only actions
+ * of generated Glirastes tools (`glirastes.*`) are dispatched; app-specific
+ * uiActions stay with the app's own result handler. Returns the count.
+ */
+export declare function dispatchToolResultUiActions(result: unknown, bus?: UiActionBus): Promise<number>;

package/dist/browser/client-actions.js

@@ -0,0 +1,42 @@
+import { getDefaultUiActionBus } from './ui-action-bus.js';
+/**
+ * Registers a client action the chat may run (`ui.<actionId>`). The literal
+ * id and the contract are read by `glirastes tools refresh`; at runtime the
+ * contract validates the payload before the handler runs.
+ */
+export function registerAiClientAction(actionId, handler, contract, options = {}) {
+    const bus = options.bus ?? getDefaultUiActionBus();
+    return bus.subscribeById(actionId, async (action) => {
+        const payload = action.payload ?? {};
+        if (!contract) {
+            await handler(payload);
+            return;
+        }
+        const parsed = contract.safeParse(payload);
+        if (!parsed.success)
+            throw new Error(`Invalid payload for UI action ${actionId}`);
+        await handler(parsed.data);
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Hands the UI actions of a successful tool result to the bus. Only actions
+ * of generated Glirastes tools (`glirastes.*`) are dispatched; app-specific
+ * uiActions stay with the app's own result handler. Returns the count.
+ */
+export async function dispatchToolResultUiActions(result, bus = getDefaultUiActionBus()) {
+    if (!isRecord(result) || result.success !== true)
+        return 0;
+    const actions = Array.isArray(result.uiAction) ? result.uiAction : [result.uiAction];
+    let dispatched = 0;
+    for (const action of actions) {
+        if (!isRecord(action) || typeof action.type !== 'string' || !action.type.startsWith('glirastes.'))
+            continue;
+        await bus.dispatch(action);
+        dispatched += 1;
+    }
+    return dispatched;
+}
+//# sourceMappingURL=client-actions.js.map

package/dist/browser/client-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-actions.js","sourceRoot":"","sources":["../../src/browser/client-actions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAmC,MAAM,oBAAoB,CAAC;AAa5F;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgB,EAChB,OAA6C,EAC7C,QAA6B,EAC7B,UAA+B,EAAE;IAEjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,qBAAqB,EAAE,CAAC;IACnD,OAAO,GAAG,CAAC,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QAClD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,OAAO,CAAC,OAAY,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,QAAQ,EAAE,CAAC,CAAC;QAClF,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAe,EACf,MAAmB,qBAAqB,EAAE;IAE1C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrF,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;YAAE,SAAS;QAC5G,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAkB,CAAC,CAAC;QACvC,UAAU,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/browser/index.d.ts

@@ -0,0 +1,4 @@
+export { getDefaultUiActionBus, UiActionBus, type UiAction, type UiActionHandler, } from './ui-action-bus.js';
+export { buildNavigationHref, GLIRASTES_NAVIGATE_ACTION_ID, isSafeAppHref, registerNavigationBridge, type NavigationBridgeOptions, type QueryValue, } from './navigation.js';
+export { dispatchToolResultUiActions, registerAiClientAction, type ClientActionOptions, type PayloadContract, } from './client-actions.js';
+export { defineQueryFilters, type QueryFilterScalar, type QueryFilterSpec, type QueryFiltersDefinition, type QueryFilterValues, } from './query-filters.js';

package/dist/browser/index.js

@@ -0,0 +1,5 @@
+export { getDefaultUiActionBus, UiActionBus, } from './ui-action-bus.js';
+export { buildNavigationHref, GLIRASTES_NAVIGATE_ACTION_ID, isSafeAppHref, registerNavigationBridge, } from './navigation.js';
+export { dispatchToolResultUiActions, registerAiClientAction, } from './client-actions.js';
+export { defineQueryFilters, } from './query-filters.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,WAAW,GAGZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,aAAa,EACb,wBAAwB,GAGzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GAGvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,GAKnB,MAAM,oBAAoB,CAAC"}

package/dist/browser/navigation.d.ts

@@ -0,0 +1,32 @@
+import { type UiActionBus } from './ui-action-bus.js';
+/** Action id of every generated navigation and filter tool (`ui.navigate`, `ui.filter.<view>`). */
+export declare const GLIRASTES_NAVIGATE_ACTION_ID = "glirastes.navigate";
+export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+/**
+ * An app-internal path: one leading slash, no scheme, no protocol-relative
+ * `//host`, no backslash, no control characters and no dot segment in the
+ * path (`/a/..//host` resolves to the protocol-relative `//host`).
+ */
+export declare function isSafeAppHref(href: unknown): href is string;
+/**
+ * Builds the href a navigation or filter tool pushes. `destination` uses the
+ * route spelling of the tool (`/tasks/:id`); query values keep key order,
+ * arrays are joined with commas (nuqs `parseAsArrayOf`) or repeated
+ * (`searchParams.getAll`).
+ */
+export declare function buildNavigationHref(input: {
+    destination: string;
+    params?: Readonly<Record<string, string>>;
+    query?: Readonly<Record<string, QueryValue>>;
+    arrayFormats?: Readonly<Record<string, 'comma' | 'repeat'>>;
+}): string;
+export interface NavigationBridgeOptions {
+    /** The router's push, e.g. Next.js `router.push` or vue-router `router.push`. */
+    push: (href: string) => unknown;
+    bus?: UiActionBus;
+}
+/**
+ * Executes `ui.navigate` and `ui.filter.<view>` results with the app's own
+ * router. Returns the unsubscribe function.
+ */
+export declare function registerNavigationBridge(options: NavigationBridgeOptions): () => void;

package/dist/browser/navigation.js

@@ -0,0 +1,79 @@
+import { getDefaultUiActionBus } from './ui-action-bus.js';
+/** Action id of every generated navigation and filter tool (`ui.navigate`, `ui.filter.<view>`). */
+export const GLIRASTES_NAVIGATE_ACTION_ID = 'glirastes.navigate';
+/** `.` and `..` path segments, also percent-encoded; URL parsing resolves them. */
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+/**
+ * An app-internal path: one leading slash, no scheme, no protocol-relative
+ * `//host`, no backslash, no control characters and no dot segment in the
+ * path (`/a/..//host` resolves to the protocol-relative `//host`).
+ */
+export function isSafeAppHref(href) {
+    return typeof href === 'string'
+        && href.length > 0
+        && href.length <= 2_048
+        && href.startsWith('/')
+        && !href.startsWith('//')
+        && !href.includes('\\')
+        && !/[\u0000-\u001f\u007f]/.test(href)
+        && !href.split(/[?#]/, 1)[0].split('/').some((segment) => DOT_SEGMENT.test(segment));
+}
+/**
+ * Builds the href a navigation or filter tool pushes. `destination` uses the
+ * route spelling of the tool (`/tasks/:id`); query values keep key order,
+ * arrays are joined with commas (nuqs `parseAsArrayOf`) or repeated
+ * (`searchParams.getAll`).
+ */
+export function buildNavigationHref(input) {
+    const path = input.destination.split('/').map((segment) => {
+        if (!segment.startsWith(':'))
+            return segment;
+        const name = segment.slice(1);
+        const value = input.params?.[name];
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(`Missing route parameter ${name}`);
+        }
+        // `.` and `..` would move the path instead of naming one segment.
+        if (value === '.' || value === '..')
+            throw new Error(`Invalid route parameter ${name}`);
+        return encodeURIComponent(value);
+    }).join('/');
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                continue;
+            if (input.arrayFormats?.[key] === 'repeat') {
+                for (const item of value)
+                    search.append(key, String(item));
+            }
+            else {
+                search.append(key, value.map(String).join(','));
+            }
+            continue;
+        }
+        search.append(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `${path}?${query}` : path;
+}
+function hrefOf(action) {
+    const payload = action.payload;
+    return payload && typeof payload === 'object' ? payload.href : undefined;
+}
+/**
+ * Executes `ui.navigate` and `ui.filter.<view>` results with the app's own
+ * router. Returns the unsubscribe function.
+ */
+export function registerNavigationBridge(options) {
+    const bus = options.bus ?? getDefaultUiActionBus();
+    return bus.subscribeById(GLIRASTES_NAVIGATE_ACTION_ID, async (action) => {
+        const href = hrefOf(action);
+        if (!isSafeAppHref(href))
+            throw new Error('Unsafe navigation target');
+        await options.push(href);
+    });
+}
+//# sourceMappingURL=navigation.js.map

package/dist/browser/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/browser/navigation.ts"],"names":[],"mappings":"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"}

package/dist/browser/query-filters.d.ts

@@ -0,0 +1,30 @@
+export type QueryFilterScalar = 'string' | 'integer' | 'number' | 'boolean' | readonly [string, ...string[]];
+export type QueryFilterSpec = QueryFilterScalar | {
+    readonly arrayOf: QueryFilterScalar;
+    readonly format?: 'comma' | 'repeat';
+};
+type ScalarValue<S> = S extends 'integer' | 'number' ? number : S extends 'boolean' ? boolean : S extends readonly (infer L)[] ? L : string;
+type FilterValue<S> = S extends {
+    readonly arrayOf: infer V;
+} ? Array<ScalarValue<V>> : ScalarValue<S>;
+export type QueryFilterValues<F extends Record<string, QueryFilterSpec>> = {
+    [K in keyof F]?: FilterValue<F[K]>;
+};
+export interface QueryFiltersDefinition<F extends Record<string, QueryFilterSpec>> {
+    readonly path: string;
+    readonly filters: F;
+    /** Typed filter values from a query string; values outside the domain are dropped. */
+    read(search: string | URLSearchParams): QueryFilterValues<F>;
+    /** The href `ui.filter.<view>` pushes for these values. */
+    href(values: QueryFilterValues<F>, params?: Readonly<Record<string, string>>): string;
+}
+/**
+ * Declares the URL filters of a view for apps without a framework source
+ * (SPAs, Vue). `glirastes tools refresh` reads the literal definition and
+ * generates `ui.filter.<view>`; the app uses `read` to apply the URL.
+ */
+export declare function defineQueryFilters<const F extends Record<string, QueryFilterSpec>>(definition: {
+    path: string;
+    filters: F;
+}): QueryFiltersDefinition<F>;
+export {};

package/dist/browser/query-filters.js

@@ -0,0 +1,85 @@
+import { buildNavigationHref } from './navigation.js';
+const NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+const KINDS = new Set(['string', 'integer', 'number', 'boolean']);
+function scalarOf(spec) {
+    return typeof spec === 'object' && !Array.isArray(spec) && 'arrayOf' in spec ? spec.arrayOf : spec;
+}
+function assertScalar(key, scalar) {
+    if (Array.isArray(scalar)) {
+        if (scalar.length === 0 || scalar.some((value) => typeof value !== 'string' || value.length === 0)) {
+            throw new Error(`Filter ${key} needs at least one non-empty value`);
+        }
+        return;
+    }
+    if (typeof scalar !== 'string' || !KINDS.has(scalar)) {
+        throw new Error(`Filter ${key} must be string, integer, number, boolean or a list of values`);
+    }
+}
+function parseScalar(scalar, raw) {
+    if (Array.isArray(scalar))
+        return scalar.includes(raw) ? raw : undefined;
+    switch (scalar) {
+        case 'integer':
+            return /^-?\d+$/.test(raw) ? Number.parseInt(raw, 10) : undefined;
+        case 'number': {
+            const value = Number(raw);
+            return raw.trim() !== '' && Number.isFinite(value) ? value : undefined;
+        }
+        case 'boolean':
+            return raw === 'true' ? true : raw === 'false' ? false : undefined;
+        default:
+            return raw;
+    }
+}
+/**
+ * Declares the URL filters of a view for apps without a framework source
+ * (SPAs, Vue). `glirastes tools refresh` reads the literal definition and
+ * generates `ui.filter.<view>`; the app uses `read` to apply the URL.
+ */
+export function defineQueryFilters(definition) {
+    if (typeof definition.path !== 'string' || !definition.path.startsWith('/') || definition.path.startsWith('//')) {
+        throw new Error('defineQueryFilters needs an app path starting with /');
+    }
+    for (const [key, spec] of Object.entries(definition.filters)) {
+        if (!NAME.test(key))
+            throw new Error(`Filter key ${JSON.stringify(key)} is not a plain name`);
+        assertScalar(key, scalarOf(spec));
+    }
+    const arrayFormats = {};
+    for (const [key, spec] of Object.entries(definition.filters)) {
+        if (typeof spec === 'object' && !Array.isArray(spec) && 'arrayOf' in spec)
+            arrayFormats[key] = spec.format ?? 'comma';
+    }
+    return {
+        path: definition.path,
+        filters: definition.filters,
+        read(search) {
+            const params = typeof search === 'string' ? new URLSearchParams(search) : search;
+            const values = {};
+            for (const [key, spec] of Object.entries(definition.filters)) {
+                const scalar = scalarOf(spec);
+                if (arrayFormats[key]) {
+                    const raw = arrayFormats[key] === 'repeat' ? params.getAll(key) : (params.get(key)?.split(',') ?? []);
+                    const parsed = raw.map((value) => parseScalar(scalar, value)).filter((value) => value !== undefined);
+                    if (parsed.length > 0)
+                        values[key] = parsed;
+                    continue;
+                }
+                const raw = params.get(key);
+                const parsed = raw === null ? undefined : parseScalar(scalar, raw);
+                if (parsed !== undefined)
+                    values[key] = parsed;
+            }
+            return values;
+        },
+        href(values, params) {
+            return buildNavigationHref({
+                destination: definition.path,
+                ...(params ? { params } : {}),
+                query: values,
+                arrayFormats,
+            });
+        },
+    };
+}
+//# sourceMappingURL=query-filters.js.map

package/dist/browser/query-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-filters.js","sourceRoot":"","sources":["../../src/browser/query-filters.ts"],"names":[],"mappings":"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"}