@lupinum/ginko-content 0.1.5 → 0.2.0

package/dist/runtime/server/collection-helpers.d.ts

@@ -2,10 +2,10 @@ import type { H3Event } from 'h3';
 import type { ParsedContent } from '../../types/content';
 import type { ContentCollectionItemSurroundingsOptions, ContentCollectionNavigationOptions, ContentCollectionPageOptions, ContentCollectionRouteMetaOptions, ContentCollectionSearchSectionsOptions, ContentPageResult, ContentSearchSection } from '../../types/query';
 export declare function queryFilesystemCollectionNavigation(event: H3Event, collection: string, fieldsOrOptions?: string[] | ContentCollectionNavigationOptions): Promise<any[]>;
-export declare function queryFilesystemCollectionItemSurroundings(event: H3Event, collection: string, path: string, opts?: ContentCollectionItemSurroundingsOptions): Promise<(import("../../types").NavItem | null)[]>;
+export declare function queryFilesystemCollectionItemSurroundings(event: H3Event, collection: string, path: string, opts?: ContentCollectionItemSurroundingsOptions): Promise<(import("../../types/content").NavItem | null)[]>;
 export declare function queryFilesystemCollectionSearchSections(event: H3Event, collection: string, opts?: ContentCollectionSearchSectionsOptions): Promise<ContentSearchSection[]>;
 export declare function queryFilesystemCollectionPage<T = ParsedContent>(event: H3Event, collection: string, routeOrPath?: string, options?: ContentCollectionPageOptions): Promise<ContentPageResult<T> | null>;
-export declare function queryFilesystemCollectionRouteMeta(event: H3Event, collection: string, routeOrPath?: string, options?: ContentCollectionRouteMetaOptions): Promise<import("../../types").ContentRouteMeta | null>;
+export declare function queryFilesystemCollectionRouteMeta(event: H3Event, collection: string, routeOrPath?: string, options?: ContentCollectionRouteMetaOptions): Promise<import("../../types/query").ContentRouteMeta | null>;
 export declare const queryCollectionNavigation: typeof queryFilesystemCollectionNavigation;
 export declare const queryCollectionItemSurroundings: typeof queryFilesystemCollectionItemSurroundings;
 export declare const queryCollectionSearchSections: typeof queryFilesystemCollectionSearchSections;

package/dist/runtime/server/collection-helpers.js

@@ -1,20 +1,21 @@
 import { resolveCollectionItemSurroundingsData, resolveCollectionNavigationData, resolveCollectionPageData, resolveCollectionRouteMetaData, resolveCollectionSearchSectionsData } from "../../features/collections/resolve";
 import { resolveContentNavigation } from "./navigation-query.js";
 import { executeFilesystemContentQuery } from "./query-executor.js";
+import { createProviderNavigationQuery, createProviderQuery } from "./provider-query.js";
 import { serverQueryCollection } from "./storage.js";
 import { contentConfig } from "./storage-access.js";
 const isNotFoundError = (error) => {
   return error?.statusCode === 404;
 };
 const searchPageFields = (fields = []) => [
-  "_path",
+  "path",
   "title",
   "description",
   "body",
   ...fields
 ];
 const mergeFilterQuery = (filterQuery, locale) => {
-  const localeFilter = locale ? { _locale: locale } : void 0;
+  const localeFilter = locale ? { locale } : void 0;
   if (filterQuery && localeFilter) {
     return { $and: [filterQuery, localeFilter] };
   }
@@ -25,12 +26,15 @@ export async function queryFilesystemCollectionNavigation(event, collection, fie
   const locale = options.locale;
   return await resolveCollectionNavigationData(collection, contentConfig(), {
     ...options,
-    loadNavigation: () => resolveContentNavigation(event, {
-      collection,
-      ...options.fields?.length ? { navigationFields: options.fields } : {},
-      ...typeof options.canonical === "boolean" ? { canonical: options.canonical } : {},
-      ...locale ? { resolveLocale: { locale, fallback: true } } : {}
-    })
+    loadNavigation: () => {
+      const { query, options: navigationOptions } = createProviderNavigationQuery({
+        collection,
+        ...options.fields?.length ? { navigationFields: options.fields } : {},
+        ...typeof options.canonical === "boolean" ? { canonical: options.canonical } : {},
+        ...locale ? { resolveLocale: { locale, fallback: true } } : {}
+      });
+      return resolveContentNavigation(event, query, navigationOptions);
+    }
   });
 }
 export async function queryFilesystemCollectionItemSurroundings(event, collection, path, opts = {}) {
@@ -57,7 +61,7 @@ export async function queryFilesystemCollectionPage(event, collection, routeOrPa
     ...options,
     loadVariantPage: async (input) => {
       try {
-        const response = await executeFilesystemContentQuery(event, {
+        const response = await executeFilesystemContentQuery(event, createProviderQuery({
           collection,
           first: true,
           resolveVariant: {
@@ -65,7 +69,7 @@ export async function queryFilesystemCollectionPage(event, collection, routeOrPa
             locale: input.locale,
             fallback: input.fallback
           }
-        });
+        }).plan);
         return response.result || null;
       } catch (error) {
         if (isNotFoundError(error)) {
@@ -76,7 +80,7 @@ export async function queryFilesystemCollectionPage(event, collection, routeOrPa
     },
     loadPathPage: async (path) => {
       try {
-        return await serverQueryCollection(event, collection).where("_path", "=", path).first();
+        return await serverQueryCollection(event, collection).where("path", "=", path).first();
       } catch (error) {
         if (isNotFoundError(error)) {
           return null;

package/dist/runtime/server/index.d.ts

@@ -1,9 +1,11 @@
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors, createServerContentQueryContext } from './query-api';
-export { getCollectionPath } from '../query/routes';
+export { getCollectionPath } from '../../features/query/routes';
 export { queryCollectionsSitemapEntries } from './sitemap-provider';
-export { contentCacheHeaders, noopContentCache, vercelContentCache, type VercelContentCacheOptions } from './cache-adapters';
+export { contentCacheHeaders, noopContentCache, vercelContentCache, headersContentCache, type VercelContentCacheOptions } from './cache-adapters';
 export { clearContentCacheHint, collectContentCacheHint, getContentCacheHint } from './cache-hints';
 export { createContentProviderError } from '../../public/provider-errors';
-export { withContentCache } from '../../public/provider';
-export type { ContentCacheAdapter, ContentCacheHint, ContentCacheHintInput, ContentCacheInvalidateInput, ContentProvider, ContentProviderCapabilities, ContentProviderResult, MaybeContentProviderResult } from '../../public/provider';
+export { PROVIDER_QUERY_VERSION, toContentProviderNavigationQuery, toContentProviderQuery, withContentCache } from '../../public/provider';
+export { normalizeProviderDocument, shapeProviderDocument } from './provider-document';
+export type { ProviderDocumentInput, ShapeProviderDocumentOptions } from './provider-document';
+export type { ContentCacheAdapter, ContentCacheHint, ContentCacheHintInput, ContentCacheInvalidateInput, ContentProvider, ContentProviderCapabilities, ContentProviderNavigationOptions, ContentProviderQuery, ContentProviderResult, MaybeContentProviderResult } from '../../public/provider';
 export type { ContentProviderErrorCode } from '../../public/provider-errors';

package/dist/runtime/server/index.js

@@ -1,10 +1,11 @@
 export { one, many, paginate, backlinks, resolveOne, variants, tree, neighbors, createServerContentQueryContext } from "./query-api.js";
-export { getCollectionPath } from "../query/routes.js";
+export { getCollectionPath } from "../../features/query/routes";
 export { queryCollectionsSitemapEntries } from "./sitemap-provider.js";
 export {
   contentCacheHeaders,
   noopContentCache,
-  vercelContentCache
+  vercelContentCache,
+  headersContentCache
 } from "./cache-adapters.js";
 export {
   clearContentCacheHint,
@@ -12,4 +13,10 @@ export {
   getContentCacheHint
 } from "./cache-hints.js";
 export { createContentProviderError } from "../../public/provider-errors";
-export { withContentCache } from "../../public/provider";
+export {
+  PROVIDER_QUERY_VERSION,
+  toContentProviderNavigationQuery,
+  toContentProviderQuery,
+  withContentCache
+} from "../../public/provider";
+export { normalizeProviderDocument, shapeProviderDocument } from "./provider-document.js";

package/dist/runtime/server/middleware/agent-link-headers.js

@@ -1,6 +1,6 @@
 import { defineEventHandler, getRequestURL, setHeader } from "h3";
 import { getAgentLocales, localeFromAgentPath, resolveMarkdownForPublicRoute } from "../agent-site.js";
-import { agentRawPathForRoute, normalizeAgentRoutePath } from "../../agent-paths.js";
+import { agentRawPathForRoute, normalizeAgentRoutePath } from "../../../features/agent/agent-paths";
 import { appendResponseHeader } from "../agent-http.js";
 import { contentConfig } from "../storage-access.js";
 const shouldAdvertise = (pathname) => !pathname.startsWith("/_") && !pathname.startsWith("/api/") && !pathname.endsWith(".css") && !pathname.endsWith(".js") && !pathname.endsWith(".png") && !pathname.endsWith(".jpg") && !pathname.endsWith(".jpeg") && !pathname.endsWith(".webp") && !pathname.endsWith(".svg") && !pathname.endsWith(".ico");

package/dist/runtime/server/middleware/agent-markdown.js

@@ -7,7 +7,7 @@ import {
   resolveMarkdownForPublicRoute
 } from "../agent-site.js";
 import { acceptsMarkdown, addVaryHeader, setAgentMarkdownHeaders } from "../agent-http.js";
-import { isUnsafeAgentRoutePath, normalizeAgentRoutePath } from "../../agent-paths.js";
+import { isUnsafeAgentRoutePath, normalizeAgentRoutePath } from "../../../features/agent/agent-paths";
 const shouldSkip = (pathname) => pathname.startsWith("/_") || pathname.startsWith("/api/") || pathname.startsWith("/raw/") || pathname === "/robots.txt" || pathname === "/sitemap.xml" || pathname.endsWith(".txt") || pathname.endsWith(".xml") || pathname.endsWith(".json") || pathname.endsWith(".ico") || pathname.endsWith(".png") || pathname.endsWith(".jpg") || pathname.endsWith(".jpeg") || pathname.endsWith(".webp") || pathname.endsWith(".svg") || pathname.endsWith(".css") || pathname.endsWith(".js");
 export default defineEventHandler(async (event) => {
   const { pathname } = getRequestURL(event);

package/dist/runtime/server/navigation-query.d.ts

@@ -1,4 +1,4 @@
 import type { H3Event } from 'h3';
 import type { NavItem } from '../../types/content';
-import type { ContentQueryBuilderParams } from '../../types/query';
-export declare function resolveContentNavigation(event: H3Event, inputQuery?: ContentQueryBuilderParams): Promise<NavItem[]>;
+import type { ContentProviderNavigationOptions, ContentProviderQuery } from '../../public/provider-query';
+export declare function resolveContentNavigation(event: H3Event, query: ContentProviderQuery, navigationOptions?: ContentProviderNavigationOptions): Promise<NavItem[]>;

package/dist/runtime/server/navigation-query.js

@@ -1,3 +1,4 @@
+import { isPlanRegex } from "../../core/query/plan";
 import { resolveContentNavigationData } from "../../features/navigation/query";
 import { buildCanonicalNavigation } from "../../features/navigation/build";
 import { markCollectionNavigationRoot, projectNavigationTree } from "../../features/navigation/canonical";
@@ -7,7 +8,51 @@ import { isPreview } from "./preview.js";
 import { cacheStorage } from "./storage-access.js";
 import { createServerContentQuery } from "./storage.js";
 import { resolveLocaleChain } from "./manifest.js";
-export async function resolveContentNavigation(event, inputQuery = {}) {
+const reviveFilterValue = (value) => isPlanRegex(value) ? new RegExp(value.source, value.flags) : value;
+const conditionsToWhereCondition = (conditions) => {
+  if (!conditions.length) return {};
+  if (conditions.length === 1) return conditions[0];
+  return { $and: conditions };
+};
+const filterToWhereConditions = (filter) => {
+  switch (filter.type) {
+    case "true":
+      return [];
+    case "compare":
+      return [
+        filter.operator === "eq" ? { [filter.field]: reviveFilterValue(filter.value) } : { [filter.field]: { [`$${filter.operator}`]: reviveFilterValue(filter.value) } }
+      ];
+    case "and":
+      return filter.clauses.flatMap(filterToWhereConditions);
+    case "or":
+      return [{ $or: filter.clauses.map((clause) => conditionsToWhereCondition(filterToWhereConditions(clause))) }];
+    case "not":
+      return [{ $not: conditionsToWhereCondition(filterToWhereConditions(filter.clause)) }];
+    default:
+      throw new TypeError(`Unknown query filter node: ${filter.type}`);
+  }
+};
+const sortClausesToBuilder = (sort) => sort.map((clause) => ({
+  [clause.field]: clause.direction,
+  ...clause.locale ? { $locale: clause.locale } : {},
+  ...typeof clause.numeric === "boolean" ? { $numeric: clause.numeric } : {},
+  ...clause.caseFirst ? { $caseFirst: clause.caseFirst } : {},
+  ...clause.sensitivity ? { $sensitivity: clause.sensitivity } : {}
+}));
+const providerQueryToNavigationParams = (query, options) => {
+  const where = filterToWhereConditions(query.plan.filter);
+  const sort = sortClausesToBuilder(query.plan.sort);
+  return {
+    ...query.collection ? { collection: query.collection } : {},
+    ...where.length ? { where } : {},
+    ...sort.length ? { sort } : {},
+    ...options.resolveLocale ? { resolveLocale: options.resolveLocale } : {},
+    ...options.fields?.length ? { only: options.fields } : {},
+    ...options.canonical ? { canonical: true } : {}
+  };
+};
+export async function resolveContentNavigation(event, query, navigationOptions = {}) {
+  const inputQuery = providerQueryToNavigationParams(query, navigationOptions);
   const runtimeConfig = getContentRuntimeConfig();
   const requestedFields = [
     ...Array.isArray(inputQuery.only) ? inputQuery.only.map(String) : [],
@@ -39,18 +84,18 @@ export async function resolveContentNavigation(event, inputQuery = {}) {
       return cached;
     },
     loadLocaleNavigation: async (locale) => {
-      let contentsQuery = createServerContentQuery(event, sourceQuery).where("_partial", "=", false).where("_type", "=", "markdown").where("navigation", "!=", false);
+      let contentsQuery = createServerContentQuery(event, sourceQuery).where("partial", "=", false).where("type", "=", "markdown").where("navigation", "!=", false);
       if (locale) {
-        contentsQuery = contentsQuery.where("_locale", "=", locale);
+        contentsQuery = contentsQuery.where("locale", "=", locale);
       }
-      let dirConfigsQuery = createServerContentQuery(event).where("_navigation", "=", true).where("_partial", "=", true);
+      let dirConfigsQuery = createServerContentQuery(event).where("navigationFile", "=", true).where("partial", "=", true);
       if (locale) {
-        dirConfigsQuery = dirConfigsQuery.where("_locale", "=", locale);
+        dirConfigsQuery = dirConfigsQuery.where("locale", "=", locale);
       }
       const contents = await contentsQuery.all();
       const dirConfigs = await dirConfigsQuery.all();
       const configs = dirConfigs.reduce((accumulator, config) => {
-        accumulator[config._path || "/"] = {
+        accumulator[config.path || "/"] = {
           ...config,
           ...config.body
         };
@@ -60,7 +105,7 @@ export async function resolveContentNavigation(event, inputQuery = {}) {
       return buildCanonicalNavigation(contents, configs, [.../* @__PURE__ */ new Set([...configuredFields, ...requestedFields])]);
     },
     resolveLocaleChain,
-    localizeNavigation: async (items, locale, _fallback = [], collection, canonical) => {
+    localizeNavigation: async (items, locale, _unusedFallback = [], collection, canonical) => {
       const collectionI18n = collection ? runtimeConfig.content.collections?.[collection]?.i18n : void 0;
       const collectionLocales = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.locales : void 0;
       const collectionDefault = collectionI18n && typeof collectionI18n === "object" ? collectionI18n.defaultLocale : void 0;

package/dist/runtime/server/navigation.d.ts

@@ -1,2 +1,2 @@
 import type { ParsedContentMeta } from '../../types/content';
-export declare function createNav(contents: ParsedContentMeta[], configs: Record<string, ParsedContentMeta>): import("../../types").NavItem[];
+export declare function createNav(contents: ParsedContentMeta[], configs: Record<string, ParsedContentMeta>): import("../../types/content").NavItem[];

package/dist/runtime/server/provider-document

@@ -0,0 +1 @@
+export * from './provider-document.js'

package/dist/runtime/server/provider-document.d.ts

@@ -0,0 +1,59 @@
+import type { ContentFileMeta, ParsedContent } from '../../types/content';
+import type { ContentPageResult } from '../../types/query';
+import { type RouteMounts } from '../../features/localization/path';
+/**
+ * Minimal document a third-party provider must emit. Only `collection`,
+ * `locale`, `path` and `body` are strictly required — `id`, `canonicalKey` and
+ * `type` are derived when omitted, and `file` is optional (absent for providers
+ * with no backing file, e.g. CMS-backed documents). Any additional frontmatter
+ * fields are passed through untouched.
+ */
+export interface ProviderDocumentInput extends Record<string, unknown> {
+    /** Collection the document belongs to. */
+    collection: string;
+    /** Locale code for this concrete variant. */
+    locale: string;
+    /** Canonical (source-agnostic) route path this variant serves at. */
+    path: string;
+    /** Parsed body payload (`null` for documents with no renderable body). */
+    body: ParsedContent['body'];
+    /** Fully-qualified system id. Derived from `locale` + `path` when omitted. */
+    id?: string;
+    /**
+     * Opaque, locale-agnostic identity join key. Derived from `collection` +
+     * `path` when omitted. Never parse or render it as a URL.
+     */
+    canonicalKey?: string;
+    /** Document kind. Defaults to `'markdown'`. */
+    type?: ParsedContent['type'];
+    /** Optional file provenance. Absent for providers with no backing file. */
+    file?: ContentFileMeta;
+}
+/**
+ * Options describing the provider's locale/route configuration so core can
+ * derive the localized route envelope. For single-locale providers these can be
+ * omitted entirely.
+ */
+export interface ShapeProviderDocumentOptions {
+    /** Default locale of the site (defaults to the document's own locale). */
+    defaultLocale?: string;
+    /** All configured locales (defaults to the document's own locale). */
+    locales?: string[];
+    /** Route mount(s) for the collection, used to project localized paths. */
+    route?: string | Record<string, string>;
+    /** Pre-computed route mounts (takes precedence over `route`). */
+    routeMounts?: RouteMounts;
+}
+/**
+ * Normalize a provider's raw document into the canonical content envelope,
+ * filling in the derivable identity fields (`id`, `canonicalKey`, `type`) while
+ * leaving `file` absent unless the provider supplied it.
+ */
+export declare const normalizeProviderDocument: (input: ProviderDocumentInput) => ParsedContent;
+/**
+ * Normalize a provider's raw document and derive the full route envelope
+ * (`path`, `variants`, `localePaths`, `resolved`). The result is the canonical
+ * `ContentPageResult` route helpers return, so a provider can back its `page`,
+ * `routeMeta` and `query` methods from the minimal document set alone.
+ */
+export declare const shapeProviderDocument: <T = ParsedContent>(input: ProviderDocumentInput, options?: ShapeProviderDocumentOptions) => ContentPageResult<T>;

package/dist/runtime/server/provider-document.js

@@ -0,0 +1,48 @@
+import { normalizeRouteMounts } from "../../features/localization/path";
+import { localizePageResult } from "../../features/localization/results";
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, "");
+const extensionForType = (type) => {
+  switch (type) {
+    case "yaml":
+      return "yml";
+    case "json":
+      return "json";
+    case "csv":
+      return "csv";
+    default:
+      return "md";
+  }
+};
+export const normalizeProviderDocument = (input) => {
+  const collection = input.collection;
+  const locale = input.locale;
+  const path = input.path;
+  const type = input.type ?? "markdown";
+  const canonicalKey = input.canonicalKey ?? `${collection}:${trimSlashes(path) || "index"}`;
+  const extension = input.file?.extension ?? extensionForType(type);
+  const id = input.id ?? `content:${locale}:${trimSlashes(path).replace(/\//g, ":") || "index"}.${extension}`;
+  return {
+    ...input,
+    id,
+    collection,
+    locale,
+    path,
+    canonicalKey,
+    type,
+    ...input.file ? { file: input.file } : {},
+    body: input.body
+  };
+};
+export const shapeProviderDocument = (input, options = {}) => {
+  const document = normalizeProviderDocument(input);
+  const defaultLocale = options.defaultLocale ?? input.locale;
+  const locales = options.locales ?? [input.locale];
+  const routeMounts = options.routeMounts ?? normalizeRouteMounts(options.route, locales, defaultLocale);
+  return localizePageResult(
+    document,
+    input.locale,
+    defaultLocale,
+    locales,
+    routeMounts
+  );
+};

package/dist/runtime/server/provider-query-wire

@@ -0,0 +1 @@
+export * from './provider-query-wire.js'

package/dist/runtime/server/provider-query-wire.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Builder-params → provider-wire lowering seam.
+ *
+ * These helpers translate the internal query IR (`ContentQueryBuilderParams`,
+ * see `../../types/query-parts/transport.ts`) into the closed, JSON-pure
+ * `ContentProviderQuery` wire envelope. They live in the runtime adapter layer
+ * — NOT in the `public/` facade — because the IR is internal plumbing: keeping
+ * its name out of `src/public/` is what makes the IR "not public" while the
+ * lowering functions themselves stay part of the exported surface (re-exported
+ * from `../../public/provider-query`).
+ */
+import type { ContentQueryBuilderParams } from '../../types/query';
+import type { ContentProviderNavigationOptions, ContentProviderQuery } from '../../public/provider-query';
+export declare const PROVIDER_QUERY_VERSION: 1;
+/**
+ * Lower builder params into the wire envelope. This is the single place the
+ * builder → plan translation happens before the provider boundary; providers
+ * receive only the closed, JSON-pure plan.
+ */
+export declare const toContentProviderQuery: (params: ContentQueryBuilderParams) => ContentProviderQuery;
+/**
+ * Split builder params into the navigation wire pair (CS-5): the query plan
+ * (collection + user filter/sort) plus the navigation-only options
+ * (`fields` = `only` ∪ `navigationFields`, `canonical`, and the raw
+ * `resolveLocale`). The nav-only keys are stripped before lowering so they do
+ * not leak into the plan. Pure — the single navigation builder-params → wire
+ * seam, usable by providers and their conformance suites.
+ */
+export declare const toContentProviderNavigationQuery: (params: ContentQueryBuilderParams) => {
+    query: ContentProviderQuery;
+    options: ContentProviderNavigationOptions;
+};

package/dist/runtime/server/provider-query-wire.js

@@ -0,0 +1,27 @@
+import { lowerQueryPlan } from "../../core/query/lower";
+export const PROVIDER_QUERY_VERSION = 1;
+export const toContentProviderQuery = (params) => ({
+  v: PROVIDER_QUERY_VERSION,
+  collection: params.collection ?? null,
+  plan: lowerQueryPlan(params)
+});
+export const toContentProviderNavigationQuery = (params) => {
+  const fields = [
+    ...Array.isArray(params.only) ? params.only.map(String) : [],
+    ...Array.isArray(params.navigationFields) ? params.navigationFields.map(String) : []
+  ];
+  const canonical = params.canonical === true;
+  const resolveLocale = params.resolveLocale;
+  const planParams = { ...params };
+  delete planParams.only;
+  delete planParams.navigationFields;
+  delete planParams.canonical;
+  return {
+    query: toContentProviderQuery(planParams),
+    options: {
+      ...fields.length ? { fields } : {},
+      ...canonical ? { canonical: true } : {},
+      ...resolveLocale ? { resolveLocale } : {}
+    }
+  };
+};

package/dist/runtime/server/provider-query.d.ts

@@ -1,8 +1,21 @@
 import type { H3Event } from 'h3';
-import type { ContentCollectionMap } from '@lupinum/ginko-content';
-import type { ParsedContent } from '../../types/content';
+import type { ContentDocumentResolution, ParsedContent } from '../../types/content';
 import type { ContentQueryResponse } from '../../types/api';
-import type { CollectionQueryBuilder, ContentQueryBuilderParams, ContentQueryRequest, ResolveContentReferenceOptions } from '../../types/query';
+import type { CollectionQueryBuilder, ContentCollectionMap, ContentQueryBuilderParams, ContentQueryRequest, ResolveContentReferenceOptions } from '../../types/query';
+import { type ContentProviderQuery } from '../../public/provider-query';
+export { toContentProviderNavigationQuery as createProviderNavigationQuery } from '../../public/provider-query';
+/**
+ * Build the provider wire query (CS-5) from builder params: reject
+ * globally-invalid operators and malformed `$options` up front (so callers see
+ * a clean typed error rather than a raw lowering `TypeError`), apply the shared
+ * content-query normalization (default sort, locale injection, `fallback: true`
+ * → chain expansion), then lower to a JSON-pure `ContentQueryPlan`.
+ *
+ * This is the single builder-params → plan seam before the provider boundary.
+ * Provider-specific policy (draft hiding, limit clamps, regex rejection) lives
+ * inside each provider, applied to the plan it receives.
+ */
+export declare const createProviderQuery: (params: ContentQueryBuilderParams) => ContentProviderQuery;
 export declare const normalizeProviderQueryResult: <T>(response: ContentQueryResponse<T>) => T[];
 export declare const normalizeProviderQueryResponse: <T>(params: ContentQueryBuilderParams, response: unknown, providerName?: string) => ContentQueryResponse<T>;
 export declare const resolveProviderContentVariants: (event: H3Event, identity: string, options: ResolveContentReferenceOptions) => Promise<{
@@ -18,13 +31,9 @@ export declare const resolveProviderContentVariants: (event: H3Event, identity:
     fallback: boolean;
 } | null>;
 export declare const createServerProviderQueryFetch: <T = ParsedContent>(event: H3Event) => (query: ContentQueryRequest) => Promise<ContentQueryResponse<T>>;
-export declare const createServerContentQuery: <T = ParsedContent>(event: H3Event, query?: string | ContentQueryBuilderParams, ...pathParts: string[]) => import("@lupinum/ginko-content").ContentQueryBuilder<T>;
+export declare const createServerContentQuery: <T = ParsedContent>(event: H3Event, query?: string | ContentQueryBuilderParams, ...pathParts: string[]) => import("../../types/query").ContentQueryBuilder<T>;
 export declare function serverQueryCollection<K extends keyof ContentCollectionMap & string>(event: H3Event, collection: K): CollectionQueryBuilder<ContentCollectionMap[K]>;
 export declare function serverQueryCollection<T = ParsedContent>(event: H3Event, collection: string): CollectionQueryBuilder<T>;
 export declare const resolveContentReference: <T = ParsedContent>(event: H3Event, reference: string, options?: ResolveContentReferenceOptions) => Promise<(T & {
-    _requestedLocale?: string;
-    _resolvedLocale?: string;
-    _fallback?: boolean;
-    _availableLocales?: string[];
-    _variantPaths?: Record<string, string>;
+    resolved?: ContentDocumentResolution;
 }) | null>;

package/dist/runtime/server/provider-query.js

@@ -1,10 +1,35 @@
 import { joinURL, withLeadingSlash } from "ufo";
 import { createQuery, wrapQueryBuilder } from "../../core/query/builder";
 import { normalizeContentQueryParams } from "../../core/query/params";
+import { containsStandaloneRegexOptions, findUnsupportedQueryOperator } from "../../core/query/operators";
 import { normalizeI18nConfig, resolveRuntimeCollectionI18nConfig } from "../../features/localization/config";
+import { sortLocalesCanonically } from "../../core/content/locale";
 import { normalizeReferenceValue } from "../../core/references/resolve";
 import { getContentRuntimeConfig } from "./runtime-config.js";
 import { createContentProviderError } from "../../public/provider-errors";
+import { toContentProviderQuery } from "../../public/provider-query";
+export { toContentProviderNavigationQuery as createProviderNavigationQuery } from "../../public/provider-query";
+export const createProviderQuery = (params) => {
+  const unsupported = findUnsupportedQueryOperator(params.where);
+  if (unsupported) {
+    throw createContentProviderError("unsupported_query_operator", `Unsupported query operator: ${unsupported}`, {
+      operator: unsupported
+    });
+  }
+  if (containsStandaloneRegexOptions(params.where)) {
+    throw createContentProviderError("unsupported_query_shape", "Query operator $options requires $regex.", {
+      operator: "$options"
+    });
+  }
+  const config = getContentRuntimeConfig().content || {};
+  const normalized = normalizeContentQueryParams(params, {
+    collectionI18n: params.collection ? config.collections?.[params.collection]?.i18n : void 0,
+    defaultLocale: config.defaultLocale,
+    localeFallback: config.localeFallback,
+    includeDraftFilter: false
+  });
+  return toContentProviderQuery(normalized);
+};
 const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 const isProviderFindResponse = (response) => isObject(response) && Array.isArray(response.result) && typeof response.skip === "number" && typeof response.limit === "number" && typeof response.total === "number";
 export const normalizeProviderQueryResult = (response) => {
@@ -55,7 +80,7 @@ const identityMatchesDocument = (document, identity) => {
   if (!normalizedIdentity) {
     return false;
   }
-  return [document._canonicalKey, document._path, document.ref].filter((value) => typeof value === "string").some((value) => normalizeReferenceValue(value) === normalizedIdentity);
+  return [document.canonicalKey, document.path, document.ref].filter((value) => typeof value === "string").some((value) => normalizeReferenceValue(value) === normalizedIdentity);
 };
 export const resolveProviderContentVariants = async (event, identity, options) => {
   if (!options.collection) {
@@ -77,38 +102,43 @@ export const resolveProviderContentVariants = async (event, identity, options) =
   const provider = await getContentProvider(event);
   const baseQuery = {
     collection: options.collection,
-    only: ["_path", "_canonicalKey", "_locale", "ref", "title", "description", "body"]
+    only: ["path", "canonicalKey", "locale", "ref", "title", "description", "body"]
   };
   const documents = localesToQuery.length ? (await Promise.all(
-    localesToQuery.map(
-      async (locale) => normalizeProviderQueryResult(
-        normalizeProviderQueryResponse({
-          ...baseQuery,
-          resolveLocale: { locale, exact: true }
-        }, await provider.query(event, {
-          ...baseQuery,
-          resolveLocale: { locale, exact: true }
-        }), provider.name)
-      )
-    )
-  )).flat() : normalizeProviderQueryResult(normalizeProviderQueryResponse(baseQuery, await provider.query(event, baseQuery), provider.name));
+    localesToQuery.map(async (locale) => {
+      const localeQuery = { ...baseQuery, resolveLocale: { locale, exact: true } };
+      return normalizeProviderQueryResult(
+        normalizeProviderQueryResponse(
+          localeQuery,
+          await provider.query(event, createProviderQuery(localeQuery)),
+          provider.name
+        )
+      );
+    })
+  )).flat() : normalizeProviderQueryResult(normalizeProviderQueryResponse(baseQuery, await provider.query(event, createProviderQuery(baseQuery)), provider.name));
   const matched = documents.find((document) => identityMatchesDocument(document, normalizedReference));
-  const canonicalKey = matched?._canonicalKey;
+  const canonicalKey = matched?.canonicalKey;
   if (!canonicalKey) {
     return null;
   }
-  const variants = documents.filter((document) => document._canonicalKey === canonicalKey);
+  const variants = documents.filter((document) => document.canonicalKey === canonicalKey);
   if (!variants.length) {
     return null;
   }
-  const selectByLocale = (locale) => locale ? variants.find((document) => document._locale === locale) : void 0;
+  const selectByLocale = (locale) => locale ? variants.find((document) => document.locale === locale) : void 0;
   const selected = selectByLocale(options.locale) || (!options.exact ? fallbackLocales.map(selectByLocale).find(Boolean) : void 0) || (!options.exact ? selectByLocale(collectionI18n?.defaultLocale || runtimeContent.defaultLocale) : void 0) || (!options.exact ? variants[0] : void 0);
   if (!selected) {
     return null;
   }
-  const availableLocales = Array.from(new Set(variants.map((document) => document._locale).filter(Boolean)));
+  const availableLocales = sortLocalesCanonically(
+    Array.from(new Set(variants.map((document) => document.locale).filter(Boolean))),
+    {
+      defaultLocale: collectionI18n?.defaultLocale || runtimeContent.defaultLocale,
+      locales: collectionI18n?.locales
+    }
+  );
   const variantPaths = Object.fromEntries(
-    variants.filter((document) => document._locale && document._path).map((document) => [document._locale, document._path])
+    variants.filter((document) => document.locale && document.path).map((document) => [document.locale, document.path])
   );
   return {
     canonicalKey,
@@ -117,16 +147,17 @@ export const resolveProviderContentVariants = async (event, identity, options) =
     availableLocales,
     variantPaths,
     requestedLocale: options.locale,
-    resolvedLocale: selected._locale,
-    fallback: Boolean(options.locale && selected._locale && selected._locale !== options.locale)
+    resolvedLocale: selected.locale,
+    fallback: Boolean(options.locale && selected.locale && selected.locale !== options.locale)
   };
 };
 export const createServerProviderQueryFetch = (event) => {
   return async (query) => {
     const { getContentProvider } = await import("./providers/index.js");
     const provider = await getContentProvider(event);
-    const response = await provider.query(event, query.params());
-    return normalizeProviderQueryResponse(query.params(), response, provider.name);
+    const params = query.params();
+    const response = await provider.query(event, createProviderQuery(params));
+    return normalizeProviderQueryResponse(params, response, provider.name);
   };
 };
 const getServerCollectionI18n = (collection) => {
@@ -164,10 +195,13 @@ export const resolveContentReference = async (event, reference, options = {}) =>
   }
   return {
     ...resolved.selected,
-    _requestedLocale: resolved.requestedLocale,
-    _resolvedLocale: resolved.resolvedLocale,
-    _fallback: resolved.fallback,
-    _availableLocales: resolved.availableLocales,
-    _variantPaths: resolved.variantPaths
+    resolved: {
+      ...resolved.selected.resolved || {},
+      requestedLocale: resolved.requestedLocale,
+      locale: resolved.resolvedLocale,
+      fallback: resolved.fallback,
+      availableLocales: resolved.availableLocales,
+      variantPaths: resolved.variantPaths
+    }
   };
 };