includio-cms 0.20.0 → 0.22.0

package/dist/admin/client/collection/row-actions.svelte

@@ -51,18 +51,18 @@
 		</DropdownMenu.Item>
 		<DropdownMenu.Separator />
 		{#if onRestore}
-		<DropdownMenu.Item onclick={onRestore}>
+		<DropdownMenu.Item onclick={onRestore} data-testid="row-action-restore">
 			<ArchiveOff class="mr-2 size-4" />
 			{t.restore}
 		</DropdownMenu.Item>
 		{:else}
-		<DropdownMenu.Item onclick={onArchive}>
+		<DropdownMenu.Item onclick={onArchive} data-testid="row-action-archive">
 			<Archive class="mr-2 size-4" />
 			{t.archive}
 		</DropdownMenu.Item>
 		{/if}
 		{#if onDelete}
-		<DropdownMenu.Item class="text-destructive focus:text-destructive" onclick={onDelete}>
+		<DropdownMenu.Item class="text-destructive focus:text-destructive" onclick={onDelete} data-testid="row-action-delete">
 			<Trash class="mr-2 size-4" />
 			{t.delete}
 		</DropdownMenu.Item>

package/dist/admin/client/collection/table-toolbar.svelte

@@ -131,6 +131,7 @@
 					class="gap-1.5 {hasActiveFilter
 						? 'border-primary/30 bg-lavender-lighter text-primary'
 						: ''}"
+					data-testid="status-filter-trigger"
 				>
 					<Filter class="size-3.5" />
 					{t.status}{hasActiveFilter ? `: ${activeFilterLabel}` : ''}
@@ -148,6 +149,7 @@
 						onStatusFilterChange(option.value);
 						statusPopoverOpen = false;
 					}}
+					data-testid="status-filter-option-{option.value ?? 'all'}"
 				>
 					{option.label()}
 				</button>
@@ -228,7 +230,7 @@
 
 	<div class="flex-1"></div>
 
-	<Button variant="default" size="sm" onclick={onCreateEntry}>
+	<Button variant="default" size="sm" onclick={onCreateEntry} data-testid="create-entry-button">
 		<Plus class="mr-1 size-4" />
 		{createLabel}
 	</Button>

package/dist/admin/client/entry/entry-header.svelte

@@ -166,6 +166,7 @@
 				type="button"
 				class="bg-primary text-primary-foreground hover:bg-primary/90 inline-flex items-center gap-1.5 rounded-l-lg px-4 py-1.5 text-[13px] font-semibold transition-colors"
 				onclick={() => onSave('published-now')}
+				data-testid="publish-button"
 			>
 				<SendIcon class="size-3.5" />
 				{primaryButtonLabel}
@@ -179,13 +180,14 @@
 							type="button"
 							class="bg-primary text-primary-foreground hover:bg-primary/90 inline-flex items-center rounded-r-lg border-l border-white/20 px-1.5 py-1.5 transition-colors"
 							aria-label={lang[interfaceLanguage.current].saveDraft}
+							data-testid="save-draft-trigger"
 						>
 							<ChevronDownIcon class="size-3.5" />
 						</button>
 					{/snippet}
 				</DropdownMenu.Trigger>
 				<DropdownMenu.Content align="end" class="w-48">
-					<DropdownMenu.Item onclick={onSaveDraft}>
+					<DropdownMenu.Item onclick={onSaveDraft} data-testid="save-draft-button">
 						{lang[interfaceLanguage.current].saveDraft}
 						<DropdownMenu.Shortcut>{shortcutLabel}</DropdownMenu.Shortcut>
 					</DropdownMenu.Item>

package/dist/admin/client/users/create-user-dialog.svelte

@@ -141,12 +141,12 @@
 			<div class="space-y-2">
 				<Label>{lang.role}</Label>
 				<Select.Root type="single" value={role} onValueChange={(v) => v && (role = v as UserRole)}>
-					<Select.Trigger class="w-full" aria-describedby="create-role-hint">
+					<Select.Trigger class="w-full" aria-describedby="create-role-hint" data-testid="role-select">
 						{role === 'admin' ? lang.roleAdmin : lang.roleUser}
 					</Select.Trigger>
 					<Select.Content>
-						<Select.Item value="user">{lang.roleUser}</Select.Item>
-						<Select.Item value="admin">{lang.roleAdmin}</Select.Item>
+						<Select.Item value="user" data-testid="role-option-user">{lang.roleUser}</Select.Item>
+						<Select.Item value="admin" data-testid="role-option-admin">{lang.roleAdmin}</Select.Item>
 					</Select.Content>
 				</Select.Root>
 				<p id="create-role-hint" class="text-xs" style="color: var(--text-light);">
@@ -158,7 +158,7 @@
 			{/if}
 			<Dialog.Footer>
 				<Button type="button" variant="outline" onclick={() => onOpenChange(false)}>{lang.cancel}</Button>
-				<Button type="submit" disabled={loading}>{lang.createUser}</Button>
+				<Button type="submit" disabled={loading} data-testid="create-user-submit">{lang.createUser}</Button>
 			</Dialog.Footer>
 		</form>
 	</Dialog.Content>

package/dist/admin/client/users/delete-user-dialog.svelte

@@ -82,7 +82,7 @@
 							{lang.deleteWarningTitle}
 						</p>
 						<p class="mt-1 text-sm" style="color: var(--muted-foreground);">
-							{@html lang.deleteWarningDesc(user.name)}
+							{lang.deleteWarningDesc.before}<strong>{user.name}</strong>{lang.deleteWarningDesc.after}
 						</p>
 					</div>
 				</div>
@@ -90,13 +90,14 @@
 				<!-- Confirm input -->
 				<div class="space-y-2">
 					<Label for="delete-confirm">
-						{@html lang.deleteConfirmType}
+						{lang.deleteConfirmType.before}<strong>{lang.deleteConfirmWord}</strong>{lang.deleteConfirmType.after}
 					</Label>
 					<Input
 						id="delete-confirm"
 						bind:value={confirmInput}
 						placeholder={lang.deleteConfirmWord}
 						autocomplete="off"
+						data-testid="delete-confirm-input"
 					/>
 				</div>
 
@@ -108,6 +109,7 @@
 						variant="destructive"
 						disabled={!confirmed || loading}
 						onclick={handleDelete}
+						data-testid="delete-user-submit"
 					>
 						{lang.deleteUser}
 					</Button>

package/dist/admin/client/users/lang.d.ts

@@ -24,8 +24,16 @@ export declare const usersLang: Record<InterfaceLanguage, {
     deleteConfirmTitle: string;
     deleteConfirmDescription: string;
     deleteWarningTitle: string;
-    deleteWarningDesc: (name: string) => string;
-    deleteConfirmType: string;
+    /** Split into `before` / `after`; the user name is rendered between them in template (avoids `{@html}`). */
+    deleteWarningDesc: {
+        before: string;
+        after: string;
+    };
+    /** Split into `before` / `after`; `deleteConfirmWord` is rendered between them. */
+    deleteConfirmType: {
+        before: string;
+        after: string;
+    };
     deleteConfirmWord: string;
     userCreated: string;
     userUpdated: string;

package/dist/admin/client/users/lang.js

@@ -24,8 +24,11 @@ export const usersLang = {
         deleteConfirmTitle: 'Delete user?',
         deleteConfirmDescription: 'This action cannot be undone. The user will be permanently deleted.',
         deleteWarningTitle: 'This action cannot be undone',
-        deleteWarningDesc: (name) => `User <strong>${name}</strong> will be permanently deleted along with all their data.`,
-        deleteConfirmType: 'Type <strong>DELETE</strong> to confirm',
+        deleteWarningDesc: {
+            before: 'User ',
+            after: ' will be permanently deleted along with all their data.'
+        },
+        deleteConfirmType: { before: 'Type ', after: ' to confirm' },
         deleteConfirmWord: 'DELETE',
         userCreated: 'User created',
         userUpdated: 'User updated',
@@ -107,8 +110,11 @@ export const usersLang = {
         deleteConfirmTitle: 'Usunąć użytkownika?',
         deleteConfirmDescription: 'Ta akcja jest nieodwracalna. Użytkownik zostanie trwale usunięty.',
         deleteWarningTitle: 'Tej operacji nie można cofnąć',
-        deleteWarningDesc: (name) => `Użytkownik <strong>${name}</strong> zostanie trwale usunięty wraz ze wszystkimi danymi.`,
-        deleteConfirmType: 'Wpisz <strong>USUŃ</strong>, żeby potwierdzić',
+        deleteWarningDesc: {
+            before: 'Użytkownik ',
+            after: ' zostanie trwale usunięty wraz ze wszystkimi danymi.'
+        },
+        deleteConfirmType: { before: 'Wpisz ', after: ', żeby potwierdzić' },
         deleteConfirmWord: 'USUŃ',
         userCreated: 'Użytkownik utworzony',
         userUpdated: 'Użytkownik zaktualizowany',

package/dist/admin/client/users/users-page.svelte

@@ -360,7 +360,7 @@
 				{lang.invite.inviteUser}
 			</Button>
 		{/if}
-		<Button variant="default" size="sm" onclick={() => (createOpen = true)}>
+		<Button variant="default" size="sm" onclick={() => (createOpen = true)} data-testid="create-user-button">
 			<Plus class="size-4" />
 			{lang.createUser}
 		</Button>
@@ -384,7 +384,7 @@
 			<p class="mb-5 max-w-sm text-sm" style="color: var(--muted-foreground);">
 				{lang.emptyDescription}
 			</p>
-			<Button onclick={() => (createOpen = true)}>
+			<Button onclick={() => (createOpen = true)} data-testid="create-user-button">
 				<Plus class="size-4" />
 				{lang.addUser}
 			</Button>
@@ -518,6 +518,7 @@
 											class="text-destructive h-8 w-8"
 											onclick={() => openDelete(user)}
 											title={lang.deleteUser}
+											data-testid="delete-user-row-button"
 										>
 											<Trash class="size-4" />
 										</Button>

package/dist/admin/components/media/file-upload.svelte

@@ -218,6 +218,7 @@
 	type="button"
 	class="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-1.5 text-[13px] font-semibold text-primary-foreground transition-colors hover:bg-plum-dark whitespace-nowrap"
 	onclick={() => inputElement.click()}
+	data-testid="file-upload-button"
 >
 	<Upload class="h-4 w-4" />
 	{lang[interfaceLanguage.current].addFiles}
@@ -229,6 +230,7 @@
 	type="file"
 	{accept}
 	onchange={handleUpload}
+	data-testid="file-input"
 />
 
 <!-- Drag overlay -->

package/dist/ai-claude/index.d.ts

@@ -4,8 +4,16 @@ import type { AIAdapter, AIConfig } from '../types/adapters/ai.js';
  *
  * `@anthropic-ai/sdk` is an **optional peer dependency** — install it in your
  * project (`pnpm add @anthropic-ai/sdk`) when using this adapter. SDK loads
- * lazily on first call; missing peer throws a clear error.
+ * lazily on first call; a missing peer throws a clear error.
  *
+ * @param config - `apiKey` is required.
+ * @returns An `AIAdapter` ready to use in `defineConfig({ ai })`.
  * @public
+ * @example
+ * ```ts
+ * import { claudeAdapter } from 'includio-cms/ai-claude';
+ *
+ * const ai = claudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY! });
+ * ```
  */
 export declare function claudeAdapter(config: AIConfig): AIAdapter;

package/dist/ai-claude/index.js

@@ -5,9 +5,17 @@ import sharp from 'sharp';
  *
  * `@anthropic-ai/sdk` is an **optional peer dependency** — install it in your
  * project (`pnpm add @anthropic-ai/sdk`) when using this adapter. SDK loads
- * lazily on first call; missing peer throws a clear error.
+ * lazily on first call; a missing peer throws a clear error.
  *
+ * @param config - `apiKey` is required.
+ * @returns An `AIAdapter` ready to use in `defineConfig({ ai })`.
  * @public
+ * @example
+ * ```ts
+ * import { claudeAdapter } from 'includio-cms/ai-claude';
+ *
+ * const ai = claudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY! });
+ * ```
  */
 export function claudeAdapter(config) {
     let client = null;

package/dist/ai-openai/index.d.ts

@@ -4,8 +4,16 @@ import type { AIAdapter, AIConfig } from '../types/adapters/ai.js';
  *
  * `openai` is an **optional peer dependency** — install it in your project
  * (`pnpm add openai`) when using this adapter. SDK loads lazily on first call;
- * missing peer throws a clear error.
+ * a missing peer throws a clear error.
  *
+ * @param config - `apiKey` is required.
+ * @returns An `AIAdapter` ready to use in `defineConfig({ ai })`.
  * @public
+ * @example
+ * ```ts
+ * import { openAIAdapter } from 'includio-cms/ai-openai';
+ *
+ * const ai = openAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
+ * ```
  */
 export declare function openAIAdapter(config: AIConfig): AIAdapter;

package/dist/ai-openai/index.js

@@ -6,9 +6,17 @@ import sharp from 'sharp';
  *
  * `openai` is an **optional peer dependency** — install it in your project
  * (`pnpm add openai`) when using this adapter. SDK loads lazily on first call;
- * missing peer throws a clear error.
+ * a missing peer throws a clear error.
  *
+ * @param config - `apiKey` is required.
+ * @returns An `AIAdapter` ready to use in `defineConfig({ ai })`.
  * @public
+ * @example
+ * ```ts
+ * import { openAIAdapter } from 'includio-cms/ai-openai';
+ *
+ * const ai = openAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
+ * ```
  */
 export function openAIAdapter(config) {
     let openai = null;

package/dist/cli/index.js

@@ -4,30 +4,111 @@ import { installPeers } from './install-peers.js';
 import { createUser } from './create-user.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 const args = process.argv.slice(2);
 const command = args[0];
 const subcommand = args[1];
-function printUsage() {
-    console.log(`Usage: includio <command>
+const HELP_FLAGS = new Set(['--help', '-h']);
+const VERSION_FLAGS = new Set(['--version', '-v']);
+function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // In dist: dist/cli/index.js → ../../package.json
+        // In src dev:  src/lib/cli/index.ts → ../../../package.json
+        const candidates = [
+            path.resolve(here, '../../package.json'),
+            path.resolve(here, '../../../package.json')
+        ];
+        for (const c of candidates) {
+            if (fs.existsSync(c)) {
+                const pkg = JSON.parse(fs.readFileSync(c, 'utf-8'));
+                if (pkg?.name === 'includio-cms' && typeof pkg.version === 'string') {
+                    return pkg.version;
+                }
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return '0.0.0';
+}
+function printTopLevelHelp() {
+    console.log(`includio — CLI for includio-cms
+
+Usage: includio <command> [options]
 
 Commands:
-  scaffold admin    Generate admin route files
-  install-peers     Install missing peer dependencies
-  create-user       Create a new admin/user account
+  scaffold admin    Generate admin route files (/admin and /api/admin)
+  install-peers     Install missing optional peer dependencies
+  create-user       Create a new admin/user account interactively
+
+Global options:
+  --help, -h        Show this help
+  --version, -v     Print the package version
+
+Run \`includio <command> --help\` for command-specific options.
+`);
+}
+function printScaffoldAdminHelp() {
+    console.log(`includio scaffold admin — generate admin route files
+
+Usage: includio scaffold admin [options]
 
 Options:
-  --force           Overwrite existing files
-  --routes-dir      Path to routes directory (default: src/routes)
-  --cms-config      Path to cms config (default: src/lib/cms/cms.config.ts)
-  --shop            Force shop routes ON (default: auto-detect from cms config)
-  --no-shop         Force shop routes OFF
-  --dry-run         Show what would be installed (install-peers)
+  --force                 Overwrite existing files
+  --routes-dir <DIR>      Path to SvelteKit routes (default: src/routes)
+  --cms-config <FILE>     Path to CMS config (default: src/lib/cms/cms.config.ts)
+  --shop                  Force shop routes ON (overrides auto-detect)
+  --no-shop               Force shop routes OFF
+  --help, -h              Show this help
+
+Examples:
+  includio scaffold admin
+  includio scaffold admin --force --shop
+  includio scaffold admin --routes-dir apps/web/src/routes
+`);
+}
+function printInstallPeersHelp() {
+    console.log(`includio install-peers — install missing optional peer deps
+
+Reads your project's installed packages and offers to install any optional
+peers used by the parts of includio-cms you have configured (e.g. \`openai\`,
+\`@anthropic-ai/sdk\`, \`nodemailer\`).
+
+Usage: includio install-peers [options]
+
+Options:
+  --dry-run     List what would be installed, don't run the package manager
+  --help, -h    Show this help
+
+Examples:
+  includio install-peers --dry-run
+  includio install-peers
+`);
+}
+function printCreateUserHelp() {
+    console.log(`includio create-user — create an admin/user account
+
+Interactive prompt — asks for email, password, name, and role. Requires
+\`DATABASE_URL\` in the environment (or .env loaded by the project).
+
+Usage: includio create-user [options]
+
+Options:
+  --help, -h    Show this help
+
+Example:
+  includio create-user
 `);
 }
 function flagValue(name) {
     const idx = args.indexOf(name);
     return idx !== -1 ? args[idx + 1] : undefined;
 }
+function hasHelpFlag() {
+    return args.some((a) => HELP_FLAGS.has(a));
+}
 /**
  * Best-effort detection: scan cms config text for an active `shop: defineShop(`
  * or `shop: <var>` property inside `defineCMS({ ... })`. Returns null if the
@@ -43,7 +124,20 @@ function detectShopUsage(cmsConfigPath) {
         .replace(/\/\/[^\n]*/g, '');
     return /\bshop\s*:\s*\S/.test(stripped);
 }
+// Top-level: no command, --help, or --version
+if (!command || HELP_FLAGS.has(command)) {
+    printTopLevelHelp();
+    process.exit(0);
+}
+if (VERSION_FLAGS.has(command)) {
+    console.log(readPackageVersion());
+    process.exit(0);
+}
 if (command === 'scaffold' && subcommand === 'admin') {
+    if (hasHelpFlag()) {
+        printScaffoldAdminHelp();
+        process.exit(0);
+    }
     const force = args.includes('--force');
     const cwd = process.cwd();
     const routesDir = flagValue('--routes-dir') ?? path.join(cwd, 'src', 'routes');
@@ -73,13 +167,21 @@ if (command === 'scaffold' && subcommand === 'admin') {
     scaffoldAdmin({ routesDir, force, shop });
 }
 else if (command === 'install-peers') {
+    if (hasHelpFlag()) {
+        printInstallPeersHelp();
+        process.exit(0);
+    }
     const dryRun = args.includes('--dry-run');
     installPeers({ dryRun });
 }
 else if (command === 'create-user') {
+    if (hasHelpFlag()) {
+        printCreateUserHelp();
+        process.exit(0);
+    }
     createUser();
 }
 else {
-    printUsage();
-    process.exit(command ? 1 : 0);
+    printTopLevelHelp();
+    process.exit(1);
 }

package/dist/cms/runtime/schema.d.ts

@@ -0,0 +1,2 @@
+export * from 'includio-cms/db-postgres/schema-core';
+export * from 'includio-cms/auth-schema';

package/dist/cms/runtime/schema.js

@@ -0,0 +1,4 @@
+// This file is auto-generated. Do not edit directly.
+// Point your drizzle.config.ts schema field at this file.
+export * from 'includio-cms/db-postgres/schema-core';
+export * from 'includio-cms/auth-schema';

package/dist/cms/runtime/types.d.ts

@@ -44,7 +44,7 @@ export interface BlogPost {
     slug?: string;
     cover?: ImageFieldData | VideoFieldData | null;
     rating: number;
-    category?: 'technology' | 'design' | 'business' | 'tutorial';
+    category: 'technology' | 'design' | 'business' | 'tutorial';
     publishedAt?: string;
     thumbnail?: ImageFieldData | VideoFieldData | null;
     content?: StructuredContentDoc;

package/dist/core/cms.d.ts

@@ -39,7 +39,19 @@ export declare class CMS implements ICMS {
 }
 export declare function initCMS(config: CMSConfig): CMS;
 /**
- * Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
+ * Returns the singleton CMS instance. Must be called after `includioCMS()`
+ * initializes the CMS in `hooks.server.ts`.
+ *
+ * @returns The active `CMS` instance (collections, adapters, plugins, ...).
+ * @throws {Error} when called before `includioCMS()` has run (e.g. in plain
+ *   client code that imports `$lib/...` without going through SvelteKit hooks).
  * @public
+ * @example
+ * ```ts
+ * import { getCMS } from 'includio-cms';
+ *
+ * const cms = getCMS();
+ * await cms.databaseAdapter.getEntries({ slug: 'posts' });
+ * ```
  */
 export declare function getCMS(): CMS;

package/dist/core/cms.js

@@ -160,8 +160,20 @@ export function initCMS(config) {
     return cms;
 }
 /**
- * Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
+ * Returns the singleton CMS instance. Must be called after `includioCMS()`
+ * initializes the CMS in `hooks.server.ts`.
+ *
+ * @returns The active `CMS` instance (collections, adapters, plugins, ...).
+ * @throws {Error} when called before `includioCMS()` has run (e.g. in plain
+ *   client code that imports `$lib/...` without going through SvelteKit hooks).
  * @public
+ * @example
+ * ```ts
+ * import { getCMS } from 'includio-cms';
+ *
+ * const cms = getCMS();
+ * await cms.databaseAdapter.getEntries({ slug: 'posts' });
+ * ```
  */
 export function getCMS() {
     if (!cms) {

package/dist/core/errors.d.ts

@@ -0,0 +1,71 @@
+import type { ZodError } from 'zod';
+/**
+ * Base error class for CMS runtime failures. Carries a stable `code` and a
+ * `context` bag so callers (and clients) can branch on the failure mode without
+ * string-matching on `message`.
+ *
+ * `code` is a SCREAMING_SNAKE_CASE constant; see callers for the canonical list
+ * (`ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`,
+ * `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`).
+ *
+ * @public
+ * @example
+ * ```ts
+ * try { await resolveEntry({ id }); }
+ * catch (e) {
+ *   if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { ... }
+ * }
+ * ```
+ */
+export declare class CmsError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(code: string, message: string, context?: Record<string, unknown>, options?: {
+        cause?: unknown;
+    });
+    toString(): string;
+}
+/**
+ * One concrete validation issue extracted from a Zod error, with a friendly
+ * hint when the path matches a known config shape.
+ * @public
+ */
+export interface ConfigValidationIssue {
+    /** Dot/bracket-formatted path, e.g. `languages[0].code` or `collections[2].fields[0].slug`. */
+    path: string;
+    /** The validator's message, lightly normalized. */
+    message: string;
+    /** Optional hint describing how to fix this specific issue. */
+    hint?: string;
+}
+/**
+ * Thrown by {@link defineConfig} when the runtime config fails Zod validation.
+ * Aggregates ALL issues (not just the first) so the user can fix everything in
+ * one pass.
+ *
+ * @public
+ */
+export declare class ConfigValidationError extends CmsError {
+    readonly issues: ConfigValidationIssue[];
+    constructor(issues: ConfigValidationIssue[]);
+}
+/**
+ * Render a Zod issue path (`(string | number)[]`) into JS-style notation:
+ * - string segments → `.foo`
+ * - numeric segments → `[3]`
+ * - leading string segment has no leading dot.
+ */
+export declare function formatIssuePath(path: ReadonlyArray<string | number>): string;
+/**
+ * Render a `ZodError` from entry/form data validation as a list of
+ * `path: message` lines (one per issue). Used by data-write operations to give
+ * callers a readable dump instead of `JSON.stringify(error.flatten())`.
+ *
+ * @public
+ */
+export declare function formatZodDataIssues(error: ZodError): string;
+/**
+ * Convert a `ZodError` into a {@link ConfigValidationError} with friendly,
+ * path-prefixed messages and per-issue hints.
+ */
+export declare function formatConfigError(error: ZodError): ConfigValidationError;