@lupinum/ginko-content 1.0.0-beta.7 → 1.0.0-beta.8

package/README.md

@@ -15,7 +15,7 @@
 </p>
 
 > [!WARNING]
-> Version `1.0.0-beta.7` is a prerelease. Install it from npm's `next`
+> Version `1.0.0-beta.8` is a prerelease. Install it from npm's `next`
 > channel. The stable `0.3` line remains on `latest`.
 
 ## Why use this package?
@@ -40,13 +40,13 @@ output.
 Use the Nuxt CLI:
 
 ```bash
-npx nuxi module add @lupinum/ginko-content@1.0.0-beta.7
+npx nuxi module add @lupinum/ginko-content@1.0.0-beta.8
 ```
 
 Or install and register the module by hand:
 
 ```bash
-pnpm add @lupinum/ginko-content@1.0.0-beta.7
+pnpm add @lupinum/ginko-content@1.0.0-beta.8
 ```
 
 ```ts

package/dist/cli.mjs

@@ -4,6 +4,7 @@ import { stat, readFile, readdir } from 'node:fs/promises';
 import { join, extname, relative, resolve, isAbsolute } from 'node:path';
 import { loadNuxtConfig } from '@nuxt/kit';
 import { isContentValidationReport } from '../dist/features/validation/report.js';
+import { assessFilesystemPortability, exportFilesystemToPortableDirectory, FilesystemPortabilityAssessmentError } from '../dist/portability-node/filesystem-export.js';
 
 const ignoredDirs = /* @__PURE__ */ new Set([
   ".git",
@@ -902,16 +903,45 @@ if (!command || command === "--help" || command === "-h") {
     "Commands:",
     "  doctor [root]         Validate a Nuxt Content v3 to Ginko migration",
     "  doctor --i18n [root]  Validate i18n migration wiring and generated output",
-    "  validate [root]       Validate internal content links, anchors, and assets"
+    "  validate [root]       Validate internal content links, anchors, and assets",
+    "  portable assess [root]",
+    "                        Assess filesystem content for portable V1 export",
+    "  portable export <destination> [root]",
+    "                        Export filesystem content to a new portable V1 directory"
   ].join("\n"));
   process.exit(0);
 }
-if (command !== "doctor" && command !== "validate") {
+if (command !== "doctor" && command !== "validate" && command !== "portable") {
   console.error(`Unknown command: ${command}`);
   console.error('Run "ginko-content --help" for available commands.');
   process.exit(1);
 }
 try {
+  if (command === "portable") {
+    const [operation, ...portableArgs] = args;
+    const unknownFlag2 = portableArgs.find((arg) => arg.startsWith("-"));
+    const hasExtraArguments = operation === "assess" ? portableArgs.length > 1 : portableArgs.length > 2;
+    if (unknownFlag2 || hasExtraArguments || operation !== "assess" && operation !== "export") {
+      console.error(unknownFlag2 ? `Unknown option: ${unknownFlag2}` : "Usage: ginko-content portable assess [root] | portable export <destination> [root]");
+      process.exit(1);
+    }
+    if (operation === "assess") {
+      const result3 = await assessFilesystemPortability({ rootDir: portableArgs[0] || process.cwd() });
+      for (const item of result3.diagnostics) console.error(`${item.severity.toUpperCase()} ${item.code}${item.file ? ` ${item.file}` : ""}${item.field ? `:${item.field}` : ""}: ${item.message} ${item.resolution}`);
+      if (result3.evidence) console.log(`Filesystem portability ${result3.ok ? "passed" : "failed"}: ${result3.summary.documents} document(s), ${result3.summary.assets} managed asset(s), input ${result3.evidence.inputHash}.`);
+      process.exit(result3.ok ? 0 : 2);
+    }
+    if (!portableArgs[0]) {
+      console.error("Usage: ginko-content portable export <destination> [root]");
+      process.exit(1);
+    }
+    const result2 = await exportFilesystemToPortableDirectory({
+      destination: portableArgs[0],
+      rootDir: portableArgs[1] || process.cwd()
+    });
+    console.log(`Portable V1 written to ${result2.directory}: ${result2.documents} document(s), ${result2.assets} managed asset(s), manifest ${result2.manifestSha256}.`);
+    process.exit(0);
+  }
   if (command === "validate") {
     const unknownFlag2 = args.find((arg) => arg.startsWith("-"));
     if (unknownFlag2) {
@@ -934,6 +964,10 @@ try {
   process.stdout.write(formatDoctorResult(result));
   process.exit(result.exitCode);
 } catch (error) {
+  if (error instanceof FilesystemPortabilityAssessmentError) {
+    for (const item of error.assessment.diagnostics) console.error(`${item.severity.toUpperCase()} ${item.code}${item.file ? ` ${item.file}` : ""}${item.field ? `:${item.field}` : ""}: ${item.message} ${item.resolution}`);
+    process.exit(2);
+  }
   console.error(error instanceof Error ? error.message : error);
   process.exit(1);
 }

package/dist/cms-contract/render-policy.js

@@ -219,6 +219,7 @@ export function isSafePublicMarkdownUrl(value, kind = "href") {
   });
   if (!input || input.startsWith("//") || input.includes("\\") || hasControlCharacter) return false;
   if (kind === "href" && input.startsWith("#")) return true;
+  if (kind === "href" && /^\$[^\s\\?#]+(?:#[^\s\\]*)?$/u.test(input)) return true;
   try {
     if (input.startsWith("/") || input.startsWith("./") || input.startsWith("../")) {
       return new URL(input, "https://ginko.invalid").origin === "https://ginko.invalid";

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "configKey": "content",
   "compatibility": {
     "nuxt": ">=4.5.1 <5"

package/dist/module.mjs

@@ -34,7 +34,7 @@ import { assertCanonicalHighlightOptionNames } from '../dist/parsers/markdown-pl
 import { BUILTIN_MARKDOWN_RENDER_CONTRACTS } from '../dist/core/markdown/builtin-render-contracts.js';
 
 const name = "@lupinum/ginko-content";
-const version = "1.0.0-beta.7";
+const version = "1.0.0-beta.8";
 const peerDependencies = {
 	nuxt: ">=4.5.1 <5"};
 

package/dist/portability-node/filesystem-export.d.ts

@@ -0,0 +1,62 @@
+import type { ResolvedContentContractV1 } from '../cms-contract/types.js';
+import { GinkoBoundaryError, type PortabilityErrorCode, type PortabilityOperation } from '../portability/errors.js';
+import type { PortableDocumentV1, PortableManifestV1 } from '../portability/model.js';
+import { type PortableAssetWriteInput } from './write-directory.js';
+export interface FilesystemPortabilityDiagnostic {
+    severity: 'error' | 'warning';
+    code: PortabilityErrorCode;
+    operation: PortabilityOperation;
+    collection: string | null;
+    file: string | null;
+    field: string | null;
+    message: string;
+    resolution: string;
+}
+export interface FilesystemPortabilityEvidence {
+    inputHash: string;
+    contractSha256: string;
+    packageVersion: string;
+    files: Array<{
+        file: string;
+        bytes: number;
+        sha256: string;
+    }>;
+}
+export interface FilesystemPortabilityAssessment {
+    ok: boolean;
+    rootDir: string;
+    contract: ResolvedContentContractV1 | null;
+    documents: PortableDocumentV1[];
+    assets: PortableAssetWriteInput[];
+    diagnostics: FilesystemPortabilityDiagnostic[];
+    evidence: FilesystemPortabilityEvidence | null;
+    summary: {
+        documents: number;
+        assets: number;
+        collections: string[];
+        locales: string[];
+    };
+}
+export interface FilesystemPortabilityExportResult {
+    directory: string;
+    inputHash: string;
+    contractSha256: string;
+    manifestSha256: string;
+    manifest: PortableManifestV1;
+    documents: number;
+    assets: number;
+    collections: string[];
+    locales: string[];
+}
+export declare class FilesystemPortabilityAssessmentError extends GinkoBoundaryError {
+    readonly assessment: FilesystemPortabilityAssessment;
+    constructor(assessment: FilesystemPortabilityAssessment);
+}
+export declare function assessFilesystemPortability(options: {
+    rootDir: string;
+}): Promise<FilesystemPortabilityAssessment>;
+export declare function exportFilesystemToPortableDirectory(options: {
+    rootDir: string;
+    destination: string;
+    expectedInputHash?: string;
+}): Promise<FilesystemPortabilityExportResult>;

package/dist/portability-node/filesystem-export.js

@@ -0,0 +1,740 @@
+import { lstat } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import defu from "defu";
+import { globby } from "globby";
+import jiti from "jiti";
+import { buildResolvedContentContract } from "../cms-contract/build.js";
+import { verifyPublicImageBytes } from "../cms-contract/asset-bytes.js";
+import { canonicalJsonBytes, hashCanonicalJson, sha256Hex } from "../cms-contract/hash.js";
+import { PORTABLE_CONTENT_LIMITS } from "../cms-contract/limits.js";
+import { buildContentGraph } from "../core/content/graph.js";
+import { expandDataLocaleVariants } from "../core/content/locale.js";
+import { resolveCollections } from "../core/content/collection.js";
+import { isNavigationFile } from "../core/content/structural.js";
+import { resolveLocalePolicy } from "../features/localization/locale-policy.js";
+import { resolveCollectionI18nConfig } from "../features/localization/config.js";
+import { buildCanonicalNavigation } from "../features/navigation/build.js";
+import { resolveSitemapCollections } from "../features/sitemap/counts.js";
+import { parseComark } from "../core/markdown/parse-comark.js";
+import csvParser from "../parsers/csv.js";
+import jsonParser from "../parsers/json.js";
+import pathMeta from "../parsers/path-meta.js";
+import { stripReservedContentKeys } from "../parsers/reserved.js";
+import yamlParser from "../parsers/yaml.js";
+import { validatePortableDocument } from "../portability/documents.js";
+import {
+  assertPortableAssetReference,
+  collectPortableAssetReferences,
+  collectPortableMdcAssetReferences
+} from "../portability/assets.js";
+import { GinkoBoundaryError } from "../portability/errors.js";
+import { validatePortableReferences } from "../portability/references.js";
+import { validateCollectionDocument, validateContentGraph, validateDocumentJsonPurity } from "../storage/validation.js";
+import { readResolvedContentContract } from "../cms-contract-node/artifact.js";
+import { readStableRegularFile, StableFileError } from "../cms-contract-node/stable-file.js";
+import { writePortableDirectory } from "./write-directory.js";
+import { readPortableDirectory } from "./read-directory.js";
+const CONFIG_NAMES = ["content.config.ts", "content.config.mts", "content.config.js", "content.config.mjs", "content.config.cjs"];
+const NUXT_CONFIG_NAMES = ["nuxt.config.ts", "nuxt.config.mts", "nuxt.config.js", "nuxt.config.mjs"];
+const SOURCE_EXTENSIONS = /* @__PURE__ */ new Set(["md", "json", "json5", "yml", "yaml", "csv"]);
+const filesystemExportDefaults = {
+  i18n: true,
+  sitemap: true,
+  search: false,
+  navigation: { fields: [] },
+  transformers: [],
+  yaml: {},
+  csv: { delimiter: ",", json: true },
+  respectPathCase: false
+};
+export class FilesystemPortabilityAssessmentError extends GinkoBoundaryError {
+  constructor(assessment) {
+    super({
+      operation: "directory.write",
+      code: "DOCUMENT_INVALID",
+      message: `Filesystem content is not portable (${assessment.diagnostics.filter((item) => item.severity === "error").length} error(s)).`,
+      details: { errors: assessment.diagnostics.filter((item) => item.severity === "error").length }
+    });
+    this.assessment = assessment;
+  }
+  assessment;
+}
+export async function assessFilesystemPortability(options) {
+  const rootDir = resolve(options.rootDir);
+  const diagnostics = [];
+  let contract = null;
+  let contractSha256 = "";
+  let packageVersion = "";
+  let collections = {};
+  let localePolicy = null;
+  let moduleOptions = filesystemExportDefaults;
+  try {
+    const loaded = await loadProjectConfig(rootDir);
+    collections = loaded.collections;
+    localePolicy = loaded.localePolicy;
+    moduleOptions = loaded.moduleOptions;
+    packageVersion = loaded.packageVersion;
+    const artifact = await readResolvedContentContract({ root: rootDir });
+    contract = artifact.contract;
+    contractSha256 = artifact.sha256;
+    const rebuilt = buildResolvedContentContract(
+      { collections },
+      {
+        defaultLocale: localePolicy.defaultLocale,
+        locales: [...localePolicy.locales],
+        localeFallbacks: Object.fromEntries(Object.entries(localePolicy.fallback).map(([key, value]) => [key, [...value]])),
+        translatedSlugs: localePolicy.translatedSlugs,
+        componentPolicy: moduleOptions.componentPolicy
+      }
+    );
+    const rebuiltHash = await hashCanonicalJson(rebuilt);
+    if (rebuiltHash !== artifact.sha256) {
+      diagnostic(
+        diagnostics,
+        "CONTRACT_HASH_MISMATCH",
+        "portability.hash",
+        null,
+        ".ginko/content-contract.json",
+        null,
+        "The resolved Content contract is stale for the current configuration.",
+        "Run the app's Nuxt prepare or generate command, then assess again."
+      );
+    }
+    if (loaded.provider !== "filesystem") {
+      diagnostic(
+        diagnostics,
+        "CONTRACT_INVALID",
+        "portability.hash",
+        null,
+        "content.config",
+        "provider",
+        `The configured provider is "${loaded.provider}"; this boundary exports filesystem content only.`,
+        "Switch to the filesystem source before export, or use the provider-owned export path."
+      );
+    }
+    if (moduleOptions.transformers?.length) {
+      diagnostic(
+        diagnostics,
+        "DOCUMENT_INVALID",
+        "portability.parse",
+        null,
+        "nuxt.config",
+        "content.transformers",
+        "Custom filesystem transformers cannot be reproduced by the portable source boundary.",
+        "Remove the transformer dependency or define a versioned portable representation for its output."
+      );
+    }
+  } catch (error) {
+    diagnostic(
+      diagnostics,
+      boundaryCode(error, "CONTRACT_INVALID"),
+      "portability.hash",
+      null,
+      null,
+      null,
+      message(error),
+      "Fix the project configuration and regenerate its resolved Content contract."
+    );
+  }
+  if (!contract || !localePolicy) return emptyAssessment(rootDir, diagnostics);
+  const sourceRoot = join(rootDir, "content");
+  const sourceFiles = [];
+  try {
+    const paths = (await globby("**/*", { cwd: sourceRoot, onlyFiles: true, dot: true, followSymbolicLinks: false })).sort();
+    if (paths.length > PORTABLE_CONTENT_LIMITS.documents + 1e3) {
+      diagnostic(
+        diagnostics,
+        "LIMIT_EXCEEDED",
+        "portability.parse",
+        null,
+        "content",
+        null,
+        "The filesystem source exceeds the bounded file count.",
+        "Reduce the source set or split the migration."
+      );
+    } else {
+      for (const file of paths) {
+        const extension = file.split(".").pop()?.toLowerCase() ?? "";
+        if (!SOURCE_EXTENSIONS.has(extension)) continue;
+        try {
+          const path = join(sourceRoot, ...file.split("/"));
+          const before = await lstat(path);
+          const bytes = await readStableRegularFile(path, before, PORTABLE_CONTENT_LIMITS.documentBytes);
+          sourceFiles.push({ file, bytes, sha256: await sha256Hex(bytes) });
+        } catch (error) {
+          diagnostic(
+            diagnostics,
+            error instanceof StableFileError && error.reason === "limit" ? "LIMIT_EXCEEDED" : "PATH_INVALID",
+            "portability.parse",
+            null,
+            `content/${file}`,
+            null,
+            "The source is not a stable, bounded regular file.",
+            "Replace symlinks and retry after source writes finish."
+          );
+        }
+      }
+    }
+  } catch (error) {
+    diagnostic(diagnostics, "PATH_INVALID", "portability.parse", null, "content", null, message(error), "Ensure the content directory exists and is readable.");
+  }
+  const parsed = [];
+  const rawById = /* @__PURE__ */ new Map();
+  for (const source of sourceFiles) {
+    const matches = resolveCollections(source.file, collections, [...contract.locales]);
+    const navigation = /(?:^|\/)\.navigation\.ya?ml$/u.test(source.file);
+    if (!navigation && matches.length === 0) {
+      diagnostic(
+        diagnostics,
+        "DOCUMENT_INVALID",
+        "portability.parse",
+        null,
+        `content/${source.file}`,
+        null,
+        "The source file does not match a configured collection.",
+        "Add it to one collection source or exclude/remove it intentionally."
+      );
+      continue;
+    }
+    if (matches.length > 1) {
+      diagnostic(
+        diagnostics,
+        "IDENTITY_CONFLICT",
+        "portability.parse",
+        null,
+        `content/${source.file}`,
+        null,
+        `The source file matches multiple collections: ${matches.join(", ")}.`,
+        "Make collection source globs unambiguous."
+      );
+      continue;
+    }
+    try {
+      const id = `content:${source.file}`;
+      const value = new TextDecoder("utf-8", { fatal: true }).decode(source.bytes);
+      rawById.set(id, value);
+      const document = await parseFilesystemSource(id, value, {
+        yaml: moduleOptions.yaml,
+        csv: moduleOptions.csv,
+        markdown: { plugins: [], tags: {}, anchorLinks: { depth: 4, exclude: [1] } },
+        pathMeta: {
+          locales: [...contract.locales],
+          defaultLocale: contract.defaultLocale,
+          translatedSlugs: localePolicy.translatedSlugs,
+          respectPathCase: moduleOptions.respectPathCase,
+          collections,
+          localePolicy: localePolicy.collections,
+          collectionResolver: (file) => resolveCollections(file, collections, [...contract.locales])[0]
+        }
+      });
+      const matched = document.collection ? collections[document.collection] : void 0;
+      const variants = expandDataLocaleVariants(document, matched?.i18n && matched.i18n !== true ? matched.i18n : void 0);
+      for (const variant of variants) {
+        const schema = validateCollectionDocument(variant, collections);
+        if (!schema.ok) throw schema.error;
+        const pure = validateDocumentJsonPurity(schema.value);
+        if (!pure.ok) throw pure.error;
+        parsed.push(pure.value);
+      }
+    } catch (error) {
+      diagnostic(
+        diagnostics,
+        boundaryCode(error, "DOCUMENT_INVALID"),
+        "portability.parse",
+        matches[0] ?? null,
+        `content/${source.file}`,
+        fieldFrom(error),
+        message(error),
+        "Fix the source document so it passes the configured parser and schema."
+      );
+    }
+  }
+  const graph = buildContentGraph(parsed, {
+    locales: [...contract.locales],
+    defaultLocale: contract.defaultLocale
+  });
+  const graphValidation = validateContentGraph(parsed, {
+    collections,
+    locales: [...contract.locales],
+    translatedSlugs: localePolicy.translatedSlugs,
+    localePolicy
+  });
+  if (!graphValidation.ok) {
+    const code = graphValidation.error.code === "INVALID_REF_VALUE" || graphValidation.error.code === "SCHEMA_VALIDATION_FAILED" ? "DOCUMENT_INVALID" : "IDENTITY_CONFLICT";
+    diagnostic(
+      diagnostics,
+      code,
+      "portability.validateReferences",
+      null,
+      fieldFile(graphValidation.error),
+      fieldFrom(graphValidation.error),
+      graphValidation.error.message,
+      "Resolve the identity, locale, route, or reference conflict in source content."
+    );
+  }
+  const navigationFields = moduleOptions.navigation === false ? [] : moduleOptions.navigation?.fields ?? [];
+  const navigationByVariant = buildNavigationMetadata(parsed, collections, contract, navigationFields);
+  const sitemapCollections = new Set(resolveSitemapCollections(collections, moduleOptions.sitemap === false ? false : normalizeSitemap(moduleOptions.sitemap)));
+  const documents = [];
+  for (const document of parsed) {
+    if (isFilesystemNavigationFile(document)) continue;
+    if (document.partial) {
+      diagnostic(
+        diagnostics,
+        "DOCUMENT_INVALID",
+        "portability.parse",
+        document.collection ?? null,
+        fieldFile(document),
+        null,
+        "Portable V1 cannot represent a standalone partial document.",
+        "Inline the partial, exclude it from the migration, or define a versioned portable contract change."
+      );
+      continue;
+    }
+    if (document.draft) {
+      diagnostic(
+        diagnostics,
+        "DOCUMENT_INVALID",
+        "portability.parse",
+        document.collection ?? null,
+        fieldFile(document),
+        "draft",
+        "Portable V1 does not encode source draft state.",
+        "Publish or remove the draft, or define a versioned portable contract change before migration."
+      );
+      continue;
+    }
+    const collectionId = document.collection;
+    const canonicalKey = document.canonicalKey;
+    const locale = document.locale;
+    if (!collectionId || !canonicalKey || !locale || !contract.collections[collectionId]) {
+      diagnostic(
+        diagnostics,
+        "DOCUMENT_INVALID",
+        "portability.parse",
+        collectionId ?? null,
+        fieldFile(document),
+        null,
+        "The parsed document lacks a collection, canonical key, or locale.",
+        "Make the source match one configured collection and locale."
+      );
+      continue;
+    }
+    try {
+      const collection = contract.collections[collectionId];
+      const fields = await portableFields(document, collection, graph, diagnostics);
+      const routeBacked = collection.kind === "page" && collection.routing.mode === "route";
+      const navigationKey = variantKey(collectionId, canonicalKey, locale);
+      const nav = navigationByVariant.get(navigationKey);
+      if (nav) {
+        for (const field of collection.fields.filter((item) => item.role !== "body")) {
+          if (!(field.key in nav)) continue;
+          (field.localized ? fields.localized : fields.shared)[field.key] = nav[field.key];
+        }
+      }
+      const body = document.type === "markdown" ? { kind: "mdc", source: markdownBody(requiredRawSource(rawById, document.id)) } : null;
+      const portable = {
+        format: "ginko-content-document",
+        version: 1,
+        collection: collectionId,
+        canonicalKey,
+        locale,
+        slug: routeBacked ? routeSlug(document, collection) : "",
+        parentCanonicalKey: routeBacked && collection.structure === "tree" ? treeParent(canonicalKey) : null,
+        order: routeBacked && collection.structure === "tree" ? treeOrder(canonicalKey) : null,
+        shared: fields.shared,
+        localized: fields.localized,
+        body,
+        visibility: routeBacked ? {
+          navigation: moduleOptions.navigation !== false && Boolean(nav),
+          search: searchVisible(moduleOptions.search, collectionId),
+          sitemap: sitemapCollections.has(collectionId) && document.sitemap !== false
+        } : { navigation: false, search: false, sitemap: false }
+      };
+      documents.push(validatePortableDocument(portable, contract));
+    } catch (error) {
+      diagnostic(
+        diagnostics,
+        boundaryCode(error, "DOCUMENT_INVALID"),
+        "portability.parse",
+        collectionId,
+        fieldFile(document),
+        fieldFrom(error),
+        message(error),
+        "Align the source value and collection contract; no value was discarded."
+      );
+    }
+  }
+  try {
+    validatePortableReferences(documents, contract);
+  } catch (error) {
+    diagnostic(
+      diagnostics,
+      boundaryCode(error, "REFERENCE_MISSING"),
+      "portability.validateReferences",
+      null,
+      null,
+      null,
+      message(error),
+      "Add the referenced entry or correct the source reference."
+    );
+  }
+  const sharedByIdentity = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    const identity = `${document.collection}\0${document.canonicalKey}`;
+    const hash = await hashCanonicalJson(document.shared);
+    const previous = sharedByIdentity.get(identity);
+    if (previous && previous !== hash) {
+      diagnostic(
+        diagnostics,
+        "SHARED_FIELD_DIVERGENCE",
+        "directory.verify",
+        document.collection,
+        null,
+        null,
+        `Shared fields differ between locale variants of "${document.canonicalKey}".`,
+        "Move translated values to localized fields or make the shared source values identical."
+      );
+    }
+    sharedByIdentity.set(identity, hash);
+  }
+  documents.sort((left, right) => variantKey(left.collection, left.canonicalKey, left.locale).localeCompare(variantKey(right.collection, right.canonicalKey, right.locale)));
+  const assets = await materializeManagedAssets(rootDir, documents, contract, diagnostics);
+  const evidenceFiles = sourceFiles.map(({ file, bytes, sha256 }) => ({ file: `content/${file}`, bytes: bytes.byteLength, sha256 }));
+  evidenceFiles.push(...assets.map((asset) => ({ file: asset.file, bytes: asset.bytes, sha256: asset.sha256 })));
+  for (const name of [...CONFIG_NAMES, ...NUXT_CONFIG_NAMES, ".ginko/content-contract.json", "package.json"]) {
+    try {
+      const path = join(rootDir, ...name.split("/"));
+      const before = await lstat(path);
+      const bytes = await readStableRegularFile(path, before, PORTABLE_CONTENT_LIMITS.contractBytes);
+      evidenceFiles.push({ file: name, bytes: bytes.byteLength, sha256: await sha256Hex(bytes) });
+    } catch {
+    }
+  }
+  evidenceFiles.sort((left, right) => left.file.localeCompare(right.file));
+  const inputHash = await hashCanonicalJson({ contractSha256, packageVersion, files: evidenceFiles });
+  const summary = summarize(documents, assets);
+  return {
+    ok: !diagnostics.some((item) => item.severity === "error"),
+    rootDir,
+    contract,
+    documents,
+    assets,
+    diagnostics,
+    evidence: { inputHash, contractSha256, packageVersion, files: evidenceFiles },
+    summary
+  };
+}
+async function parseFilesystemSource(id, source, options) {
+  const extension = id.slice(id.lastIndexOf(".")).toLowerCase();
+  let parsed;
+  if (extension === ".md") {
+    const tree = await parseComark(source);
+    const frontmatter = stripReservedContentKeys(tree.frontmatter, id);
+    parsed = {
+      ...frontmatter,
+      description: typeof frontmatter.description === "string" ? frontmatter.description : "",
+      id,
+      type: "markdown",
+      body: { type: "root", children: [] }
+    };
+  } else {
+    const parser = extension === ".json" || extension === ".json5" ? jsonParser : extension === ".yml" || extension === ".yaml" ? yamlParser : extension === ".csv" ? csvParser : null;
+    if (!parser?.parse) throw new TypeError(`Unsupported filesystem extension "${extension}".`);
+    parsed = await parser.parse(id, source, extension === ".csv" ? options.csv : options.yaml);
+  }
+  if (!pathMeta.transform) throw new TypeError("The canonical path transformer is unavailable.");
+  return await pathMeta.transform(parsed, options.pathMeta);
+}
+export async function exportFilesystemToPortableDirectory(options) {
+  const assessment = await assessFilesystemPortability({ rootDir: options.rootDir });
+  if (!assessment.ok || !assessment.contract || !assessment.evidence) throw new FilesystemPortabilityAssessmentError(assessment);
+  if (options.expectedInputHash && options.expectedInputHash !== assessment.evidence.inputHash) {
+    throw new GinkoBoundaryError({
+      operation: "directory.write",
+      code: "CONTRACT_HASH_MISMATCH",
+      message: "Filesystem content changed after assessment; export was refused.",
+      details: { expectedInputHash: options.expectedInputHash, actualInputHash: assessment.evidence.inputHash }
+    });
+  }
+  const destination = resolve(options.rootDir, options.destination);
+  await writePortableDirectory(destination, { contract: assessment.contract, documents: assessment.documents, assets: assessment.assets });
+  const bundle = await readPortableDirectory(destination);
+  return {
+    directory: destination,
+    inputHash: assessment.evidence.inputHash,
+    contractSha256: assessment.evidence.contractSha256,
+    manifestSha256: await hashCanonicalJson(bundle.manifest),
+    manifest: bundle.manifest,
+    ...assessment.summary
+  };
+}
+async function loadProjectConfig(rootDir) {
+  const configPath = await firstExisting(rootDir, CONFIG_NAMES);
+  const nuxtPath = await firstExisting(rootDir, NUXT_CONFIG_NAMES);
+  if (!configPath || !nuxtPath) throw new TypeError("A content.config.* and nuxt.config.* are required.");
+  const importer = jiti(rootDir, { interopDefault: true, moduleCache: false });
+  const contentConfig = unwrap(await importer.import(configPath));
+  const nuxtConfig = unwrap(await importer.import(nuxtPath));
+  if (!contentConfig.collections || !Object.keys(contentConfig.collections).length) throw new TypeError("content.config.* must declare collections.");
+  const moduleOptions = defu(nuxtConfig.content ?? {}, filesystemExportDefaults);
+  const modules = Array.isArray(nuxtConfig.modules) ? nuxtConfig.modules : [];
+  const i18n = nuxtConfig.i18n ?? {};
+  const moduleI18n = moduleOptions.i18n === false || moduleOptions.i18n === true ? {} : moduleOptions.i18n ?? {};
+  const localePolicy = resolveLocalePolicy({
+    nuxtI18n: {
+      installed: modules.some((item) => (Array.isArray(item) ? item[0] : item) === "@nuxtjs/i18n"),
+      locales: i18n.locales?.map((item) => typeof item === "string" ? item : item.code).filter((item) => Boolean(item)),
+      defaultLocale: i18n.defaultLocale,
+      strategy: i18n.strategy
+    },
+    content: {
+      locales: moduleI18n.locales,
+      defaultLocale: moduleI18n.defaultLocale,
+      fallback: moduleI18n.fallback,
+      translatedSlugs: moduleI18n.translatedSlugs
+    },
+    collections: Object.entries(contentConfig.collections).map(([name, collection]) => ({
+      name,
+      localized: Boolean(collection.i18n),
+      ...collection.i18n && collection.i18n !== true ? { locales: collection.i18n.locales, defaultLocale: collection.i18n.defaultLocale } : {},
+      route: collection.route
+    }))
+  });
+  const collections = Object.fromEntries(Object.entries(contentConfig.collections).map(([name, collection]) => [name, {
+    ...collection,
+    i18n: collection.i18n === false ? false : resolveCollectionI18nConfig(collection, { defaultLocale: localePolicy.defaultLocale, locales: [...localePolicy.locales] })
+  }]));
+  let packageVersion = "unknown";
+  try {
+    const appManifest = unwrap(await importer.import(join(rootDir, "node_modules/@lupinum/ginko-content/package.json")));
+    packageVersion = appManifest.version ?? packageVersion;
+  } catch {
+  }
+  return { collections, localePolicy, moduleOptions, provider: contentConfig.provider ?? "filesystem", packageVersion };
+}
+function buildNavigationMetadata(documents, collections, contract, fields) {
+  const result = /* @__PURE__ */ new Map();
+  for (const [collection, config] of Object.entries(collections)) {
+    const pages = documents.filter((item) => item.collection === collection && !item.partial && !isFilesystemNavigationFile(item));
+    const locales = new Set(pages.map((item) => item.locale).filter((item) => Boolean(item)));
+    for (const locale of locales) {
+      const variants = pages.filter((item) => item.locale === locale);
+      const configs = {};
+      const overrides = /* @__PURE__ */ new Map();
+      for (const navigation of documents.filter((item) => isFilesystemNavigationFile(item) && item.locale === locale)) {
+        const directory = sourceDirectory(navigation.file?.path);
+        const indexPage = variants.find((item) => sourceDirectory(item.file?.path) === directory && /(?:^|\/)\d*\.?index\.[^.]+$/u.test(item.file?.path ?? ""));
+        if (indexPage?.path && indexPage.canonicalKey) {
+          configs[indexPage.path] = { ...navigation, path: indexPage.path };
+          overrides.set(indexPage.canonicalKey, navigation);
+        }
+      }
+      const portableFields2 = contract.collections[collection]?.fields.map((field) => field.key) ?? [];
+      for (const node of flattenNavigation(buildCanonicalNavigation(variants, configs, [.../* @__PURE__ */ new Set([...fields, ...portableFields2])]))) {
+        if (!node.canonicalKey) continue;
+        const configured = overrides.get(node.canonicalKey);
+        result.set(variantKey(collection, node.canonicalKey, locale), configured ? Object.fromEntries(portableFields2.filter((key) => key in configured).map((key) => [key, configured[key]])) : {});
+      }
+    }
+    void config;
+  }
+  return result;
+}
+function flattenNavigation(items) {
+  return items.flatMap((item) => [item, ...flattenNavigation(item.children ?? [])]);
+}
+function isFilesystemNavigationFile(document) {
+  return isNavigationFile(document) || /(?:^|\/)\.navigation\.ya?ml$/u.test(document.file?.path ?? "");
+}
+function sourceDirectory(file) {
+  if (!file) return "";
+  const separator = file.lastIndexOf("/");
+  return separator < 0 ? "" : file.slice(0, separator);
+}
+async function portableFields(document, collection, graph, diagnostics) {
+  const shared = {};
+  const localized = {};
+  for (const field of collection.fields) {
+    if (field.role === "body" || !(field.key in document)) continue;
+    const value = await portableFieldValue(field, document[field.key], graph, document, diagnostics);
+    (field.localized ? localized : shared)[field.key] = value;
+  }
+  return { shared, localized };
+}
+async function portableFieldValue(field, value, graph, document, diagnostics) {
+  if (field.type === "relation" || field.type === "relations") {
+    const values = field.type === "relations" ? value : [value];
+    const refs = values.map((item) => {
+      if (typeof item !== "string") throw new TypeError(`Field "${field.key}" must contain source reference strings.`);
+      const canonicalKey = graph.referenceTargetsByCollection[field.relation.collection]?.get(item);
+      if (!canonicalKey) throw new TypeError(`Field "${field.key}" contains unresolved reference "${item}".`);
+      return { collection: field.relation.collection, canonicalKey };
+    });
+    return field.type === "relations" ? refs : refs[0];
+  }
+  if (field.type === "image" || field.type === "images") {
+    const values = field.type === "images" ? value : [value];
+    const refs = values.map((item) => {
+      if (typeof item === "string" && item.startsWith("https://")) return { kind: "external", url: item };
+      if (item && typeof item === "object") return assertPortableAssetReference(item);
+      throw new TypeError(`Field "${field.key}" uses a site-owned or unsupported asset; portable managed assets require explicit /ginko-assets identity and verified bytes.`);
+    });
+    return field.type === "images" ? refs : refs[0];
+  }
+  if ((field.type === "object" || field.type === "array" || field.type === "blocks") && field.fields) {
+    const convert = async (input) => {
+      if (!input || typeof input !== "object" || Array.isArray(input)) return input;
+      const output = {};
+      for (const child of field.fields) if (child.key in input) output[child.key] = await portableFieldValue(child, input[child.key], graph, document, diagnostics);
+      return output;
+    };
+    return Array.isArray(value) ? await Promise.all(value.map(convert)) : await convert(value);
+  }
+  canonicalJsonBytes(value);
+  void document;
+  void diagnostics;
+  return value;
+}
+async function materializeManagedAssets(rootDir, documents, contract, diagnostics) {
+  const referenced = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    const collection = contract.collections[document.collection];
+    if (!collection) continue;
+    try {
+      for (const reference of collectPortableAssetReferences(collection.fields, { ...document.shared, ...document.localized })) {
+        if (reference.kind === "local") referenced.set(reference.path, { sha256: reference.sha256, mediaType: reference.mediaType, collection: document.collection });
+      }
+      if (document.body) {
+        for (const reference of await collectPortableMdcAssetReferences(document.body.source, collection.componentPolicy)) {
+          referenced.set(reference.path, { ...reference, collection: document.collection });
+        }
+      }
+    } catch (error) {
+      diagnostic(
+        diagnostics,
+        boundaryCode(error, "DOCUMENT_INVALID"),
+        "portability.validateAssets",
+        document.collection,
+        null,
+        null,
+        message(error),
+        "Correct the managed asset reference in the source document."
+      );
+    }
+  }
+  const assets = [];
+  for (const [publicPath, reference] of [...referenced].sort(([left], [right]) => left.localeCompare(right))) {
+    const file = `public${publicPath}`;
+    try {
+      const path = join(rootDir, ...file.split("/"));
+      const before = await lstat(path);
+      const content = await readStableRegularFile(path, before, PORTABLE_CONTENT_LIMITS.assetBytes);
+      const verified = await verifyPublicImageBytes(content, reference.mediaType);
+      if (verified.sha256 !== reference.sha256) throw new TypeError("The asset bytes do not match the SHA-256 identity in the source reference.");
+      assets.push({ sha256: verified.sha256, file, bytes: verified.bytes, mediaType: verified.mediaType, content });
+    } catch (error) {
+      diagnostic(
+        diagnostics,
+        error instanceof StableFileError && error.reason === "limit" ? "LIMIT_EXCEEDED" : "ASSET_INTEGRITY_FAILED",
+        "portability.validateAssets",
+        reference.collection,
+        file,
+        null,
+        message(error),
+        "Restore the exact verified image at this public path, or correct the source reference."
+      );
+    }
+  }
+  return assets;
+}
+function markdownBody(source) {
+  const normalized = source.replace(/\r\n?/g, "\n");
+  if (!normalized.startsWith("---\n")) return normalized;
+  const end = normalized.indexOf("\n---\n", 4);
+  if (end < 0) {
+    if (normalized.endsWith("\n---")) return "";
+    throw new TypeError("Markdown frontmatter is not closed.");
+  }
+  return normalized.slice(end + 5);
+}
+function requiredRawSource(rawById, id) {
+  const source = rawById.get(id);
+  if (source === void 0) throw new TypeError(`Raw Markdown source is unavailable for "${id}".`);
+  return source;
+}
+function routeSlug(document, collection) {
+  if (collection.routing.singleton && collection.routing.rootSlug) return collection.routing.rootSlug;
+  const parts = (document.path ?? "").split("/").filter(Boolean);
+  const slug = parts[parts.length - 1];
+  if (!slug) throw new TypeError("A route-backed portable document requires a non-empty slug.");
+  return slug;
+}
+function treeParent(canonicalKey) {
+  const parts = canonicalKey.split("/").filter(Boolean);
+  return parts.length > 1 ? parts.slice(0, -1).join("/") : null;
+}
+function treeOrder(canonicalKey) {
+  const parts = canonicalKey.split("/");
+  const segment = parts[parts.length - 1] ?? "";
+  return /^\d+$/u.test(segment) ? BigInt(segment).toString(16).toUpperCase().padStart(16, "0") : null;
+}
+function searchVisible(search, collection) {
+  if (!search) return false;
+  if (search?.filterQuery && JSON.stringify(search.filterQuery) !== JSON.stringify({ partial: false })) {
+    throw new TypeError("Custom content.search.filterQuery cannot be represented as per-document portable visibility without evaluating the application query.");
+  }
+  return !search.collections || search.collections.includes(collection);
+}
+function normalizeSitemap(value) {
+  if (value === true) return { include: void 0, exclude: [] };
+  return { include: value.include, exclude: value.exclude ?? [] };
+}
+function diagnostic(target, code, operation, collection, file, field, message2, resolution) {
+  target.push({ severity: "error", code, operation, collection, file, field, message: message2, resolution });
+}
+function boundaryCode(error, fallback) {
+  return error instanceof GinkoBoundaryError ? error.code : fallback;
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function fieldFrom(error) {
+  const context = error?.context;
+  if (Array.isArray(context?.path)) return context.path.join(".");
+  if (typeof context?.details === "string") return context.details.split(":", 1)[0] ?? null;
+  return null;
+}
+function fieldFile(value) {
+  if (value && typeof value === "object") {
+    const item = value;
+    return item.file?.path ? `content/${item.file.path}` : item.context?.file ? `content/${item.context.file}` : null;
+  }
+  return null;
+}
+function variantKey(collection, canonicalKey, locale) {
+  return `${collection}\0${canonicalKey}\0${locale}`;
+}
+function summarize(documents, assets) {
+  return {
+    documents: documents.length,
+    assets: assets.length,
+    collections: [...new Set(documents.map((item) => item.collection))].sort(),
+    locales: [...new Set(documents.map((item) => item.locale))].sort()
+  };
+}
+function emptyAssessment(rootDir, diagnostics) {
+  return { ok: false, rootDir, contract: null, documents: [], assets: [], diagnostics, evidence: null, summary: { documents: 0, assets: 0, collections: [], locales: [] } };
+}
+async function firstExisting(rootDir, names) {
+  for (const name of names) try {
+    const path = join(rootDir, name);
+    if ((await lstat(path)).isFile()) return path;
+  } catch {
+  }
+  return null;
+}
+function unwrap(value) {
+  const record = value;
+  return record && typeof record === "object" && "default" in record ? record.default : value;
+}

package/dist/portability-node/index.d.ts

@@ -1,3 +1,4 @@
 export { readPortableDirectory, readPortableDirectoryForPlanning, verifyPortableDirectoryBounded, rebuildPortableDirectoryManifest, type PortableDirectoryAsset, type PortableDirectoryBundle, type PortableDirectoryDocument, type PortableDirectoryPlanningBundle, type PortableDirectoryPlanningDocument, type PortableDirectoryPlanningLimits, type PortableDirectoryVerification, } from './read-directory.js';
 export { writePortableDirectory, type PortableAssetWriteInput, type WritePortableDirectoryInput, } from './write-directory.js';
 export { assertPortablePathSet, validatePortableRelativePath } from './safe-path.js';
+export { assessFilesystemPortability, exportFilesystemToPortableDirectory, FilesystemPortabilityAssessmentError, type FilesystemPortabilityAssessment, type FilesystemPortabilityDiagnostic, type FilesystemPortabilityEvidence, type FilesystemPortabilityExportResult, } from './filesystem-export.js';

package/dist/portability-node/index.js

@@ -8,3 +8,8 @@ export {
   writePortableDirectory
 } from "./write-directory.js";
 export { assertPortablePathSet, validatePortableRelativePath } from "./safe-path.js";
+export {
+  assessFilesystemPortability,
+  exportFilesystemToPortableDirectory,
+  FilesystemPortabilityAssessmentError
+} from "./filesystem-export.js";

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "framework": "vue",
   "name": "@lupinum/ginko-content",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "contributions": {
     "html": {
       "description-markup": "markdown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "description": "Collection-first content engine for Nuxt",
   "homepage": "https://ginko-content.lupinum.com",
   "bugs": {
@@ -144,7 +144,7 @@
     "globby": "^16.2.0",
     "h3": "1.15.11",
     "jiti": "^2.7.0",
-    "js-yaml": "^4.3.1",
+    "js-yaml": "^4.3.2",
     "json5": "^2.2.3",
     "knitwork": "^1.3.0",
     "minisearch": "^7.2.0",