@zpress/core 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -74,7 +74,7 @@ export declare interface CardConfig {
  */
 export declare interface ConfigError {
     readonly _tag: 'ConfigError';
-    readonly type: 'empty_sections' | 'missing_field' | 'duplicate_prefix' | 'invalid_icon' | 'invalid_entry' | 'missing_nav_icon';
+    readonly type: 'empty_sections' | 'missing_field' | 'duplicate_prefix' | 'invalid_icon' | 'invalid_entry';
     readonly message: string;
 }
 
@@ -98,21 +98,15 @@ export declare type ConfigResult<T> = readonly [ConfigError, null] | readonly [n
 export declare function createPaths(dir: string): Paths;
 
 /**
- * Type-safe config helper with validation.
+ * Type-safe config helper for user config files.
  *
- * Validates the config structure and exits with a clear error message
- * if any issues are found. This is the primary entry point for user-
- * provided config — validation happens at the boundary.
- *
- * `defineConfig` is called in user config files (e.g. `zpress.config.ts`)
- * where the return value is consumed by the c12 config loader, which
- * expects a plain `ZpressConfig` object — not a `Result` tuple.
- * Because this is the outermost user-facing boundary (not a library
- * function), `process.exit(1)` is acceptable here: the user must fix
- * their config before any downstream code can run.
+ * This is a passthrough that provides type safety and editor
+ * autocompletion in `zpress.config.ts`. Validation is deferred to
+ * `loadConfig` at CLI runtime, so errors surface with structured
+ * feedback rather than a raw `process.exit`.
  *
  * @param config - Raw zpress config object
- * @returns The validated config (unchanged)
+ * @returns The config (unchanged)
  */
 export declare function defineConfig(config: ZpressConfig): ZpressConfig;
 
@@ -252,9 +246,8 @@ export declare interface Entry {
      */
     readonly indexFile?: string;
     /**
-     * Iconify icon identifier for sidebar icon rail display.
-     * Format: `"prefix:name"` (e.g., `"pixelarticons:folder"`, `"devicon:typescript"`).
-     * Only meaningful on top-level sections — ignored on leaf pages.
+     * Iconify icon identifier (e.g. `"pixelarticons:speed-fast"`).
+     * Used on home page feature cards when auto-generated from sections.
      */
     readonly icon?: string;
     /**
@@ -401,10 +394,14 @@ declare type GlobPattern = string;
 export declare function hasGlobChars(s: string): boolean;
 
 /**
- * Load zpress config at runtime via c12.
+ * Load and validate zpress config at runtime via c12.
  *
- * Returns a `ConfigResult` tuple instead of calling `process.exit` — the
- * CLI boundary is responsible for surfacing the error and exiting.
+ * Returns a `ConfigResult` tuple — the CLI boundary is responsible for
+ * surfacing any error and exiting. Validation runs here (not in
+ * `defineConfig`) so every consumer gets structured error feedback.
+ *
+ * @param dir - Repository root directory to search for `zpress.config.*`
+ * @returns A `ConfigResult` tuple — `[null, config]` on success or `[ConfigError, null]` on failure
  */
 export declare function loadConfig(dir: string): Promise<ConfigResult<ZpressConfig>>;
 
@@ -461,12 +458,6 @@ export declare interface NavItem {
     readonly link?: UrlPath;
     readonly items?: readonly NavItem[];
     readonly activeMatch?: string;
-    /**
-     * Iconify icon identifier for nav bar display.
-     * Format: `"prefix:name"` (e.g., `"pixelarticons:folder"`, `"devicon:typescript"`).
-     * Required on top-level nav items when nav is explicit (validated at config boundary).
-     */
-    readonly icon?: string;
 }
 
 /**
@@ -662,10 +653,6 @@ export declare interface SidebarItem {
      */
     readonly collapsed?: boolean;
     readonly items?: readonly SidebarItem[];
-    /**
-     * Iconify identifier for sidebar icon rail. Only present on top-level sections.
-     */
-    readonly icon?: string;
 }
 
 /**
@@ -768,6 +755,14 @@ export declare interface SyncResult {
  */
 declare type UrlPath = string;
 
+/**
+ * Validate the entire config, returning the first error found.
+ *
+ * @param config - Raw zpress config object to validate
+ * @returns A `ConfigResult` tuple — `[null, config]` on success or `[ConfigError, null]` on failure
+ */
+export declare function validateConfig(config: ZpressConfig): ConfigResult<ZpressConfig>;
+
 /**
  * A named group of workspace items for custom workspace categories.
  *

package/dist/index.mjs

@@ -48,11 +48,6 @@ function collectResults(results) {
     ]);
 }
 function defineConfig(config) {
-    const [err] = validateConfig(config);
-    if (err) {
-        process.stderr.write(`[zpress] ${err.message}\n`);
-        process.exit(1);
-    }
     return config;
 }
 function validateConfig(config) {
@@ -90,11 +85,6 @@ function validateConfig(config) {
         featErr,
         null
     ];
-    const [navErr] = validateNav(config.nav);
-    if (navErr) return [
-        navErr,
-        null
-    ];
     return [
         null,
         config
@@ -227,29 +217,6 @@ function validateFeature(feature) {
     if (feature.icon && !feature.icon.includes(':')) return configError('invalid_icon', `Feature "${feature.text}": icon must be an Iconify identifier (e.g. "pixelarticons:speed-fast")`);
     return null;
 }
-function validateNav(nav) {
-    if ('auto' === nav || void 0 === nav) return [
-        null,
-        true
-    ];
-    const navError = nav.reduce((acc, item)=>{
-        if (acc) return acc;
-        return validateNavItem(item);
-    }, null);
-    if (navError) return [
-        navError,
-        null
-    ];
-    return [
-        null,
-        true
-    ];
-}
-function validateNavItem(item) {
-    if (!item.icon) return configError('missing_nav_icon', `NavItem "${item.text}": top-level nav items require an "icon" (Iconify identifier)`);
-    if (!item.icon.includes(':')) return configError('invalid_icon', `NavItem "${item.text}": icon must be an Iconify identifier (e.g. "pixelarticons:folder")`);
-    return null;
-}
 async function config_loadConfig(dir) {
     const { config } = await loadConfig({
         cwd: dir,
@@ -263,10 +230,7 @@ async function config_loadConfig(dir) {
         configError('empty_sections', 'Failed to load zpress.config — no sections found'),
         null
     ];
-    return [
-        null,
-        config
-    ];
+    return validateConfig(config);
 }
 const FIGLET_CHARS = Object.freeze({
     A: [
@@ -1457,7 +1421,7 @@ function buildFeatures(sections, repoRoot) {
     return Promise.all(sections.slice(0, 3).map(async (section, index)=>{
         const link = section.link ?? findFirstChildLink(section);
         const details = await extractSectionDescription(section, repoRoot);
-        const iconId = match(section.icon).with(P.nonNullable, (id)=>id).otherwise(()=>null);
+        const iconId = section.icon ?? null;
         const iconColor = ICON_COLORS[index % ICON_COLORS.length];
         return {
             title: section.text,
@@ -2168,13 +2132,12 @@ function deduplicateByLink(entries) {
     });
     return result;
 }
-function buildSidebarEntry(entry, icon) {
+function buildSidebarEntry(entry) {
     if (entry.items && entry.items.length > 0) return {
         text: entry.text,
         items: generateSidebar(entry.items),
         ...maybeCollapsed(entry.collapsible),
-        ...maybeLink(entry.link),
-        ...maybeIcon(icon)
+        ...maybeLink(entry.link)
     };
     if (null === entry.link || void 0 === entry.link) {
         log.error(`[zpress] Leaf entry "${entry.text}" has no link — skipping`);
@@ -2184,33 +2147,28 @@ function buildSidebarEntry(entry, icon) {
     }
     return {
         text: entry.text,
-        link: entry.link,
-        ...maybeIcon(icon)
+        link: entry.link
     };
 }
-function generateSidebar(entries, icons) {
+function generateSidebar(entries) {
     const visible = entries.filter((e)=>!e.hidden);
     const pages = visible.filter((e)=>!e.items || 0 === e.items.length);
     const sections = visible.filter((e)=>e.items && e.items.length > 0);
     return [
         ...pages,
         ...sections
-    ].map((entry)=>{
-        const icon = resolveIcon(icons, entry.text);
-        return buildSidebarEntry(entry, icon);
-    });
+    ].map(buildSidebarEntry);
 }
-function buildNavEntry(entry, icon) {
+function buildNavEntry(entry) {
     const link = sidebar_resolveLink(entry);
     const children = resolveChildren(entry);
     return {
         text: entry.text,
         link,
-        ...maybeIcon(icon),
         ...maybeChildren(children)
     };
 }
-function generateNav(config, resolved, icons) {
+function generateNav(config, resolved) {
     if ('auto' !== config.nav && void 0 !== config.nav) return [
         ...config.nav
     ];
@@ -2220,7 +2178,7 @@ function generateNav(config, resolved, icons) {
     return [
         ...nonIsolated,
         ...isolated
-    ].map((entry)=>buildNavEntry(entry, icons.get(entry.text))).filter((item)=>void 0 !== item.link);
+    ].map(buildNavEntry).filter((item)=>void 0 !== item.link);
 }
 function sidebar_findFirstLink(entry) {
     if (entry.link) return entry.link;
@@ -2241,15 +2199,6 @@ function maybeLink(link) {
     };
     return {};
 }
-function maybeIcon(icon) {
-    if (icon) return {
-        icon
-    };
-    return {};
-}
-function resolveIcon(icons, text) {
-    if (icons) return icons.get(text);
-}
 function sidebar_resolveLink(entry) {
     if (entry.link) return entry.link;
     return sidebar_findFirstLink(entry);
@@ -2379,10 +2328,10 @@ function resolveTags(tags) {
         ...tags
     ];
 }
-function buildMultiSidebar(resolved, openapiSidebar, icons) {
+function buildMultiSidebar(resolved, openapiSidebar) {
     const rootEntries = resolved.filter((e)=>!e.isolated);
     const isolatedEntries = resolved.filter((e)=>e.isolated && e.link);
-    const docsSidebar = generateSidebar(rootEntries, icons);
+    const docsSidebar = generateSidebar(rootEntries);
     const childrenByLink = new Map(isolatedEntries.map((entry)=>{
         const link = entry.link;
         const items = resolveEntryItems(entry.items);
@@ -2394,23 +2343,19 @@ function buildMultiSidebar(resolved, openapiSidebar, icons) {
     const isolatedSidebar = Object.fromEntries(isolatedEntries.flatMap((entry)=>{
         const entryLink = entry.link;
         const children = resolveChildrenByLink(childrenByLink, entryLink);
-        const icon = icons.get(entry.text);
         const parentLink = resolveParentLink(entryLink);
         const parentEntry = match(parentLink).with(P.nonNullable, (pl)=>isolatedEntries.find((e)=>e.link === pl)).otherwise(()=>{});
         const isChild = null != parentEntry && parentEntry !== entry;
         const landing = {
             text: entry.text,
-            link: entryLink,
-            ...multi_maybeIcon(icon)
+            link: entryLink
         };
         const sidebarItems = match(isChild).with(true, ()=>{
             const pe = parentEntry;
             const peLink = pe.link;
-            const parentIcon = icons.get(pe.text);
             const parentLanding = {
                 text: pe.text,
-                link: peLink,
-                ...multi_maybeIcon(parentIcon)
+                link: peLink
             };
             const siblings = isolatedEntries.filter((sib)=>{
                 const sibLink = sib.link;
@@ -2480,12 +2425,6 @@ function resolveParentLink(entryLink) {
     if (segments) return segments;
     return null;
 }
-function multi_maybeIcon(icon) {
-    if (icon) return {
-        icon
-    };
-    return {};
-}
 function buildSidebarGroup(text, link, children, collapsed) {
     if (children.length > 0) return {
         text,
@@ -2522,7 +2461,6 @@ function synthesizeWorkspaceSections(config) {
             text: 'Apps',
             link: '/apps',
             isolated: true,
-            icon: 'pixelarticons:device-laptop',
             frontmatter: {
                 description: 'Deployable applications that make up the platform.'
             },
@@ -2532,7 +2470,6 @@ function synthesizeWorkspaceSections(config) {
             text: 'Packages',
             link: '/packages',
             isolated: true,
-            icon: 'pixelarticons:archive',
             frontmatter: {
                 description: 'Shared libraries and utilities consumed across apps and services.'
             },
@@ -2545,7 +2482,6 @@ function synthesizeWorkspaceSections(config) {
             text: group.name,
             link,
             isolated: true,
-            icon: group.icon,
             frontmatter: {
                 description: group.description
             },
@@ -2766,9 +2702,8 @@ async function sync(config, options) {
         skipped: 0
     }));
     const removed = await match(previousManifest).with(P.nonNullable, async (m)=>await cleanStaleFiles(outDir, m, ctx.manifest)).otherwise(()=>Promise.resolve(0));
-    const icons = buildIconMap(allSections);
-    const sortedSidebar = buildMultiSidebar(resolved, openapiSidebar, icons);
-    const nav = generateNav(config, resolved, icons);
+    const sortedSidebar = buildMultiSidebar(resolved, openapiSidebar);
+    const nav = generateNav(config, resolved);
     await promises.writeFile(node_path.resolve(outDir, '.generated/sidebar.json'), JSON.stringify(sortedSidebar, null, 2), 'utf8');
     await promises.writeFile(node_path.resolve(outDir, '.generated/nav.json'), JSON.stringify(nav, null, 2), 'utf8');
     await saveManifest(outDir, ctx.manifest);
@@ -2864,17 +2799,6 @@ async function copyAll(src, dest) {
         else await promises.copyFile(srcPath, destPath);
     }, Promise.resolve());
 }
-function buildIconMap(sections) {
-    return new Map(sections.flatMap((section)=>{
-        if (section.icon) return [
-            [
-                section.text,
-                section.icon
-            ]
-        ];
-        return [];
-    }));
-}
 function resolveQuiet(quiet) {
     if (null != quiet) return quiet;
     return false;
@@ -2907,4 +2831,4 @@ function createPaths(dir) {
         cacheDir: node_path.resolve(outputRoot, 'cache')
     };
 }
-export { configError, config_loadConfig as loadConfig, createPaths, defineConfig, generateAssets, generateBannerSvg, generateIconSvg, generateLogoSvg, hasGlobChars, loadManifest, resolveEntries, sync, syncError };
+export { configError, config_loadConfig as loadConfig, createPaths, defineConfig, generateAssets, generateBannerSvg, generateIconSvg, generateLogoSvg, hasGlobChars, loadManifest, resolveEntries, sync, syncError, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zpress/core",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Config loading, sync engine, and asset utilities for zpress",
   "keywords": [
     "config",