@lupinum/ginko-content 0.1.0

package/dist/cms-contract/mdc.js

@@ -0,0 +1,52 @@
+import { parse } from "comark";
+import { mapMarkdownNodes, toMarkdownRoot } from "../core/markdown/tree.js";
+export async function parseMdcBody(raw, options = {}) {
+  const tree = await parse(raw ?? "");
+  const toc = deriveToc(tree.nodes, options);
+  const body = toMarkdownRoot(tree.nodes, toc);
+  const searchText = renderPlainText(body);
+  return { body, toc, searchText };
+}
+function deriveToc(nodes, options) {
+  const searchDepth = options.tocDepth ?? 3;
+  const links = [];
+  for (const node of nodes) {
+    if (!Array.isArray(node)) continue;
+    const tag = String(node[0] ?? "");
+    const match = /^h([1-6])$/.exec(tag);
+    if (!match) continue;
+    const depth = Number(match[1]);
+    if (depth < 2 || depth > searchDepth) continue;
+    const props = node[1] && typeof node[1] === "object" ? node[1] : {};
+    const children = node.slice(2);
+    const text = collectTupleText(children);
+    links.push({
+      id: String(props.id || slugHeading(text)),
+      text,
+      depth
+    });
+  }
+  return links.length > 0 ? { title: "", depth: 2, searchDepth, links } : void 0;
+}
+function collectTupleText(nodes) {
+  let value = "";
+  for (const node of nodes) {
+    if (typeof node === "string") {
+      value += node;
+    } else if (Array.isArray(node)) {
+      value += collectTupleText(node.slice(2));
+    }
+  }
+  return value.trim();
+}
+function slugHeading(value) {
+  return value.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
+}
+function renderPlainText(root) {
+  const parts = [];
+  mapMarkdownNodes(root.children, (node) => {
+    if (node.type === "text" && typeof node.value === "string") parts.push(node.value);
+    return node;
+  });
+  return parts.join(" ").replace(/\s+/g, " ").trim();
+}

package/dist/cms-contract/path

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

package/dist/cms-contract/path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure path helpers re-exported from `ginko-content`'s canonical path engine.
+ *
+ * The CMS uses these instead of duplicating its own path-generation logic.
+ * Per Gate 0 of the refactor: ginko-content owns path semantics; ginko-cms
+ * imports them. No more parallel implementations of `generatePath` /
+ * `generateCanonicalKey` / `slugifyUrlSegment`.
+ *
+ * All re-exports MUST be runtime-pure (no Node, no Nuxt, no h3). They are.
+ */
+export { describeId, generatePath, generateCanonicalKey, generateTitle, isDraftPath, isPartialPath, normalizeContentPath, normalizeRouteMounts, longestMountForPath, routeRemainder, mountContentPath, prefixPathWithLocale, stripLocalePrefix, refineUrlPart, routeToContentPathCandidates, } from '../core/content/path.js';
+export { slugifyUrlSegment } from '../core/content/slug.js';

package/dist/cms-contract/path.js

@@ -0,0 +1,18 @@
+export {
+  describeId,
+  generatePath,
+  generateCanonicalKey,
+  generateTitle,
+  isDraftPath,
+  isPartialPath,
+  normalizeContentPath,
+  normalizeRouteMounts,
+  longestMountForPath,
+  routeRemainder,
+  mountContentPath,
+  prefixPathWithLocale,
+  stripLocalePrefix,
+  refineUrlPart,
+  routeToContentPathCandidates
+} from "../core/content/path.js";
+export { slugifyUrlSegment } from "../core/content/slug.js";

package/dist/cms-contract/schema

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

package/dist/cms-contract/schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure Zod-schema introspection helpers, re-exported for CMS use.
+ *
+ * These are how the CMS understands what a collection's `schema` field means:
+ * walks down through Optional / Nullable / Default / Effects wrappers,
+ * extracts object shapes, recognizes content-reference fields.
+ *
+ * Pure functions over Zod's internal `_def` shape. No runtime deps beyond
+ * the symbols Zod itself exposes.
+ */
+export { getSchemaDef, getSchemaTypeName, unwrapSchema, getObjectShape, getReferenceDescriptor, collectTopLevelReferenceFields, } from '../core/references/schema.js';
+/**
+ * Symbol Zod schemas may carry to expose ginko-content's UI metadata
+ * (label, description, options, slug source, image/asset constraints, etc.).
+ */
+export { CONTENT_FIELD_METADATA_KEY, type ContentFieldMetadata, type ContentFieldSchema, } from '../types/fields.js';
+export { getContentFieldMetadata } from '../types/fields.js';
+export { CONTENT_REFERENCE_PREFIX } from '../types/reference.js';

package/dist/cms-contract/schema.js

@@ -0,0 +1,13 @@
+export {
+  getSchemaDef,
+  getSchemaTypeName,
+  unwrapSchema,
+  getObjectShape,
+  getReferenceDescriptor,
+  collectTopLevelReferenceFields
+} from "../core/references/schema.js";
+export {
+  CONTENT_FIELD_METADATA_KEY
+} from "../types/fields.js";
+export { getContentFieldMetadata } from "../types/fields.js";
+export { CONTENT_REFERENCE_PREFIX } from "../types/reference.js";

package/dist/cms-contract/types

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

package/dist/cms-contract/types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @lupinum/ginko-content/cms-contract — pure subpath
+ *
+ * This module contains the runtime-safe contract types and helpers that
+ * `@lupinum/ginko-cms` consumes from inside its Convex component. Everything
+ * exported from this subpath MUST be importable from a V8 isolate (Convex,
+ * Edge runtime, browser) without pulling Node, Nuxt, h3, nitropack, or
+ * filesystem APIs along.
+ *
+ * Per the ginko-cms refactor plan ("Gate 0 — Lock the boundary"):
+ *  - `ginko-content` owns content semantics (schema, paths, i18n, MDC parsing).
+ *  - `ginko-cms` owns editorial workflow (drafts, revisions, publish, assets).
+ *
+ * The CMS imports from this subpath (NOT from the full Nuxt module) so the two
+ * packages share one source of truth for what content means.
+ */
+import type { ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionI18nConfig } from '../types/config.js';
+export type { ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionI18nConfig, };
+/**
+ * The normalized contract a CMS consumes for one collection. This is the
+ * deterministic output of `buildCmsContract`: every decision the CMS used to
+ * infer (label, type, locales, routing, fields) is materialized here so the
+ * CMS never has to re-derive content semantics.
+ */
+export interface CmsCollectionContract {
+    /** Collection identifier (`blog`, `docs`, ...). */
+    slug: string;
+    /** Display label, single-string for monolingual sites or per-locale map. */
+    label: string | Record<string, string>;
+    /** `flat` (e.g. blog posts) or `tree` (e.g. nested docs). */
+    type: 'flat' | 'tree';
+    /** Optional icon hint for editor surfaces. */
+    icon?: string | null;
+    /** Locales this collection supplies. Always non-empty; defaults to site default. */
+    locales: string[];
+    /** Default locale for this collection. */
+    defaultLocale: string;
+    /** Routing config the public provider will honor. */
+    routing: CmsCollectionRouting;
+    /** Normalized field set, in stable order. */
+    fields: CmsFieldContract[];
+    /** Schema artifact reference, if Zod schema was supplied. Validates publish. */
+    schema?: CmsSchemaArtifactRef;
+    /** Free-form per-collection settings (sitemap, search, etc.). */
+    settings?: Record<string, unknown>;
+}
+export interface CmsCollectionRouting {
+    /** `route` exposes the collection at a public URL; `none` keeps it data-only. */
+    mode: 'route' | 'none';
+    /** Public URL prefix when `mode === 'route'`. Empty for `mode === 'none'`. */
+    pathPrefix: string;
+    /** Per-locale public URL prefixes for localized route-backed collections. */
+    localizedPathPrefixes?: Record<string, string> | null;
+    /** Per-locale public paths for localized singleton collections. */
+    localizedSingletonPaths?: Record<string, string> | null;
+    /** How slugs combine across locales. */
+    slugMode: 'shared' | 'localized' | 'stable' | 'localizedStable';
+    /** Optional root entry slug (e.g. an "intro" page that owns the prefix root). */
+    rootSlug?: string | null;
+    /** True when the collection holds exactly one entry. */
+    singleton: boolean;
+}
+export interface CmsFieldContract {
+    key: string;
+    type: ContentCmsFieldType;
+    label?: string | Record<string, string> | null;
+    description?: string | null;
+    required: boolean;
+    localized: boolean;
+    hidden: boolean;
+    searchable: boolean;
+    sortable: boolean;
+    order: number;
+    width: 'full' | 'half';
+    defaultValue?: unknown;
+    options?: string[] | null;
+    relation?: ContentCmsRelationConfig | null;
+    media?: {
+        accept?: string[];
+        aspectRatio?: string | null;
+    } | null;
+    fields?: CmsFieldContract[] | null;
+    validation?: Record<string, unknown> | null;
+    condition?: Record<string, unknown> | null;
+    min?: number | null;
+    max?: number | null;
+    step?: number | null;
+    slugFrom?: string | null;
+    language?: string | null;
+}
+/**
+ * Reference to a schema validation artifact. The actual artifact (a serialized,
+ * checksum-verified validator) is generated at build time by ginko-content and
+ * shipped alongside the contract. The CMS reads the checksum to verify the
+ * artifact it holds matches the contract it imported.
+ *
+ * Keeping the artifact behind a ref (rather than embedding it inline) lets the
+ * CMS drop the artifact when it doesn't need publish validation (e.g. for a
+ * code-only data collection).
+ */
+export interface CmsSchemaArtifactRef {
+    /** Stable id used to look up the artifact in the artifact registry. */
+    artifactId: string;
+    /** Stable checksum of the serialized artifact bytes. */
+    checksum: string;
+    /** Schema features the artifact actually supports. */
+    capabilities: CmsSchemaCapabilities;
+    /** Deterministic serialized validation artifact bytes. */
+    artifact: string;
+}
+export type CmsSchemaValidationNode = {
+    kind: 'object';
+    required: string[];
+    shape: Record<string, CmsSchemaValidationNode>;
+} | {
+    kind: 'array';
+    element: CmsSchemaValidationNode;
+} | {
+    kind: 'string';
+    checks?: Array<{
+        kind: 'min';
+        value: number;
+    } | {
+        kind: 'max';
+        value: number;
+    } | {
+        kind: 'email';
+    } | {
+        kind: 'url';
+    }>;
+} | {
+    kind: 'number';
+} | {
+    kind: 'boolean';
+} | {
+    kind: 'date';
+} | {
+    kind: 'enum';
+    values: string[];
+} | {
+    kind: 'optional';
+    inner: CmsSchemaValidationNode;
+} | {
+    kind: 'nullable';
+    inner: CmsSchemaValidationNode;
+} | {
+    kind: 'default';
+    inner: CmsSchemaValidationNode;
+    value: unknown;
+};
+export interface CmsSchemaValidationArtifact {
+    version: 'v1';
+    root: CmsSchemaValidationNode;
+}
+export interface CmsSchemaCapabilities {
+    /** Top-level Zod constructs the artifact understands. */
+    supports: Array<'object' | 'array' | 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'optional' | 'nullable' | 'default' | 'reference'>;
+    /** Constructs the source schema used that the artifact does NOT support. */
+    unsupported: Array<{
+        feature: string;
+        path: string;
+        reason: string;
+    }>;
+}
+/**
+ * Top-level CMS contract: one entry per collection plus site-wide settings.
+ */
+export interface CmsContract {
+    /** Schema-version identifier so the CMS can detect a contract upgrade. */
+    contractVersion: string;
+    /** Site default locale. */
+    defaultLocale: string;
+    /** Site-wide locale list (superset of any per-collection locale subset). */
+    locales: string[];
+    /** Collections keyed by slug. */
+    collections: Record<string, CmsCollectionContract>;
+}

package/dist/cms-import/index

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

package/dist/cms-import/index.d.ts

@@ -0,0 +1,21 @@
+import { type ContentGraph } from '../core/content/graph.js';
+import type { ParsedContent } from '../types/content.js';
+import type { ContentCollectionConfig } from '../types/config.js';
+import type { ContentContext } from '../types/module.js';
+export type CmsImportContentContext = Pick<ContentContext, 'locales' | 'defaultLocale' | 'translatedSlugs' | 'respectPathCase' | 'markdown' | 'yaml' | 'csv'> & {
+    collections: Record<string, ContentCollectionConfig>;
+};
+export type CmsImportParsedFile = {
+    frontmatter: Record<string, unknown>;
+    body?: string;
+    document: ParsedContent;
+};
+export declare function parseCmsImportFile(args: {
+    id: string;
+    source: string;
+    context: CmsImportContentContext;
+}): Promise<CmsImportParsedFile>;
+export declare function buildCmsImportGraph(documents: ParsedContent[], options?: {
+    locales?: string[];
+    defaultLocale?: string;
+}): ContentGraph;

package/dist/cms-import/index.js

@@ -0,0 +1,57 @@
+import { parse as parseMarkdown } from "comark";
+import { destr } from "destr";
+import { load as parseYaml } from "js-yaml";
+import { buildContentGraph } from "../core/content/graph.js";
+import { resolveCollection } from "../core/content/collection.js";
+import { transformContent } from "../parsers/index.js";
+export async function parseCmsImportFile(args) {
+  const document = await transformContent(args.id, args.source, {
+    markdown: args.context.markdown,
+    yaml: args.context.yaml,
+    csv: args.context.csv,
+    pathMeta: {
+      locales: args.context.locales,
+      defaultLocale: args.context.defaultLocale,
+      translatedSlugs: args.context.translatedSlugs,
+      respectPathCase: args.context.respectPathCase,
+      collections: args.context.collections,
+      collectionResolver: (filePath) => resolveCollection(filePath, args.context.collections, args.context.locales || [])
+    }
+  });
+  const editable = await extractEditableSource(args.id, args.source);
+  return {
+    ...editable,
+    document
+  };
+}
+export function buildCmsImportGraph(documents, options = {}) {
+  return buildContentGraph(documents, options);
+}
+async function extractEditableSource(id, source) {
+  if (/\.(md|mdc|markdown)$/i.test(id)) {
+    return parseMarkdownEditableSource(source);
+  }
+  if (/\.json5?$/i.test(id)) {
+    return { frontmatter: normalizeRecord(destr(source)) };
+  }
+  if (/\.ya?ml$/i.test(id)) {
+    return { frontmatter: normalizeRecord(parseYaml(source)) };
+  }
+  return { frontmatter: {} };
+}
+async function parseMarkdownEditableSource(source) {
+  const tree = await parseMarkdown(source);
+  return {
+    frontmatter: normalizeRecord(tree.frontmatter),
+    body: stripFrontmatter(source).trim()
+  };
+}
+function stripFrontmatter(source) {
+  if (!source.startsWith("---")) return source;
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return source;
+  return source.slice(source.indexOf("\n", end + 4) + 1);
+}
+function normalizeRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/dist/config.d.mts

@@ -0,0 +1,3 @@
+export { CollectionSchema, ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionI18nConfig, ContentCollectionKind, ContentCollectionSource, ContentCollectionSourceObject, ContentConfig, ContentReferenceSchema, DefineCollectionObject, DefineCollectionOptions, defineCollection, defineContentConfig, reference } from '../dist/types/config';
+export { ContentFieldMetadata, ContentFieldSchema, asset, fields, file, getContentFieldMetadata, image, isContentFieldSchema, relation, relations, richtext, text } from '../dist/types/fields';
+export { SlugifyUrlSegmentOptions, slugifyUrlSegment } from '../dist/core/content/slug';

package/dist/config.mjs

@@ -0,0 +1,3 @@
+export { defineCollection, defineContentConfig, reference } from '../dist/types/config';
+export { asset, fields, file, getContentFieldMetadata, image, isContentFieldSchema, relation, relations, richtext, text } from '../dist/types/fields';
+export { slugifyUrlSegment } from '../dist/core/content/slug';

package/dist/core/cache

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

package/dist/core/cache-hints

@@ -0,0 +1 @@
+export * from './cache-hints.js'

package/dist/core/cache-hints.d.ts

@@ -0,0 +1,3 @@
+import type { ContentCacheHint, ContentCacheHintInput } from '../public/provider';
+export declare const normalizeContentCacheHint: (hint: ContentCacheHint) => ContentCacheHint;
+export declare const mergeContentCacheHints: (current: ContentCacheHint | false | undefined, next: ContentCacheHintInput | undefined) => ContentCacheHint | false | undefined;

package/dist/core/cache-hints.js

@@ -0,0 +1,55 @@
+const normalizeStringList = (values, normalize) => Array.from(new Set((values || []).filter((value) => typeof value === "string").map((value) => normalize(value.trim())).filter(Boolean)));
+const normalizePath = (path) => {
+  const normalized = path.startsWith("/") ? path : `/${path}`;
+  return normalized.replace(/\/{2,}/g, "/");
+};
+const normalizeSeconds = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+const normalizeLastModified = (value) => {
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) ? date : void 0;
+  }
+  return void 0;
+};
+export const normalizeContentCacheHint = (hint) => {
+  const tags = normalizeStringList(hint.tags, (value) => value);
+  const paths = normalizeStringList(hint.paths, normalizePath);
+  const maxAge = normalizeSeconds(hint.maxAge);
+  const swr = normalizeSeconds(hint.swr);
+  const lastModified = normalizeLastModified(hint.lastModified);
+  const etag = typeof hint.etag === "string" && hint.etag.trim() ? hint.etag.trim() : void 0;
+  return {
+    ...tags.length ? { tags } : {},
+    ...paths.length ? { paths } : {},
+    ...typeof maxAge === "number" ? { maxAge } : {},
+    ...typeof swr === "number" ? { swr } : {},
+    ...etag ? { etag } : {},
+    ...lastModified ? { lastModified } : {}
+  };
+};
+export const mergeContentCacheHints = (current, next) => {
+  if (current === false || next === false) {
+    return false;
+  }
+  if (!next) {
+    return current;
+  }
+  const left = normalizeContentCacheHint(current || {});
+  const right = normalizeContentCacheHint(next);
+  const tags = normalizeStringList([...left.tags || [], ...right.tags || []], (value) => value);
+  const paths = normalizeStringList([...left.paths || [], ...right.paths || []], normalizePath);
+  const maxAge = [left.maxAge, right.maxAge].filter((value) => typeof value === "number");
+  const swr = [left.swr, right.swr].filter((value) => typeof value === "number");
+  const lastModified = [left.lastModified, right.lastModified].filter((value) => value instanceof Date).sort((a, b) => b.getTime() - a.getTime())[0];
+  return {
+    ...tags.length ? { tags } : {},
+    ...paths.length ? { paths } : {},
+    ...maxAge.length ? { maxAge: Math.min(...maxAge) } : {},
+    ...swr.length ? { swr: Math.min(...swr) } : {},
+    ...right.etag || left.etag ? { etag: right.etag || left.etag } : {},
+    ...lastModified ? { lastModified } : {}
+  };
+};

package/dist/core/cache.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Content cache contracts.
+ *
+ * Pure interfaces only — no implementation, no framework imports. The default
+ * implementation lives in `src/storage/cache.ts`; `integrations/nitro/context.ts`
+ * references these types to hold a per-context reference without creating a
+ * layering violation against the core → storage → integrations dependency order.
+ */
+/**
+ * Deduplicates concurrent in-flight work by key. If two callers ask for the
+ * same key before the first factory resolves, both observe the same promise.
+ * The entry is removed as soon as the promise settles, so subsequent reads
+ * re-run the factory.
+ */
+export interface SingleFlightMap<T> {
+    run(key: string, factory: () => Promise<T>): Promise<T>;
+}
+/**
+ * Request-scoped content cache. Holds parsed-content lists keyed by a config
+ * digest, plus two single-flight maps that prevent duplicate parse/load work
+ * inside a single request.
+ */
+export interface ContentCacheStore<TContent> {
+    getContents(key: string): TContent[] | undefined;
+    setContents(key: string, value: TContent[]): void;
+    clearContents(): void;
+    readonly inflightContents: SingleFlightMap<TContent[]>;
+    readonly inflightContentsList: SingleFlightMap<TContent[]>;
+}

package/dist/core/content/collection

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

package/dist/core/content/collection.d.ts

@@ -0,0 +1,3 @@
+import type { ContentCollectionConfig } from '../../types/config';
+export declare const resolveCollection: (file: string, collections?: Record<string, ContentCollectionConfig>, locales?: string[]) => string;
+export declare const resolveCollections: (file: string, collections?: Record<string, ContentCollectionConfig>, locales?: string[]) => string[];

package/dist/core/content/collection.js

@@ -0,0 +1,52 @@
+import picomatch from "picomatch";
+import { normalizeCollectionExcludes, normalizeCollectionSources } from "./sources.js";
+const stripLocalePrefix = (file, locales) => {
+  const parts = file.split("/").filter(Boolean);
+  if (parts[0] && locales.includes(parts[0])) {
+    return parts.slice(1).join("/");
+  }
+  return file;
+};
+const createNumericSlugPattern = (source) => {
+  const translated = source.split("/").map((segment) => {
+    if (segment.includes("*")) {
+      return segment;
+    }
+    const match = /^(\d+)\.[^/]+?(\.[^.]+)?$/.exec(segment);
+    if (!match) {
+      return segment;
+    }
+    return `${match[1]}.*${match[2] || ""}`;
+  }).join("/");
+  return translated === source ? [source] : [source, translated];
+};
+const createSourceMatcher = (source) => {
+  const matchers = createNumericSlugPattern(source).map((pattern) => picomatch(pattern, { dot: true }));
+  return (file) => matchers.some((isMatch) => isMatch(file));
+};
+export const resolveCollection = (file, collections = {}, locales = []) => {
+  return resolveCollections(file, collections, locales)[0];
+};
+export const resolveCollections = (file, collections = {}, locales = []) => {
+  const normalizedFile = file.replace(/^\/+/, "");
+  const localeAgnosticFile = stripLocalePrefix(normalizedFile, locales);
+  const matches = [];
+  for (const [name, collection] of Object.entries(collections)) {
+    const excludes = normalizeCollectionExcludes(collection.exclude);
+    const isExcluded = excludes.some((source) => {
+      const isMatch = createSourceMatcher(source);
+      return isMatch(normalizedFile) || isMatch(localeAgnosticFile);
+    });
+    if (isExcluded) {
+      continue;
+    }
+    for (const source of normalizeCollectionSources(collection.source)) {
+      const isMatch = createSourceMatcher(source);
+      if (isMatch(normalizedFile) || isMatch(localeAgnosticFile)) {
+        matches.push(name);
+        break;
+      }
+    }
+  }
+  return matches;
+};

package/dist/core/content/graph

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