@helyx/core 0.2.1 → 0.2.3

package/dist/help.js

@@ -0,0 +1,304 @@
+import { createHash } from "node:crypto";
+export const HELP_COLLECTION_SCHEMA_VERSION = 2;
+export const HELP_QUESTION_MAX_LENGTH = 600;
+export const HELP_DOCS_URL = "https://docs.helyx.gg/";
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/** Explicit field order makes hashes independent of JSON property order. */
+export function helpFaqContent(faq) {
+    return {
+        id: faq.id,
+        moduleCode: faq.moduleCode,
+        area: faq.area,
+        areaName: faq.areaName,
+        moduleId: faq.moduleId,
+        question: faq.question,
+        answerMarkdown: faq.answerMarkdown,
+        answerText: faq.answerText,
+        sourceUrl: faq.sourceUrl,
+        sourcePath: faq.sourcePath,
+        releaseStatus: faq.releaseStatus,
+        deploymentSupport: faq.deploymentSupport,
+        context: [...faq.context],
+    };
+}
+export function hashHelpFaq(faq) {
+    return hash(helpFaqContent(faq));
+}
+export function createHelpCollection(faqs) {
+    const records = faqs
+        .map((faq) => ({ ...helpFaqContent(faq), contentHash: faq.contentHash }))
+        .sort((a, b) => compare(a.id, b.id));
+    return parseHelpCollection({
+        schemaVersion: HELP_COLLECTION_SCHEMA_VERSION,
+        revision: hash(records),
+        faqs: records,
+    });
+}
+/** Validate persisted/build input before it can enter retrieval or packaging. */
+export function parseHelpCollection(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Invalid Help collection");
+    const collection = value;
+    if (collection.schemaVersion !== 2 || !Array.isArray(collection.faqs))
+        throw new Error("Unsupported Help collection schema");
+    const seen = new Set();
+    const faqs = [];
+    for (const input of collection.faqs) {
+        if (!input || typeof input !== "object")
+            throw new Error("Invalid Help FAQ");
+        const faq = input;
+        for (const field of [
+            "id",
+            "moduleCode",
+            "area",
+            "areaName",
+            "question",
+            "answerMarkdown",
+            "answerText",
+            "sourceUrl",
+            "sourcePath",
+            "contentHash",
+        ]) {
+            if (typeof faq[field] !== "string" || !faq[field].trim())
+                throw new Error(`Invalid Help FAQ ${field}`);
+        }
+        if (!/^[1-9]\d{5}$/u.test(faq.id) ||
+            faq.id.slice(3) === "000" ||
+            faq.moduleCode !== faq.id.slice(0, 3) ||
+            seen.has(faq.id))
+            throw new Error(`Invalid or duplicate Help FAQ ID: ${faq.id}`);
+        seen.add(faq.id);
+        if (faq.moduleId !== null && typeof faq.moduleId !== "string")
+            throw new Error("Invalid Help module identity");
+        if (!["live", "testing", "planned", "alpha", "reference", "unknown"].includes(faq.releaseStatus))
+            throw new Error("Invalid Help release status");
+        if (!["both", "hosted", "self-hosted", "not_declared"].includes(faq.deploymentSupport))
+            throw new Error("Invalid Help deployment support");
+        if (!Array.isArray(faq.context) ||
+            faq.context.some((item) => typeof item !== "string"))
+            throw new Error("Invalid Help context");
+        const url = new URL(faq.sourceUrl);
+        if (url.origin !== "https://docs.helyx.gg" ||
+            url.username ||
+            url.password ||
+            !url.hash)
+            throw new Error("Help source must be a public documentation fragment");
+        if (!/^apps\/docs\/src\/content\/docs\/.+\.mdx?$/u.test(faq.sourcePath) ||
+            faq.sourcePath.includes(".."))
+            throw new Error("Invalid Help source path");
+        if (faq.contentHash !== hashHelpFaq(faq))
+            throw new Error(`Help FAQ checksum mismatch: ${faq.id}`);
+        faqs.push({ ...helpFaqContent(faq), contentHash: faq.contentHash });
+    }
+    faqs.sort((a, b) => compare(a.id, b.id));
+    if (collection.revision !== hash(faqs))
+        throw new Error("Help collection checksum mismatch");
+    return { schemaVersion: 2, revision: collection.revision, faqs };
+}
+const stopWords = new Set("a an and are as at be been but by can could did do does for from had has have how i if in is it its me my of on or our should that the their them there these they this to us was we were what when where which who why will with would you your help helyx module please".split(" "));
+const normalise = (text) => text
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+export const normaliseHelpQuestion = normalise;
+const terms = (text) => new Set(normalise(text)
+    .split(/\s+/u)
+    .filter((term) => term && !stopWords.has(term)));
+export function createHelpLexicalSearch(faqs, revision, copy = (faq) => structuredClone(faq)) {
+    const documents = faqs.map((faq) => ({
+        faq,
+        normalised: normalise(faq.question),
+        question: terms(faq.question),
+        area: terms(`${faq.area} ${faq.areaName}`),
+        answer: terms(faq.answerText),
+    }));
+    const frequency = new Map();
+    for (const doc of documents)
+        for (const term of doc.question)
+            frequency.set(term, (frequency.get(term) ?? 0) + 1);
+    const weight = (term) => 1 + Math.log(1 + documents.length / (1 + (frequency.get(term) ?? 0)));
+    const base = { mode: "lexical", revision };
+    const choose = (results) => results.length === 1
+        ? { ...base, kind: "answer", faq: copy(results[0]) }
+        : { ...base, kind: "choices", faqs: results.slice(0, 3).map(copy) };
+    return (question) => {
+        if (question.length > 600)
+            return { ...base, kind: "invalid", reason: "too_long" };
+        const query = normalise(question), tokens = terms(question);
+        if (!query || !tokens.size)
+            return {
+                ...base,
+                kind: "no_match",
+                reason: "empty",
+                docsUrl: "https://docs.helyx.gg/",
+            };
+        const byId = documents.find(({ faq }) => faq.id === question.trim().replace(/^#/u, ""));
+        if (byId)
+            return choose([byId.faq]);
+        const exact = documents.filter((doc) => doc.normalised === query);
+        if (exact.length)
+            return choose(exact.map(({ faq }) => faq));
+        const total = [...tokens].reduce((sum, term) => sum + weight(term), 0);
+        const ranked = documents
+            .map((doc) => {
+            let matched = 0, overlap = 0, areaOverlap = 0, answerOverlap = 0;
+            for (const term of tokens) {
+                if (doc.question.has(term)) {
+                    overlap += weight(term);
+                    matched++;
+                }
+                if (doc.area.has(term))
+                    areaOverlap += weight(term);
+                if (doc.answer.has(term))
+                    answerOverlap += weight(term);
+            }
+            const coverage = overlap / total, length = [...doc.question].reduce((sum, term) => sum + weight(term), 0);
+            const score = (2 * overlap) / (total + length || 1) +
+                (0.2 * areaOverlap) / total +
+                (0.05 * answerOverlap) / total;
+            return { ...doc, score, coverage, matched };
+        })
+            .filter((doc) => doc.matched > 0 && doc.score >= 0.3)
+            .sort((a, b) => b.score - a.score ||
+            (a.faq.id < b.faq.id ? -1 : a.faq.id > b.faq.id ? 1 : 0));
+        const best = ranked[0];
+        if (!best)
+            return {
+                ...base,
+                kind: "no_match",
+                reason: "weak_match",
+                docsUrl: "https://docs.helyx.gg/",
+            };
+        const next = ranked[1];
+        if (best.matched >= 2 &&
+            best.coverage >= 0.8 &&
+            best.score >= 0.65 &&
+            (!next || best.score - next.score >= 0.18))
+            return choose([best.faq]);
+        const alternatives = ranked
+            .filter((doc) => doc.coverage >= 0.4 && doc.score >= best.score - 0.18)
+            .slice(0, 3);
+        if (alternatives.length >= 2)
+            return {
+                ...base,
+                kind: "choices",
+                faqs: alternatives.map(({ faq }) => copy(faq)),
+            };
+        return {
+            ...base,
+            kind: "no_match",
+            reason: "weak_match",
+            docsUrl: "https://docs.helyx.gg/",
+        };
+    };
+}
+/** Conservative local baseline. Scores are ranking signals, not probabilities. */
+export function createHelpSearch(input) {
+    const collection = parseHelpCollection(input);
+    return createHelpLexicalSearch(collection.faqs, collection.revision, (faq) => ({ ...faq, context: [...faq.context] }));
+}
+export const HELP_PUBLISHED_SOURCE_URL = "https://docs.helyx.gg/help-sources.json";
+function publishedSourceContent(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Invalid published Help source");
+    const feed = value;
+    if (feed.schemaVersion !== 1 ||
+        !Array.isArray(feed.groups) ||
+        feed.groups.length > 898 ||
+        !Array.isArray(feed.records) ||
+        feed.records.length > 20000 ||
+        !/^[a-f0-9]{64}$/u.test(feed.sourceRevision) ||
+        !Number.isInteger(feed.nextModuleCode) ||
+        !Number.isInteger(feed.nextGeneralCode) ||
+        feed.nextModuleCode < 100 ||
+        feed.nextModuleCode > 1000 ||
+        feed.nextGeneralCode < 99 ||
+        feed.nextGeneralCode > 999 ||
+        feed.nextModuleCode > feed.nextGeneralCode + 1)
+        throw new Error("Invalid published Help source bounds");
+    const groups = feed.groups
+        .map((group) => ({
+        code: group.code,
+        area: group.area,
+        name: group.name,
+        nextFaq: group.nextFaq,
+    }))
+        .sort((a, b) => compare(a.code, b.code));
+    if (new Set(groups.map((group) => group.code)).size !== groups.length ||
+        new Set(groups.map((group) => group.area)).size !== groups.length)
+        throw new Error("Duplicate published Help area");
+    for (const group of groups)
+        if (!/^[1-9]\d{2}$/u.test(group.code) ||
+            ["900", "901"].includes(group.code) ||
+            typeof group.area !== "string" ||
+            !group.area.trim() ||
+            group.area.length > 200 ||
+            ["platform:generic", "platform:custom"].includes(group.area) ||
+            typeof group.name !== "string" ||
+            !group.name.trim() ||
+            group.name.length > 200 ||
+            !Number.isInteger(group.nextFaq) ||
+            group.nextFaq < 1 ||
+            group.nextFaq > 1000 ||
+            (group.area.startsWith("platform:")
+                ? Number(group.code) <= feed.nextGeneralCode
+                : Number(group.code) >= feed.nextModuleCode))
+            throw new Error("Invalid published Help area");
+    const canonicalFaqs = new Map(createHelpCollection(feed.records.map((record) => record.faq)).faqs.map((faq) => [faq.id, faq]));
+    const groupMap = new Map(groups.map((group) => [group.code, group]));
+    const records = feed.records
+        .map((record) => {
+        const faq = canonicalFaqs.get(record.faq.id), group = groupMap.get(faq.moduleCode);
+        if (!group ||
+            group.area !== faq.area ||
+            Number(faq.id.slice(3)) >= group.nextFaq ||
+            faq.question.length > 600 ||
+            faq.answerMarkdown.length > 100000 ||
+            faq.answerText.length > 100000 ||
+            !["dedicated_faq", "guide_question"].includes(record.sourceKind) ||
+            typeof record.pageTitle !== "string" ||
+            !record.pageTitle.trim() ||
+            record.pageTitle.length > 500 ||
+            !Number.isInteger(record.sourceLine) ||
+            record.sourceLine < 1 ||
+            record.sourceLine > 1000000 ||
+            !/^[a-f0-9]{64}$/u.test(record.sourceAnswerHash) ||
+            !Array.isArray(record.issues) ||
+            record.issues.length > 20 ||
+            record.issues.some((issue) => typeof issue !== "string" || issue.length > 500))
+            throw new Error("Invalid published Help source record");
+        if (new URL(faq.sourceUrl).hash !== `#help-faq-${faq.id}`)
+            throw new Error("Published Help anchor does not match its permanent ID");
+        return {
+            faq,
+            sourceKind: record.sourceKind,
+            pageTitle: record.pageTitle,
+            sourceLine: record.sourceLine,
+            sourceAnswerHash: record.sourceAnswerHash,
+            issues: [...record.issues],
+        };
+    })
+        .sort((a, b) => compare(a.faq.id, b.faq.id));
+    return {
+        schemaVersion: 1,
+        sourceRevision: feed.sourceRevision,
+        nextModuleCode: feed.nextModuleCode,
+        nextGeneralCode: feed.nextGeneralCode,
+        groups,
+        records,
+    };
+}
+export function createHelpPublishedSources(input) {
+    const content = publishedSourceContent({ ...input, schemaVersion: 1 });
+    return { ...content, revision: hash(content) };
+}
+export function parseHelpPublishedSources(value) {
+    const content = publishedSourceContent(value), revision = hash(content);
+    if (value.revision !== revision)
+        throw new Error("Published Help source checksum mismatch");
+    return { ...content, revision };
+}
+//# sourceMappingURL=help.js.map

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 import type { HealthResult, Logger, ModuleDefinition, ModulePermissionConfiguration, PermissionActor, GuildAccessPolicy, HelyxAccessLevel, PermissionPolicy, ServiceAccess } from "@helyx/sdk";
 export * from "./async-cleanup-stack.js";
+export * from "./help.js";
+export * from "./help-collection.js";
+export * from "./help-runtime.js";
+export * from "./help-runtime-collection.js";
+export * from "./help-retrieval.js";
+export * from "./help-direct-answer.js";
+export * from "./help-areas.js";
 export type RuntimeState = "created" | "starting" | "running" | "stopping" | "stopped" | "failed";
 export interface ModuleHealth {
     id: string;

package/dist/index.js

@@ -1,6 +1,13 @@
 import { orderModuleManifests, parseModuleManifest, } from "@helyx/module-manifest";
 import { createHash } from "node:crypto";
 export * from "./async-cleanup-stack.js";
+export * from "./help.js";
+export * from "./help-collection.js";
+export * from "./help-runtime.js";
+export * from "./help-runtime-collection.js";
+export * from "./help-retrieval.js";
+export * from "./help-direct-answer.js";
+export * from "./help-areas.js";
 export class ServiceRegistry {
     #services;
     constructor(services = new Map()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Module lifecycle and runtime registry for Helyx.",
   "keywords": [
     "helyx",
@@ -47,7 +47,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@helyx/module-manifest": ">=0.13.0 <0.14.0",
-    "@helyx/sdk": ">=0.16.0 <0.17.0"
+    "@helyx/module-manifest": ">=0.14.0 <0.15.0",
+    "@helyx/sdk": ">=0.17.0 <0.18.0"
   }
 }