@aigne/afs-index 1.12.0-beta.5

package/dist/extraction/field-map.cjs

@@ -0,0 +1,162 @@
+const require_host = require('../text/host.cjs');
+let ufo = require("ufo");
+
+//#region src/extraction/field-map.ts
+function tokenizePath(path) {
+	const segments = [];
+	let rest = path;
+	while (rest.length > 0) if (rest.startsWith("[*]")) {
+		segments.push({ type: "wildcard" });
+		rest = rest.slice(3);
+	} else if (rest.startsWith(".")) {
+		rest = rest.slice(1);
+		const m = rest.match(/^([^.[*\]]+)/);
+		if (!m) break;
+		segments.push({
+			type: "field",
+			name: m[1]
+		});
+		rest = rest.slice(m[1].length);
+	} else break;
+	return segments;
+}
+function evalSegments(current, segments) {
+	if (segments.length === 0) return current !== void 0 && current !== null ? [current] : [];
+	const [seg, ...rest] = segments;
+	if (!seg) return [];
+	if (seg.type === "field") {
+		if (typeof current !== "object" || current === null || Array.isArray(current)) return [];
+		const next = current[seg.name];
+		if (next === void 0 || next === null) return [];
+		return evalSegments(next, rest);
+	}
+	if (seg.type === "wildcard") {
+		if (!Array.isArray(current)) return [];
+		return current.flatMap((item) => evalSegments(item, rest));
+	}
+	return [];
+}
+/**
+* Evaluate a JSONPath expression against a JSON value.
+* Returns an array of all matched values (may be empty).
+* Expressions must start with `$`; otherwise returns [].
+*/
+function evalJsonPath(obj, expr) {
+	if (!expr.startsWith("$")) return [];
+	return evalSegments(obj, tokenizePath(expr.slice(1)));
+}
+const HOST_EXPR_RE = /^host\((.+)\)$/;
+function extractHost(url) {
+	try {
+		const u = new URL(url);
+		return u.hostname ? require_host.normalizeHost(u.hostname) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Evaluate a single field expression (JSONPath or `host()`) against a JSON value.
+* Returns an array of non-empty string values.
+*/
+function evalFieldExpr(obj, expr) {
+	const hostMatch = expr.match(HOST_EXPR_RE);
+	if (hostMatch) return evalJsonPath(obj, hostMatch[1].trim()).flatMap((url) => {
+		if (typeof url !== "string") return [];
+		const h = extractHost(url);
+		return h ? [h] : [];
+	});
+	return evalJsonPath(obj, expr).filter((v) => typeof v === "string").filter((s) => s.length > 0);
+}
+/**
+* Apply a field map against a JSON document.
+* Returns a record of field name → deduplicated string values.
+* Fields with no matching values are omitted.
+*/
+function applyFieldMap(obj, fields) {
+	const result = {};
+	for (const [fieldName, exprs] of Object.entries(fields)) {
+		const values = (Array.isArray(exprs) ? exprs : [exprs]).flatMap((expr) => evalFieldExpr(obj, expr));
+		const unique = [...new Set(values)];
+		if (unique.length > 0) result[fieldName] = unique;
+	}
+	return result;
+}
+/**
+* Extract FTS summary text by evaluating one or more JSONPath expressions.
+* Values are joined with newline; empty/missing values are skipped.
+*/
+function extractSummaryText(obj, exprs) {
+	return (Array.isArray(exprs) ? exprs : [exprs]).flatMap((expr) => evalFieldExpr(obj, expr)).filter(Boolean).join("\n").trim();
+}
+/**
+* Resolve an enrich contentFile path template against the item JSON.
+*
+* Template syntax: `assets/{$.slug}/content.md` — `{$.expr}` is replaced
+* with the first string value from the expression.
+*
+* Returns null if:
+* - No `{$.field}` placeholders resolve to a value
+* - Resolved path would traverse `..` (injection guard)
+*/
+function resolveEnrichPath(template, itemJson) {
+	const resolved = template.replace(/\{(\$[^}]+)\}/g, (_, expr) => {
+		return evalFieldExpr(itemJson, expr.trim())[0] ?? "";
+	});
+	if (!resolved) return null;
+	if (resolved.split("/").some((s) => s === "..")) return null;
+	return resolved;
+}
+/**
+* Perform the `enrich.contentFile` second hop: resolve the sidecar path
+* template against the item JSON (via {@link resolveEnrichPath}), read it
+* through the AFS handle, truncate to `maxChars`, and append the result to
+* `baseSummary`. This is the real two-hop read the field-map engine promises
+* (read item.json → derive a path → read the sidecar) — kept AFS-Only: the
+* only I/O here is `afs.read()`.
+*
+* Fails soft in every case — returns `baseSummary` unchanged when:
+* - `enrich.contentFile` is not configured
+* - the path template can't be resolved (missing placeholder value, or `..`
+*   traversal after resolution — {@link resolveEnrichPath} returns null)
+* - the sidecar doesn't exist or isn't readable (`afs.read` throws or
+*   returns no string content)
+*
+* Path assembly uses the real two-argument `joinURL(base, relative)` form
+* (not the single-arg passthrough) so the scope and the resolved relative
+* path are joined with correct slash normalization.
+*/
+async function applyEnrichContentFile(params) {
+	const { afs, itemJson, baseSummary, enrich, scope } = params;
+	const contentFile = enrich?.contentFile;
+	if (!contentFile) return baseSummary;
+	const relative = resolveEnrichPath(contentFile.path, itemJson);
+	if (!relative) return baseSummary;
+	const sidecarPath = (0, ufo.joinURL)(scope ?? "/", relative);
+	try {
+		const content = (await afs.read?.(sidecarPath))?.data?.content;
+		if (typeof content !== "string" || content.length === 0) return baseSummary;
+		const enriched = contentFile.maxChars != null ? truncateToMaxChars(content, contentFile.maxChars) : content;
+		return baseSummary ? `${baseSummary}\n${enriched}` : enriched;
+	} catch {
+		return baseSummary;
+	}
+}
+/**
+* Truncate a string to at most `maxChars` characters.
+* Truncation happens at a word boundary if possible, otherwise at the hard limit.
+*/
+function truncateToMaxChars(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	const cut = text.slice(0, maxChars);
+	const lastSpace = cut.lastIndexOf(" ");
+	return lastSpace > maxChars * .8 ? cut.slice(0, lastSpace) : cut;
+}
+
+//#endregion
+exports.applyEnrichContentFile = applyEnrichContentFile;
+exports.applyFieldMap = applyFieldMap;
+exports.evalFieldExpr = evalFieldExpr;
+exports.evalJsonPath = evalJsonPath;
+exports.extractSummaryText = extractSummaryText;
+exports.resolveEnrichPath = resolveEnrichPath;
+exports.truncateToMaxChars = truncateToMaxChars;

package/dist/extraction/field-map.d.cts

@@ -0,0 +1,70 @@
+import { AFSRoot, IndexEnrich } from "@aigne/afs";
+
+//#region src/extraction/field-map.d.ts
+/**
+ * Evaluate a JSONPath expression against a JSON value.
+ * Returns an array of all matched values (may be empty).
+ * Expressions must start with `$`; otherwise returns [].
+ */
+declare function evalJsonPath(obj: unknown, expr: string): unknown[];
+/**
+ * Evaluate a single field expression (JSONPath or `host()`) against a JSON value.
+ * Returns an array of non-empty string values.
+ */
+declare function evalFieldExpr(obj: unknown, expr: string): string[];
+/**
+ * Apply a field map against a JSON document.
+ * Returns a record of field name → deduplicated string values.
+ * Fields with no matching values are omitted.
+ */
+declare function applyFieldMap(obj: unknown, fields: Record<string, string | string[]>): Record<string, string[]>;
+/**
+ * Extract FTS summary text by evaluating one or more JSONPath expressions.
+ * Values are joined with newline; empty/missing values are skipped.
+ */
+declare function extractSummaryText(obj: unknown, exprs: string | string[]): string;
+/**
+ * Resolve an enrich contentFile path template against the item JSON.
+ *
+ * Template syntax: `assets/{$.slug}/content.md` — `{$.expr}` is replaced
+ * with the first string value from the expression.
+ *
+ * Returns null if:
+ * - No `{$.field}` placeholders resolve to a value
+ * - Resolved path would traverse `..` (injection guard)
+ */
+declare function resolveEnrichPath(template: string, itemJson: Record<string, unknown>): string | null;
+/**
+ * Perform the `enrich.contentFile` second hop: resolve the sidecar path
+ * template against the item JSON (via {@link resolveEnrichPath}), read it
+ * through the AFS handle, truncate to `maxChars`, and append the result to
+ * `baseSummary`. This is the real two-hop read the field-map engine promises
+ * (read item.json → derive a path → read the sidecar) — kept AFS-Only: the
+ * only I/O here is `afs.read()`.
+ *
+ * Fails soft in every case — returns `baseSummary` unchanged when:
+ * - `enrich.contentFile` is not configured
+ * - the path template can't be resolved (missing placeholder value, or `..`
+ *   traversal after resolution — {@link resolveEnrichPath} returns null)
+ * - the sidecar doesn't exist or isn't readable (`afs.read` throws or
+ *   returns no string content)
+ *
+ * Path assembly uses the real two-argument `joinURL(base, relative)` form
+ * (not the single-arg passthrough) so the scope and the resolved relative
+ * path are joined with correct slash normalization.
+ */
+declare function applyEnrichContentFile(params: {
+  /** AFS handle used for the second-hop read. Only `read()` is used (AFS-Only). */afs: Pick<AFSRoot, "read">; /** The item JSON the field map was extracted from (and enrich path is templated against). */
+  itemJson: Record<string, unknown>; /** Summary text already extracted via `extractSummaryText`, to append to. */
+  baseSummary: string; /** The domain's `enrich` config (from `BlockletIndexDomain.enrich`). */
+  enrich: IndexEnrich | undefined; /** Base path the resolved relative sidecar path is joined against (e.g. the domain's `scope`, "/user"). */
+  scope?: string;
+}): Promise<string>;
+/**
+ * Truncate a string to at most `maxChars` characters.
+ * Truncation happens at a word boundary if possible, otherwise at the hard limit.
+ */
+declare function truncateToMaxChars(text: string, maxChars: number): string;
+//#endregion
+export { applyEnrichContentFile, applyFieldMap, evalFieldExpr, evalJsonPath, extractSummaryText, resolveEnrichPath, truncateToMaxChars };
+//# sourceMappingURL=field-map.d.cts.map

package/dist/extraction/field-map.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-map.d.cts","names":[],"sources":["../../src/extraction/field-map.ts"],"mappings":";;;;;;;;iBAuEgB,YAAA,CAAa,GAAA,WAAc,IAAA;;;;;iBA6B3B,aAAA,CAAc,GAAA,WAAc,IAAA;;;;;;iBAwB5B,aAAA,CACd,GAAA,WACA,MAAA,EAAQ,MAAA,8BACP,MAAA;;;AA0EH;;iBAzDgB,kBAAA,CAAmB,GAAA,WAAc,KAAA;;;;;;;;;;;iBAgBjC,iBAAA,CACd,QAAA,UACA,QAAA,EAAU,MAAA;;;;;;;;;;AA8EZ;;;;;;;;;;iBAvCsB,sBAAA,CAAuB,MAAA;mFAE3C,GAAA,EAAK,IAAA,CAAK,OAAA;EAEV,QAAA,EAAU,MAAA;EAEV,WAAA;EAEA,MAAA,EAAQ,WAAA;EAER,KAAA;AAAA,IACE,OAAA;;;;;iBA4BY,kBAAA,CAAmB,IAAA,UAAc,QAAA"}

package/dist/extraction/field-map.d.mts

@@ -0,0 +1,70 @@
+import { AFSRoot, IndexEnrich } from "@aigne/afs";
+
+//#region src/extraction/field-map.d.ts
+/**
+ * Evaluate a JSONPath expression against a JSON value.
+ * Returns an array of all matched values (may be empty).
+ * Expressions must start with `$`; otherwise returns [].
+ */
+declare function evalJsonPath(obj: unknown, expr: string): unknown[];
+/**
+ * Evaluate a single field expression (JSONPath or `host()`) against a JSON value.
+ * Returns an array of non-empty string values.
+ */
+declare function evalFieldExpr(obj: unknown, expr: string): string[];
+/**
+ * Apply a field map against a JSON document.
+ * Returns a record of field name → deduplicated string values.
+ * Fields with no matching values are omitted.
+ */
+declare function applyFieldMap(obj: unknown, fields: Record<string, string | string[]>): Record<string, string[]>;
+/**
+ * Extract FTS summary text by evaluating one or more JSONPath expressions.
+ * Values are joined with newline; empty/missing values are skipped.
+ */
+declare function extractSummaryText(obj: unknown, exprs: string | string[]): string;
+/**
+ * Resolve an enrich contentFile path template against the item JSON.
+ *
+ * Template syntax: `assets/{$.slug}/content.md` — `{$.expr}` is replaced
+ * with the first string value from the expression.
+ *
+ * Returns null if:
+ * - No `{$.field}` placeholders resolve to a value
+ * - Resolved path would traverse `..` (injection guard)
+ */
+declare function resolveEnrichPath(template: string, itemJson: Record<string, unknown>): string | null;
+/**
+ * Perform the `enrich.contentFile` second hop: resolve the sidecar path
+ * template against the item JSON (via {@link resolveEnrichPath}), read it
+ * through the AFS handle, truncate to `maxChars`, and append the result to
+ * `baseSummary`. This is the real two-hop read the field-map engine promises
+ * (read item.json → derive a path → read the sidecar) — kept AFS-Only: the
+ * only I/O here is `afs.read()`.
+ *
+ * Fails soft in every case — returns `baseSummary` unchanged when:
+ * - `enrich.contentFile` is not configured
+ * - the path template can't be resolved (missing placeholder value, or `..`
+ *   traversal after resolution — {@link resolveEnrichPath} returns null)
+ * - the sidecar doesn't exist or isn't readable (`afs.read` throws or
+ *   returns no string content)
+ *
+ * Path assembly uses the real two-argument `joinURL(base, relative)` form
+ * (not the single-arg passthrough) so the scope and the resolved relative
+ * path are joined with correct slash normalization.
+ */
+declare function applyEnrichContentFile(params: {
+  /** AFS handle used for the second-hop read. Only `read()` is used (AFS-Only). */afs: Pick<AFSRoot, "read">; /** The item JSON the field map was extracted from (and enrich path is templated against). */
+  itemJson: Record<string, unknown>; /** Summary text already extracted via `extractSummaryText`, to append to. */
+  baseSummary: string; /** The domain's `enrich` config (from `BlockletIndexDomain.enrich`). */
+  enrich: IndexEnrich | undefined; /** Base path the resolved relative sidecar path is joined against (e.g. the domain's `scope`, "/user"). */
+  scope?: string;
+}): Promise<string>;
+/**
+ * Truncate a string to at most `maxChars` characters.
+ * Truncation happens at a word boundary if possible, otherwise at the hard limit.
+ */
+declare function truncateToMaxChars(text: string, maxChars: number): string;
+//#endregion
+export { applyEnrichContentFile, applyFieldMap, evalFieldExpr, evalJsonPath, extractSummaryText, resolveEnrichPath, truncateToMaxChars };
+//# sourceMappingURL=field-map.d.mts.map

package/dist/extraction/field-map.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-map.d.mts","names":[],"sources":["../../src/extraction/field-map.ts"],"mappings":";;;;;;;;iBAuEgB,YAAA,CAAa,GAAA,WAAc,IAAA;;;;;iBA6B3B,aAAA,CAAc,GAAA,WAAc,IAAA;;;;;;iBAwB5B,aAAA,CACd,GAAA,WACA,MAAA,EAAQ,MAAA,8BACP,MAAA;;;AA0EH;;iBAzDgB,kBAAA,CAAmB,GAAA,WAAc,KAAA;;;;;;;;;;;iBAgBjC,iBAAA,CACd,QAAA,UACA,QAAA,EAAU,MAAA;;;;;;;;;;AA8EZ;;;;;;;;;;iBAvCsB,sBAAA,CAAuB,MAAA;mFAE3C,GAAA,EAAK,IAAA,CAAK,OAAA;EAEV,QAAA,EAAU,MAAA;EAEV,WAAA;EAEA,MAAA,EAAQ,WAAA;EAER,KAAA;AAAA,IACE,OAAA;;;;;iBA4BY,kBAAA,CAAmB,IAAA,UAAc,QAAA"}

package/dist/extraction/field-map.mjs

@@ -0,0 +1,157 @@
+import { normalizeHost } from "../text/host.mjs";
+import { joinURL } from "ufo";
+
+//#region src/extraction/field-map.ts
+function tokenizePath(path) {
+	const segments = [];
+	let rest = path;
+	while (rest.length > 0) if (rest.startsWith("[*]")) {
+		segments.push({ type: "wildcard" });
+		rest = rest.slice(3);
+	} else if (rest.startsWith(".")) {
+		rest = rest.slice(1);
+		const m = rest.match(/^([^.[*\]]+)/);
+		if (!m) break;
+		segments.push({
+			type: "field",
+			name: m[1]
+		});
+		rest = rest.slice(m[1].length);
+	} else break;
+	return segments;
+}
+function evalSegments(current, segments) {
+	if (segments.length === 0) return current !== void 0 && current !== null ? [current] : [];
+	const [seg, ...rest] = segments;
+	if (!seg) return [];
+	if (seg.type === "field") {
+		if (typeof current !== "object" || current === null || Array.isArray(current)) return [];
+		const next = current[seg.name];
+		if (next === void 0 || next === null) return [];
+		return evalSegments(next, rest);
+	}
+	if (seg.type === "wildcard") {
+		if (!Array.isArray(current)) return [];
+		return current.flatMap((item) => evalSegments(item, rest));
+	}
+	return [];
+}
+/**
+* Evaluate a JSONPath expression against a JSON value.
+* Returns an array of all matched values (may be empty).
+* Expressions must start with `$`; otherwise returns [].
+*/
+function evalJsonPath(obj, expr) {
+	if (!expr.startsWith("$")) return [];
+	return evalSegments(obj, tokenizePath(expr.slice(1)));
+}
+const HOST_EXPR_RE = /^host\((.+)\)$/;
+function extractHost(url) {
+	try {
+		const u = new URL(url);
+		return u.hostname ? normalizeHost(u.hostname) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Evaluate a single field expression (JSONPath or `host()`) against a JSON value.
+* Returns an array of non-empty string values.
+*/
+function evalFieldExpr(obj, expr) {
+	const hostMatch = expr.match(HOST_EXPR_RE);
+	if (hostMatch) return evalJsonPath(obj, hostMatch[1].trim()).flatMap((url) => {
+		if (typeof url !== "string") return [];
+		const h = extractHost(url);
+		return h ? [h] : [];
+	});
+	return evalJsonPath(obj, expr).filter((v) => typeof v === "string").filter((s) => s.length > 0);
+}
+/**
+* Apply a field map against a JSON document.
+* Returns a record of field name → deduplicated string values.
+* Fields with no matching values are omitted.
+*/
+function applyFieldMap(obj, fields) {
+	const result = {};
+	for (const [fieldName, exprs] of Object.entries(fields)) {
+		const values = (Array.isArray(exprs) ? exprs : [exprs]).flatMap((expr) => evalFieldExpr(obj, expr));
+		const unique = [...new Set(values)];
+		if (unique.length > 0) result[fieldName] = unique;
+	}
+	return result;
+}
+/**
+* Extract FTS summary text by evaluating one or more JSONPath expressions.
+* Values are joined with newline; empty/missing values are skipped.
+*/
+function extractSummaryText(obj, exprs) {
+	return (Array.isArray(exprs) ? exprs : [exprs]).flatMap((expr) => evalFieldExpr(obj, expr)).filter(Boolean).join("\n").trim();
+}
+/**
+* Resolve an enrich contentFile path template against the item JSON.
+*
+* Template syntax: `assets/{$.slug}/content.md` — `{$.expr}` is replaced
+* with the first string value from the expression.
+*
+* Returns null if:
+* - No `{$.field}` placeholders resolve to a value
+* - Resolved path would traverse `..` (injection guard)
+*/
+function resolveEnrichPath(template, itemJson) {
+	const resolved = template.replace(/\{(\$[^}]+)\}/g, (_, expr) => {
+		return evalFieldExpr(itemJson, expr.trim())[0] ?? "";
+	});
+	if (!resolved) return null;
+	if (resolved.split("/").some((s) => s === "..")) return null;
+	return resolved;
+}
+/**
+* Perform the `enrich.contentFile` second hop: resolve the sidecar path
+* template against the item JSON (via {@link resolveEnrichPath}), read it
+* through the AFS handle, truncate to `maxChars`, and append the result to
+* `baseSummary`. This is the real two-hop read the field-map engine promises
+* (read item.json → derive a path → read the sidecar) — kept AFS-Only: the
+* only I/O here is `afs.read()`.
+*
+* Fails soft in every case — returns `baseSummary` unchanged when:
+* - `enrich.contentFile` is not configured
+* - the path template can't be resolved (missing placeholder value, or `..`
+*   traversal after resolution — {@link resolveEnrichPath} returns null)
+* - the sidecar doesn't exist or isn't readable (`afs.read` throws or
+*   returns no string content)
+*
+* Path assembly uses the real two-argument `joinURL(base, relative)` form
+* (not the single-arg passthrough) so the scope and the resolved relative
+* path are joined with correct slash normalization.
+*/
+async function applyEnrichContentFile(params) {
+	const { afs, itemJson, baseSummary, enrich, scope } = params;
+	const contentFile = enrich?.contentFile;
+	if (!contentFile) return baseSummary;
+	const relative = resolveEnrichPath(contentFile.path, itemJson);
+	if (!relative) return baseSummary;
+	const sidecarPath = joinURL(scope ?? "/", relative);
+	try {
+		const content = (await afs.read?.(sidecarPath))?.data?.content;
+		if (typeof content !== "string" || content.length === 0) return baseSummary;
+		const enriched = contentFile.maxChars != null ? truncateToMaxChars(content, contentFile.maxChars) : content;
+		return baseSummary ? `${baseSummary}\n${enriched}` : enriched;
+	} catch {
+		return baseSummary;
+	}
+}
+/**
+* Truncate a string to at most `maxChars` characters.
+* Truncation happens at a word boundary if possible, otherwise at the hard limit.
+*/
+function truncateToMaxChars(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	const cut = text.slice(0, maxChars);
+	const lastSpace = cut.lastIndexOf(" ");
+	return lastSpace > maxChars * .8 ? cut.slice(0, lastSpace) : cut;
+}
+
+//#endregion
+export { applyEnrichContentFile, applyFieldMap, evalFieldExpr, evalJsonPath, extractSummaryText, resolveEnrichPath, truncateToMaxChars };
+//# sourceMappingURL=field-map.mjs.map

package/dist/extraction/field-map.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-map.mjs","names":[],"sources":["../../src/extraction/field-map.ts"],"sourcesContent":["/**\n * Field-map extraction engine — evaluates JSONPath expressions and the\n * `host()` built-in against a JSON document to produce anchor values and\n * FTS summary text.\n *\n * JSONPath subset supported:\n *   $.field           — top-level field\n *   $.a.b             — nested field\n *   $.array[*]        — all elements of an array field\n *   $.a.b[*]          — all elements of a nested array\n *   $.a[*].b          — field access on each array element\n *\n * Built-in:\n *   host($.url)       — extracts the hostname from a URL field value\n *\n * All other expressions return no values (no throw).\n */\nimport type { AFSRoot, IndexEnrich } from \"@aigne/afs\";\nimport { joinURL } from \"ufo\";\nimport { normalizeHost } from \"../text/host.js\";\n\n// ── JSONPath evaluator ────────────────────────────────────────────────────────\n\ntype Segment = { type: \"field\"; name: string } | { type: \"wildcard\" };\n\nfunction tokenizePath(path: string): Segment[] {\n  const segments: Segment[] = [];\n  let rest = path;\n  while (rest.length > 0) {\n    if (rest.startsWith(\"[*]\")) {\n      segments.push({ type: \"wildcard\" });\n      rest = rest.slice(3);\n    } else if (rest.startsWith(\".\")) {\n      rest = rest.slice(1);\n      const m = rest.match(/^([^.[*\\]]+)/);\n      if (!m) break;\n      segments.push({ type: \"field\", name: m[1]! });\n      rest = rest.slice(m[1]!.length);\n    } else {\n      break;\n    }\n  }\n  return segments;\n}\n\nfunction evalSegments(current: unknown, segments: Segment[]): unknown[] {\n  if (segments.length === 0) return current !== undefined && current !== null ? [current] : [];\n\n  const [seg, ...rest] = segments;\n  if (!seg) return [];\n\n  if (seg.type === \"field\") {\n    if (typeof current !== \"object\" || current === null || Array.isArray(current)) return [];\n    const next = (current as Record<string, unknown>)[seg.name];\n    if (next === undefined || next === null) return [];\n    return evalSegments(next, rest);\n  }\n\n  if (seg.type === \"wildcard\") {\n    if (!Array.isArray(current)) return [];\n    return current.flatMap((item) => evalSegments(item, rest));\n  }\n\n  return [];\n}\n\n/**\n * Evaluate a JSONPath expression against a JSON value.\n * Returns an array of all matched values (may be empty).\n * Expressions must start with `$`; otherwise returns [].\n */\nexport function evalJsonPath(obj: unknown, expr: string): unknown[] {\n  if (!expr.startsWith(\"$\")) return [];\n  const path = expr.slice(1);\n  const segments = tokenizePath(path);\n  return evalSegments(obj, segments);\n}\n\n// ── host() built-in ───────────────────────────────────────────────────────────\n\nconst HOST_EXPR_RE = /^host\\((.+)\\)$/;\n\nfunction extractHost(url: string): string | null {\n  try {\n    const u = new URL(url);\n    // Canonicalize at the source so the `site` anchor value, its generated\n    // anchor key, and the FTS summary text all agree on one host form —\n    // `www.example.com` and `example.com` collapse to `example.com` (#1249).\n    return u.hostname ? normalizeHost(u.hostname) : null;\n  } catch {\n    return null;\n  }\n}\n\n// ── Field expression evaluator ────────────────────────────────────────────────\n\n/**\n * Evaluate a single field expression (JSONPath or `host()`) against a JSON value.\n * Returns an array of non-empty string values.\n */\nexport function evalFieldExpr(obj: unknown, expr: string): string[] {\n  const hostMatch = expr.match(HOST_EXPR_RE);\n  if (hostMatch) {\n    const innerExpr = hostMatch[1]!.trim();\n    const urls = evalJsonPath(obj, innerExpr);\n    return urls.flatMap((url) => {\n      if (typeof url !== \"string\") return [];\n      const h = extractHost(url);\n      return h ? [h] : [];\n    });\n  }\n\n  return evalJsonPath(obj, expr)\n    .filter((v): v is string => typeof v === \"string\")\n    .filter((s) => s.length > 0);\n}\n\n// ── Public API ────────────────────────────────────────────────────────────────\n\n/**\n * Apply a field map against a JSON document.\n * Returns a record of field name → deduplicated string values.\n * Fields with no matching values are omitted.\n */\nexport function applyFieldMap(\n  obj: unknown,\n  fields: Record<string, string | string[]>,\n): Record<string, string[]> {\n  const result: Record<string, string[]> = {};\n  for (const [fieldName, exprs] of Object.entries(fields)) {\n    const exprList = Array.isArray(exprs) ? exprs : [exprs];\n    const values = exprList.flatMap((expr) => evalFieldExpr(obj, expr));\n    const unique = [...new Set(values)];\n    if (unique.length > 0) {\n      result[fieldName] = unique;\n    }\n  }\n  return result;\n}\n\n/**\n * Extract FTS summary text by evaluating one or more JSONPath expressions.\n * Values are joined with newline; empty/missing values are skipped.\n */\nexport function extractSummaryText(obj: unknown, exprs: string | string[]): string {\n  const exprList = Array.isArray(exprs) ? exprs : [exprs];\n  const texts = exprList.flatMap((expr) => evalFieldExpr(obj, expr));\n  return texts.filter(Boolean).join(\"\\n\").trim();\n}\n\n/**\n * Resolve an enrich contentFile path template against the item JSON.\n *\n * Template syntax: `assets/{$.slug}/content.md` — `{$.expr}` is replaced\n * with the first string value from the expression.\n *\n * Returns null if:\n * - No `{$.field}` placeholders resolve to a value\n * - Resolved path would traverse `..` (injection guard)\n */\nexport function resolveEnrichPath(\n  template: string,\n  itemJson: Record<string, unknown>,\n): string | null {\n  const resolved = template.replace(/\\{(\\$[^}]+)\\}/g, (_, expr: string) => {\n    const values = evalFieldExpr(itemJson, expr.trim());\n    return values[0] ?? \"\";\n  });\n\n  if (!resolved) return null;\n\n  const segments = resolved.split(\"/\");\n  if (segments.some((s) => s === \"..\")) return null;\n\n  // `resolved` is already a bare relative path (no base to join against here\n  // — the base/scope is only known at the call site, see\n  // `applyEnrichContentFile`). A single-arg `joinURL(resolved)` is a no-op\n  // passthrough, so return the string directly instead of the misleading\n  // decorative call.\n  return resolved;\n}\n\n/**\n * Perform the `enrich.contentFile` second hop: resolve the sidecar path\n * template against the item JSON (via {@link resolveEnrichPath}), read it\n * through the AFS handle, truncate to `maxChars`, and append the result to\n * `baseSummary`. This is the real two-hop read the field-map engine promises\n * (read item.json → derive a path → read the sidecar) — kept AFS-Only: the\n * only I/O here is `afs.read()`.\n *\n * Fails soft in every case — returns `baseSummary` unchanged when:\n * - `enrich.contentFile` is not configured\n * - the path template can't be resolved (missing placeholder value, or `..`\n *   traversal after resolution — {@link resolveEnrichPath} returns null)\n * - the sidecar doesn't exist or isn't readable (`afs.read` throws or\n *   returns no string content)\n *\n * Path assembly uses the real two-argument `joinURL(base, relative)` form\n * (not the single-arg passthrough) so the scope and the resolved relative\n * path are joined with correct slash normalization.\n */\nexport async function applyEnrichContentFile(params: {\n  /** AFS handle used for the second-hop read. Only `read()` is used (AFS-Only). */\n  afs: Pick<AFSRoot, \"read\">;\n  /** The item JSON the field map was extracted from (and enrich path is templated against). */\n  itemJson: Record<string, unknown>;\n  /** Summary text already extracted via `extractSummaryText`, to append to. */\n  baseSummary: string;\n  /** The domain's `enrich` config (from `BlockletIndexDomain.enrich`). */\n  enrich: IndexEnrich | undefined;\n  /** Base path the resolved relative sidecar path is joined against (e.g. the domain's `scope`, \"/user\"). */\n  scope?: string;\n}): Promise<string> {\n  const { afs, itemJson, baseSummary, enrich, scope } = params;\n  const contentFile = enrich?.contentFile;\n  if (!contentFile) return baseSummary;\n\n  const relative = resolveEnrichPath(contentFile.path, itemJson);\n  if (!relative) return baseSummary;\n\n  const sidecarPath = joinURL(scope ?? \"/\", relative);\n\n  try {\n    const result = await afs.read?.(sidecarPath);\n    const content = result?.data?.content;\n    if (typeof content !== \"string\" || content.length === 0) return baseSummary;\n\n    const enriched =\n      contentFile.maxChars != null ? truncateToMaxChars(content, contentFile.maxChars) : content;\n\n    return baseSummary ? `${baseSummary}\\n${enriched}` : enriched;\n  } catch {\n    return baseSummary;\n  }\n}\n\n/**\n * Truncate a string to at most `maxChars` characters.\n * Truncation happens at a word boundary if possible, otherwise at the hard limit.\n */\nexport function truncateToMaxChars(text: string, maxChars: number): string {\n  if (text.length <= maxChars) return text;\n  const cut = text.slice(0, maxChars);\n  const lastSpace = cut.lastIndexOf(\" \");\n  return lastSpace > maxChars * 0.8 ? cut.slice(0, lastSpace) : cut;\n}\n"],"mappings":"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"}

package/dist/extraction/manager.cjs

@@ -0,0 +1,74 @@
+
+//#region src/extraction/manager.ts
+var ExtractorManager = class {
+	registrations = /* @__PURE__ */ new Map();
+	/**
+	* Register an extractor for a domain.
+	* @param domain - Domain name this extractor serves
+	* @param registration - Extractor configuration
+	*/
+	register(domain, registration) {
+		this.registrations.set(domain, registration);
+	}
+	/**
+	* Unregister an extractor for a domain.
+	*/
+	unregister(domain) {
+		this.registrations.delete(domain);
+	}
+	/**
+	* Find the first extractor whose scope matches the given path.
+	* @returns [domainName, registration] or undefined if no match
+	*/
+	findForPath(path) {
+		for (const [domain, reg] of this.registrations) if (path.startsWith(reg.scope)) return [domain, reg];
+	}
+	/**
+	* Dispatch extraction for a path using the matching extractor.
+	* Calls the extractor's AFS exec endpoint and returns the result.
+	*
+	* @returns ExtractionResult or null if no extractor matched or extraction failed
+	*/
+	async extract(path, root) {
+		const match = this.findForPath(path);
+		if (!match) return null;
+		const [domain, reg] = match;
+		if (!reg.extractor || !root.exec) return null;
+		try {
+			const execResult = await root.exec(reg.extractor, { path }, {});
+			if (!execResult.success || !execResult.data) return null;
+			const data = execResult.data;
+			return {
+				domain,
+				result: {
+					anchors: data.anchors ?? [],
+					summary: data.summary,
+					embedding: data.embedding
+				}
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* List all registered extractors.
+	*/
+	list() {
+		return this.registrations;
+	}
+	/**
+	* Check if any extractors are registered.
+	*/
+	get hasRegistrations() {
+		return this.registrations.size > 0;
+	}
+	/**
+	* Clear all registrations.
+	*/
+	clear() {
+		this.registrations.clear();
+	}
+};
+
+//#endregion
+exports.ExtractorManager = ExtractorManager;

package/dist/extraction/manager.d.cts

@@ -0,0 +1,47 @@
+import { ExtractionResult, ExtractorRegistration } from "../types.cjs";
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/extraction/manager.d.ts
+declare class ExtractorManager {
+  private readonly registrations;
+  /**
+   * Register an extractor for a domain.
+   * @param domain - Domain name this extractor serves
+   * @param registration - Extractor configuration
+   */
+  register(domain: string, registration: ExtractorRegistration): void;
+  /**
+   * Unregister an extractor for a domain.
+   */
+  unregister(domain: string): void;
+  /**
+   * Find the first extractor whose scope matches the given path.
+   * @returns [domainName, registration] or undefined if no match
+   */
+  findForPath(path: string): [string, ExtractorRegistration] | undefined;
+  /**
+   * Dispatch extraction for a path using the matching extractor.
+   * Calls the extractor's AFS exec endpoint and returns the result.
+   *
+   * @returns ExtractionResult or null if no extractor matched or extraction failed
+   */
+  extract(path: string, root: AFSRoot): Promise<{
+    domain: string;
+    result: ExtractionResult;
+  } | null>;
+  /**
+   * List all registered extractors.
+   */
+  list(): ReadonlyMap<string, ExtractorRegistration>;
+  /**
+   * Check if any extractors are registered.
+   */
+  get hasRegistrations(): boolean;
+  /**
+   * Clear all registrations.
+   */
+  clear(): void;
+}
+//#endregion
+export { ExtractorManager };
+//# sourceMappingURL=manager.d.cts.map

package/dist/extraction/manager.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.cts","names":[],"sources":["../../src/extraction/manager.ts"],"mappings":";;;;cAUa,gBAAA;EAAA,iBACM,aAAA;EAwCd;;;;;EAjCH,QAAA,CAAS,MAAA,UAAgB,YAAA,EAAc,qBAAA;EAAvC;;;EAOA,UAAA,CAAW,MAAA;EAAX;;;;EAQA,WAAA,CAAY,IAAA,oBAAwB,qBAAA;EAe9B;;;;;;EAAA,OAAA,CACJ,IAAA,UACA,IAAA,EAAM,OAAA,GACL,OAAA;IAAU,MAAA;IAAgB,MAAA,EAAQ,gBAAA;EAAA;EAgCT;;;EAA5B,IAAA,CAAA,GAAQ,WAAA,SAAoB,qBAAA;EAcvB;;;EAAA,IAPD,gBAAA,CAAA;;;;EAOJ,KAAA,CAAA;AAAA"}

package/dist/extraction/manager.d.mts

@@ -0,0 +1,47 @@
+import { ExtractionResult, ExtractorRegistration } from "../types.mjs";
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/extraction/manager.d.ts
+declare class ExtractorManager {
+  private readonly registrations;
+  /**
+   * Register an extractor for a domain.
+   * @param domain - Domain name this extractor serves
+   * @param registration - Extractor configuration
+   */
+  register(domain: string, registration: ExtractorRegistration): void;
+  /**
+   * Unregister an extractor for a domain.
+   */
+  unregister(domain: string): void;
+  /**
+   * Find the first extractor whose scope matches the given path.
+   * @returns [domainName, registration] or undefined if no match
+   */
+  findForPath(path: string): [string, ExtractorRegistration] | undefined;
+  /**
+   * Dispatch extraction for a path using the matching extractor.
+   * Calls the extractor's AFS exec endpoint and returns the result.
+   *
+   * @returns ExtractionResult or null if no extractor matched or extraction failed
+   */
+  extract(path: string, root: AFSRoot): Promise<{
+    domain: string;
+    result: ExtractionResult;
+  } | null>;
+  /**
+   * List all registered extractors.
+   */
+  list(): ReadonlyMap<string, ExtractorRegistration>;
+  /**
+   * Check if any extractors are registered.
+   */
+  get hasRegistrations(): boolean;
+  /**
+   * Clear all registrations.
+   */
+  clear(): void;
+}
+//#endregion
+export { ExtractorManager };
+//# sourceMappingURL=manager.d.mts.map

package/dist/extraction/manager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.mts","names":[],"sources":["../../src/extraction/manager.ts"],"mappings":";;;;cAUa,gBAAA;EAAA,iBACM,aAAA;EAwCd;;;;;EAjCH,QAAA,CAAS,MAAA,UAAgB,YAAA,EAAc,qBAAA;EAAvC;;;EAOA,UAAA,CAAW,MAAA;EAAX;;;;EAQA,WAAA,CAAY,IAAA,oBAAwB,qBAAA;EAe9B;;;;;;EAAA,OAAA,CACJ,IAAA,UACA,IAAA,EAAM,OAAA,GACL,OAAA;IAAU,MAAA;IAAgB,MAAA,EAAQ,gBAAA;EAAA;EAgCT;;;EAA5B,IAAA,CAAA,GAAQ,WAAA,SAAoB,qBAAA;EAcvB;;;EAAA,IAPD,gBAAA,CAAA;;;;EAOJ,KAAA,CAAA;AAAA"}