@smartdoca/web-plugin-registry 0.1.0

package/dist/index.js

@@ -0,0 +1,394 @@
+export class RegistryConflictError extends Error {
+    code;
+    contributionId;
+    name = "RegistryConflictError";
+    constructor(code, message, contributionId) {
+        super(`${contributionId}: ${message}`);
+        this.code = code;
+        this.contributionId = contributionId;
+    }
+}
+const pluginIdentifier = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const messageIdentifier = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const semanticVersion = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+function assertClientManifest(manifest, target) {
+    if (!pluginIdentifier.test(manifest.pluginId))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "manifest pluginId must be a stable lowercase dotted or dashed identifier", manifest.pluginId);
+    if (!semanticVersion.test(manifest.version))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "manifest version must be semantic", manifest.pluginId);
+    if (new Set(manifest.targets).size !== manifest.targets.length ||
+        !manifest.targets.includes(target))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", `manifest must declare the ${target} target exactly once`, manifest.pluginId);
+}
+function assertOwnedContribution(contribution) {
+    if (!pluginIdentifier.test(contribution.pluginId))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "pluginId must be a stable lowercase dotted or dashed identifier", contribution.id);
+    if (!messageIdentifier.test(contribution.id) ||
+        !contribution.id.startsWith(`${contribution.pluginId}.`))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", `id must be namespaced by ${contribution.pluginId}`, contribution.id);
+    if (contribution.order !== undefined &&
+        !Number.isFinite(contribution.order))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "order must be finite", contribution.id);
+}
+function compareContributions(left, right) {
+    return (left.order ?? 0) - (right.order ?? 0) ||
+        left.id.localeCompare(right.id);
+}
+/**
+ * A synchronous, effect-owned registry. Registration either succeeds
+ * atomically or leaves no record behind; the returned disposer is idempotent.
+ */
+export class EffectRegistry {
+    point;
+    conflictKey;
+    #byId = new Map();
+    #byConflictKey = new Map();
+    constructor(point, conflictKey) {
+        this.point = point;
+        this.conflictKey = conflictKey;
+    }
+    register(contribution) {
+        assertOwnedContribution(contribution);
+        const existing = this.#byId.get(contribution.id);
+        if (existing)
+            throw new RegistryConflictError("DUPLICATE_CONTRIBUTION_ID", `${this.point} id is already registered by ${existing.pluginId}`, contribution.id);
+        const conflictKey = this.conflictKey?.(contribution);
+        const conflicting = conflictKey
+            ? this.#byConflictKey.get(conflictKey)
+            : undefined;
+        if (conflicting)
+            throw new RegistryConflictError("DUPLICATE_CONTRIBUTION_PATH", `${this.point} key ${conflictKey} is already registered by ${conflicting.pluginId}`, contribution.id);
+        this.#byId.set(contribution.id, contribution);
+        if (conflictKey)
+            this.#byConflictKey.set(conflictKey, contribution);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            if (this.#byId.get(contribution.id) === contribution)
+                this.#byId.delete(contribution.id);
+            if (conflictKey &&
+                this.#byConflictKey.get(conflictKey) === contribution)
+                this.#byConflictKey.delete(conflictKey);
+        };
+    }
+    get(id) {
+        return this.#byId.get(id);
+    }
+    getByConflictKey(key) {
+        return this.#byConflictKey.get(key);
+    }
+    list() {
+        return [...this.#byId.values()].sort(compareContributions);
+    }
+}
+function registerOwned(registry, contributions, pluginId, effects) {
+    for (const contribution of contributions ?? []) {
+        if (contribution.pluginId !== pluginId)
+            throw new RegistryConflictError("INVALID_CONTRIBUTION", `contribution owner does not match ${pluginId}`, contribution.id);
+        effects.push(registry.register(contribution));
+    }
+}
+function normalizeRoutePath(path) {
+    const clean = path.trim().split(/[?#]/, 1)[0] || "/";
+    const prefixed = clean.startsWith("/") ? clean : `/${clean}`;
+    return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : prefixed;
+}
+function assertRoutePath(path, contributionId) {
+    const normalized = normalizeRoutePath(path);
+    if (!/^\/(?:[a-z0-9._-]+|:[a-z][A-Za-z0-9]*)(?:\/(?:[a-z0-9._-]+|:[a-z][A-Za-z0-9]*))*$/i.test(normalized) &&
+        normalized !== "/")
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", `invalid route path ${path}`, contributionId);
+    return normalized;
+}
+function matchRoute(pattern, input) {
+    const path = normalizeRoutePath(input);
+    const patternParts = normalizeRoutePath(pattern).split("/").filter(Boolean);
+    const pathParts = path.split("/").filter(Boolean);
+    if (patternParts.length !== pathParts.length)
+        return undefined;
+    const params = {};
+    for (let index = 0; index < patternParts.length; index++) {
+        const expected = patternParts[index];
+        const actual = pathParts[index];
+        if (expected.startsWith(":")) {
+            params[expected.slice(1)] = decodeURIComponent(actual);
+        }
+        else if (expected !== actual) {
+            return undefined;
+        }
+    }
+    return { path, params };
+}
+function validateMessages(contribution) {
+    const englishKeys = Object.keys(contribution.messages.en).sort();
+    const chineseKeys = Object.keys(contribution.messages.zh).sort();
+    if (englishKeys.length !== chineseKeys.length ||
+        englishKeys.some((key, index) => key !== chineseKeys[index]))
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "zh and en dictionaries must contain exactly the same keys", contribution.id);
+    for (const key of englishKeys) {
+        if (!messageIdentifier.test(key) ||
+            !key.startsWith(`${contribution.pluginId}.`))
+            throw new RegistryConflictError("INVALID_CONTRIBUTION", `message key ${key} must be a stable key namespaced by ${contribution.pluginId}`, contribution.id);
+    }
+}
+function interpolate(message, values) {
+    if (!values)
+        return message;
+    return message.replace(/\{([A-Za-z][A-Za-z0-9_]*)\}/g, (_, key) => values[key] === undefined ? `{${key}}` : String(values[key]));
+}
+export class WebPluginRegistry {
+    routes = new EffectRegistry("web route", (route) => assertRoutePath(route.path, route.id));
+    navigation = new EffectRegistry("web navigation", (item) => item.scope);
+    adminPanels = new EffectRegistry("web admin panel", (panel) => panel.tab);
+    settingsFields = new EffectRegistry("web settings field", (field) => field.path);
+    aiBlocks = new EffectRegistry("web AI block", (block) => block.kind);
+    searchResults = new EffectRegistry("web search result", (result) => result.kind);
+    knowledgeSources = new EffectRegistry("web knowledge source", (source) => source.sourceKind);
+    filePickers = new EffectRegistry("web file picker", (picker) => picker.capability);
+    messages = new EffectRegistry("web messages");
+    #messageOwners = new Map();
+    #manifests = new Map();
+    register(bundle) {
+        assertClientManifest(bundle.manifest, "web");
+        if (this.#manifests.has(bundle.manifest.pluginId))
+            throw new RegistryConflictError("DUPLICATE_CONTRIBUTION_ID", "web plugin manifest is already registered", bundle.manifest.pluginId);
+        const effects = [];
+        try {
+            const pluginId = bundle.manifest.pluginId;
+            registerOwned(this.routes, bundle.routes, pluginId, effects);
+            registerOwned(this.navigation, bundle.navigation, pluginId, effects);
+            registerOwned(this.adminPanels, bundle.adminPanels, pluginId, effects);
+            registerOwned(this.settingsFields, bundle.settingsFields, pluginId, effects);
+            registerOwned(this.aiBlocks, bundle.aiBlocks, pluginId, effects);
+            registerOwned(this.searchResults, bundle.searchResults, pluginId, effects);
+            registerOwned(this.knowledgeSources, bundle.knowledgeSources, pluginId, effects);
+            registerOwned(this.filePickers, bundle.filePickers, pluginId, effects);
+            for (const contribution of bundle.messages ?? []) {
+                if (contribution.pluginId !== bundle.manifest.pluginId)
+                    throw new RegistryConflictError("INVALID_CONTRIBUTION", `message owner does not match ${bundle.manifest.pluginId}`, contribution.id);
+                validateMessages(contribution);
+                for (const key of Object.keys(contribution.messages.en)) {
+                    const owner = this.#messageOwners.get(key);
+                    if (owner)
+                        throw new RegistryConflictError("DUPLICATE_CONTRIBUTION_ID", `message key ${key} is already registered by ${owner}`, contribution.id);
+                }
+                effects.push(this.messages.register(contribution));
+                for (const key of Object.keys(contribution.messages.en))
+                    this.#messageOwners.set(key, contribution.id);
+                effects.push(() => {
+                    for (const key of Object.keys(contribution.messages.en))
+                        if (this.#messageOwners.get(key) === contribution.id)
+                            this.#messageOwners.delete(key);
+                });
+            }
+            this.#manifests.set(bundle.manifest.pluginId, bundle.manifest);
+            effects.push(() => {
+                if (this.#manifests.get(bundle.manifest.pluginId) === bundle.manifest)
+                    this.#manifests.delete(bundle.manifest.pluginId);
+            });
+        }
+        catch (error) {
+            for (let index = effects.length - 1; index >= 0; index--)
+                effects[index]();
+            throw error;
+        }
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            for (let index = effects.length - 1; index >= 0; index--)
+                effects[index]();
+        };
+    }
+    manifests() {
+        return [...this.#manifests.values()].sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+    }
+    resolveRoute(path) {
+        for (const contribution of this.routes.list()) {
+            const match = matchRoute(contribution.path, path);
+            if (match)
+                return { contribution, match };
+        }
+        return undefined;
+    }
+    translate(locale, key, values) {
+        const selected = locale === "zh"
+            ? "zh"
+            : locale === undefined
+                ? "zh"
+                : "en";
+        for (const contribution of this.messages.list()) {
+            const message = contribution.messages[selected][key] ?? contribution.messages.en[key];
+            if (message !== undefined)
+                return interpolate(message, values);
+        }
+        return key;
+    }
+}
+export class MobilePluginRegistry {
+    routes = new EffectRegistry("mobile route", (route) => assertRoutePath(route.path, route.id));
+    tabs = new EffectRegistry("mobile tab", (tab) => tab.route);
+    aiNodes = new EffectRegistry("mobile AI node", (node) => node.kind);
+    searchResults = new EffectRegistry("mobile search result", (result) => result.kind);
+    filePickers = new EffectRegistry("mobile file picker", (picker) => picker.capability);
+    messages = new EffectRegistry("mobile messages");
+    #manifests = new Map();
+    register(bundle) {
+        assertClientManifest(bundle.manifest, "mobile");
+        if (this.#manifests.has(bundle.manifest.pluginId))
+            throw new RegistryConflictError("DUPLICATE_CONTRIBUTION_ID", "mobile plugin manifest is already registered", bundle.manifest.pluginId);
+        const effects = [];
+        try {
+            const pluginId = bundle.manifest.pluginId;
+            registerOwned(this.routes, bundle.routes, pluginId, effects);
+            registerOwned(this.tabs, bundle.tabs, pluginId, effects);
+            registerOwned(this.aiNodes, bundle.aiNodes, pluginId, effects);
+            registerOwned(this.searchResults, bundle.searchResults, pluginId, effects);
+            registerOwned(this.filePickers, bundle.filePickers, pluginId, effects);
+            for (const contribution of bundle.messages ?? [])
+                validateMessages(contribution);
+            registerOwned(this.messages, bundle.messages, pluginId, effects);
+            this.#manifests.set(bundle.manifest.pluginId, bundle.manifest);
+            effects.push(() => {
+                if (this.#manifests.get(bundle.manifest.pluginId) === bundle.manifest)
+                    this.#manifests.delete(bundle.manifest.pluginId);
+            });
+        }
+        catch (error) {
+            for (let index = effects.length - 1; index >= 0; index--)
+                effects[index]();
+            throw error;
+        }
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            for (let index = effects.length - 1; index >= 0; index--)
+                effects[index]();
+        };
+    }
+    manifests() {
+        return [...this.#manifests.values()].sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+    }
+}
+function conversationKey(kind, id) {
+    return `${kind}\u0000${id}`;
+}
+function assertConversationEvent(event) {
+    if (!event.kind.trim() || !event.id.trim() || !event.type.trim())
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "conversation event kind, id and type are required", `${event.kind}/${event.id}`);
+    if (!Number.isSafeInteger(event.seq) || event.seq < 0)
+        throw new RegistryConflictError("INVALID_CONTRIBUTION", "conversation event seq must be a non-negative safe integer", `${event.kind}/${event.id}`);
+}
+function canonical(value) {
+    if (value === null || typeof value !== "object") {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            throw new TypeError("conversation events must be JSON serializable");
+        return encoded;
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonical(object[key])}`).join(",")}}`;
+}
+/**
+ * Stores events by stable (kind,id,seq) and replays each stream from sorted
+ * sequence numbers for every projection. Arrival order never affects output.
+ */
+export class ConversationAssembler {
+    definitions = new EffectRegistry("conversation definition", (definition) => definition.kind);
+    #streams = new Map();
+    append(event) {
+        assertConversationEvent(event);
+        const key = conversationKey(event.kind, event.id);
+        let stream = this.#streams.get(key);
+        if (!stream) {
+            stream = new Map();
+            this.#streams.set(key, stream);
+        }
+        const existing = stream.get(event.seq);
+        if (existing) {
+            if (canonical(existing) === canonical(event))
+                return false;
+            throw new RegistryConflictError("EVENT_SEQUENCE_CONFLICT", `seq ${event.seq} already contains a different event`, `${event.kind}/${event.id}`);
+        }
+        stream.set(event.seq, event);
+        return true;
+    }
+    appendAll(events) {
+        for (const event of events)
+            this.append(event);
+        return this.snapshot();
+    }
+    clear(kind, id) {
+        if (kind !== undefined && id !== undefined) {
+            this.#streams.delete(conversationKey(kind, id));
+            return;
+        }
+        this.#streams.clear();
+    }
+    snapshot() {
+        const nodes = [];
+        for (const [key, stream] of this.#streams) {
+            const events = [...stream.values()].sort((left, right) => left.seq - right.seq);
+            if (!events.length)
+                continue;
+            const first = events[0];
+            const last = events.at(-1);
+            const definition = this.definitions.getByConflictKey(first.kind);
+            if (!definition) {
+                nodes.push({
+                    key,
+                    kind: first.kind,
+                    id: first.id,
+                    firstSeq: first.seq,
+                    lastSeq: last.seq,
+                    settled: events.some((event) => event.settled === true),
+                    definitionId: "generic",
+                    value: Object.freeze({
+                        type: "generic-event",
+                        kind: first.kind,
+                        id: first.id,
+                        events: Object.freeze(events),
+                    }),
+                });
+                continue;
+            }
+            let state;
+            let started = false;
+            for (const event of events) {
+                if (!started) {
+                    if (!definition.isStart(event))
+                        continue;
+                    state = definition.start(event);
+                    started = true;
+                }
+                else {
+                    state = definition.update(state, event);
+                }
+            }
+            // Known updates remain pending until their start fact is available.
+            if (!started)
+                continue;
+            nodes.push({
+                key,
+                kind: first.kind,
+                id: first.id,
+                firstSeq: first.seq,
+                lastSeq: last.seq,
+                settled: events.some((event) => event.settled === true),
+                definitionId: definition.id,
+                value: definition.materialize(state, {
+                    key,
+                    events: Object.freeze(events),
+                }),
+            });
+        }
+        return nodes.sort((left, right) => left.firstSeq - right.firstSeq || left.key.localeCompare(right.key));
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@smartdoca/web-plugin-registry",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
+}