@raystack/chronicle 0.4.0 → 0.5.0

package/dist/cli/index.js

@@ -68,7 +68,7 @@ import { remarkDirectiveAdmonition, remarkMdxMermaid } from "fumadocs-core/mdx-p
 import { defineConfig as defineFumadocsConfig } from "fumadocs-mdx/config";
 import mdx from "fumadocs-mdx/vite";
 import { nitro } from "nitro/vite";
-import fs2 from "node:fs/promises";
+import fs3 from "node:fs/promises";
 import path4 from "node:path";
 import remarkDirective from "remark-directive";
 function resolveOutputDir(projectRoot, preset) {
@@ -76,18 +76,23 @@ function resolveOutputDir(projectRoot, preset) {
     return path4.resolve(projectRoot, ".vercel/output");
   return path4.resolve(projectRoot, ".output");
 }
-async function readChronicleConfig(projectRoot, contentDir) {
-  for (const dir of [projectRoot, contentDir]) {
-    const filePath = path4.join(dir, "chronicle.yaml");
+async function readChronicleConfig(projectRoot, configPath) {
+  if (configPath) {
     try {
-      return await fs2.readFile(filePath, "utf-8");
-    } catch {}
+      return await fs3.readFile(configPath, "utf-8");
+    } catch (error) {
+      throw new Error(`Failed to read config file '${configPath}': ${error.message}`);
+    }
+  }
+  try {
+    return await fs3.readFile(path4.join(projectRoot, "chronicle.yaml"), "utf-8");
+  } catch {
+    return null;
   }
-  return null;
 }
 async function createViteConfig(options) {
-  const { packageRoot, projectRoot, contentDir, preset } = options;
-  const rawConfig = await readChronicleConfig(projectRoot, contentDir);
+  const { packageRoot, projectRoot, contentDir, configPath, preset } = options;
+  const rawConfig = await readChronicleConfig(projectRoot, configPath);
   return {
     root: packageRoot,
     configFile: false,
@@ -188,14 +193,131 @@ import chalk2 from "chalk";
 import { Command } from "commander";
 
 // src/cli/utils/config.ts
+import fs from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { parse } from "yaml";
-function resolveContentDir(contentFlag) {
+
+// src/types/config.ts
+import { z } from "zod";
+var logoSchema = z.object({
+  light: z.string().optional(),
+  dark: z.string().optional()
+});
+var themeSchema = z.object({
+  name: z.enum(["default", "paper"]),
+  colors: z.record(z.string(), z.string()).optional()
+});
+var navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string()
+});
+var socialLinkSchema = z.object({
+  type: z.string(),
+  href: z.string()
+});
+var navigationSchema = z.object({
+  links: z.array(navLinkSchema).optional(),
+  social: z.array(socialLinkSchema).optional()
+});
+var searchSchema = z.object({
+  enabled: z.boolean().optional(),
+  placeholder: z.string().optional()
+});
+var apiServerSchema = z.object({
+  url: z.string(),
+  description: z.string().optional()
+});
+var apiAuthSchema = z.object({
+  type: z.string(),
+  header: z.string(),
+  placeholder: z.string().optional()
+});
+var apiSchema = z.object({
+  name: z.string(),
+  spec: z.string(),
+  basePath: z.string(),
+  server: apiServerSchema,
+  auth: apiAuthSchema.optional()
+});
+var footerSchema = z.object({
+  copyright: z.string().optional(),
+  links: z.array(navLinkSchema).optional()
+});
+var llmsSchema = z.object({
+  enabled: z.boolean().optional()
+});
+var googleAnalyticsSchema = z.object({
+  measurementId: z.string()
+});
+var analyticsSchema = z.object({
+  enabled: z.boolean().optional(),
+  googleAnalytics: googleAnalyticsSchema.optional()
+});
+var chronicleConfigSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  url: z.string().optional(),
+  content: z.string().optional(),
+  preset: z.string().optional(),
+  logo: logoSchema.optional(),
+  theme: themeSchema.optional(),
+  navigation: navigationSchema.optional(),
+  search: searchSchema.optional(),
+  footer: footerSchema.optional(),
+  api: z.array(apiSchema).optional(),
+  llms: llmsSchema.optional(),
+  analytics: analyticsSchema.optional()
+});
+// src/cli/utils/config.ts
+function resolveConfigPath(configPath) {
+  if (configPath)
+    return path.resolve(configPath);
+  return;
+}
+async function readConfig(configPath) {
+  return fs.readFile(configPath, "utf-8").catch((error) => {
+    if (error.code === "ENOENT") {
+      console.log(chalk.red(`Error: chronicle.yaml not found at '${configPath}'`));
+      console.log(chalk.gray("Run 'chronicle init' to create one"));
+    } else {
+      console.log(chalk.red(`Error: Failed to read '${configPath}'`));
+      console.log(chalk.gray(error.message));
+    }
+    process.exit(1);
+  });
+}
+function validateConfig(raw, configPath) {
+  const parsed = parse(raw);
+  const result = chronicleConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    console.log(chalk.red(`Error: Invalid chronicle.yaml at '${configPath}'`));
+    for (const issue of result.error.issues) {
+      const path2 = issue.path.join(".");
+      console.log(chalk.gray(`  ${path2 ? `${path2}: ` : ""}${issue.message}`));
+    }
+    process.exit(1);
+  }
+  return result.data;
+}
+function resolveContentDir(config2, configPath, contentFlag) {
   if (contentFlag)
     return path.resolve(contentFlag);
+  if (config2.content)
+    return path.resolve(path.dirname(configPath), config2.content);
   return path.resolve("content");
 }
+function resolvePreset(config2, presetFlag) {
+  return presetFlag ?? config2.preset;
+}
+async function loadCLIConfig(configPath, options) {
+  const resolvedConfigPath = resolveConfigPath(configPath) ?? path.join(process.cwd(), "chronicle.yaml");
+  const raw = await readConfig(resolvedConfigPath);
+  const config2 = validateConfig(raw, resolvedConfigPath);
+  const contentDir = resolveContentDir(config2, resolvedConfigPath, options?.content);
+  const preset = resolvePreset(config2, options?.preset);
+  return { config: config2, configPath: resolvedConfigPath, contentDir, preset };
+}
 
 // src/cli/utils/resolve.ts
 import path2 from "path";
@@ -203,34 +325,38 @@ import { fileURLToPath } from "url";
 var PACKAGE_ROOT = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 // src/cli/utils/scaffold.ts
-import fs from "node:fs/promises";
+import fs2 from "node:fs/promises";
 import path3 from "node:path";
 async function linkContent(contentDir) {
   const linkPath = path3.join(PACKAGE_ROOT, ".content");
   const target = path3.resolve(contentDir);
   try {
-    const existing = await fs.readlink(linkPath);
+    const existing = await fs2.readlink(linkPath);
     if (existing === target)
       return;
-    await fs.unlink(linkPath);
+    await fs2.unlink(linkPath);
   } catch {}
-  await fs.symlink(target, linkPath);
+  await fs2.symlink(target, linkPath);
 }
 
 // src/cli/commands/build.ts
-var buildCommand = new Command("build").description("Build for production").option("-c, --content <path>", "Content directory").option("--preset <preset>", "Deploy preset (vercel, cloudflare, node-server)").action(async (options) => {
-  const contentDir = resolveContentDir(options.content);
+var buildCommand = new Command("build").description("Build for production").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").option("--preset <preset>", "Deploy preset (vercel, cloudflare, node-server)").action(async (options) => {
+  const { contentDir, configPath, preset } = await loadCLIConfig(options.config, {
+    content: options.content,
+    preset: options.preset
+  });
   await linkContent(contentDir);
   console.log(chalk2.cyan("Building for production..."));
   const { createBuilder } = await import("vite");
   const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_vite_config(), exports_vite_config));
-  const config = await createViteConfig2({
+  const config2 = await createViteConfig2({
     packageRoot: PACKAGE_ROOT,
     projectRoot: process.cwd(),
     contentDir,
-    preset: options.preset
+    configPath,
+    preset
   });
-  const builder = await createBuilder({ ...config, builder: {} });
+  const builder = await createBuilder({ ...config2, builder: {} });
   await builder.buildApp();
   console.log(chalk2.green("Build complete"));
   console.log(chalk2.cyan("Run `chronicle start` to start the server"));
@@ -239,24 +365,24 @@ var buildCommand = new Command("build").description("Build for production").opti
 // src/cli/commands/dev.ts
 import chalk3 from "chalk";
 import { Command as Command2 } from "commander";
-var devCommand = new Command2("dev").description("Start development server").option("-p, --port <port>", "Port number", "3000").option("-c, --content <path>", "Content directory").action(async (options) => {
-  const contentDir = resolveContentDir(options.content);
+var devCommand = new Command2("dev").description("Start development server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").action(async (options) => {
+  const { contentDir, configPath } = await loadCLIConfig(options.config, { content: options.content });
   const port = parseInt(options.port, 10);
   await linkContent(contentDir);
   console.log(chalk3.cyan("Starting dev server..."));
   const { createServer } = await import("vite");
   const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_vite_config(), exports_vite_config));
-  const config = await createViteConfig2({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir });
+  const config2 = await createViteConfig2({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
   const server = await createServer({
-    ...config,
-    server: { ...config.server, port }
+    ...config2,
+    server: { ...config2.server, port }
   });
   await server.listen();
   server.printUrls();
 });
 
 // src/cli/commands/init.ts
-import fs3 from "node:fs";
+import fs4 from "node:fs";
 import path5 from "node:path";
 import chalk4 from "chalk";
 import { Command as Command3 } from "commander";
@@ -280,37 +406,37 @@ This is your documentation home page.
 var initCommand = new Command3("init").description("Initialize a new Chronicle project").option("-c, --content <path>", "Content directory name", "content").action((options) => {
   const projectDir = process.cwd();
   const contentDir = path5.join(projectDir, options.content);
-  if (!fs3.existsSync(contentDir)) {
-    fs3.mkdirSync(contentDir, { recursive: true });
+  if (!fs4.existsSync(contentDir)) {
+    fs4.mkdirSync(contentDir, { recursive: true });
     console.log(chalk4.green("✓"), "Created", contentDir);
   }
   const configPath = path5.join(projectDir, "chronicle.yaml");
-  if (!fs3.existsSync(configPath)) {
-    fs3.writeFileSync(configPath, stringify(defaultConfig));
+  if (!fs4.existsSync(configPath)) {
+    fs4.writeFileSync(configPath, stringify(defaultConfig));
     console.log(chalk4.green("✓"), "Created", configPath);
   } else {
     console.log(chalk4.yellow("⚠"), configPath, "already exists");
   }
-  const contentFiles = fs3.readdirSync(contentDir);
+  const contentFiles = fs4.readdirSync(contentDir);
   if (contentFiles.length === 0) {
     const indexPath = path5.join(contentDir, "index.mdx");
-    fs3.writeFileSync(indexPath, sampleMdx);
+    fs4.writeFileSync(indexPath, sampleMdx);
     console.log(chalk4.green("✓"), "Created", indexPath);
   }
   const gitignorePath = path5.join(projectDir, ".gitignore");
   const gitignoreEntries = ["node_modules", "dist", ".output"];
-  if (fs3.existsSync(gitignorePath)) {
-    const existing = fs3.readFileSync(gitignorePath, "utf-8");
+  if (fs4.existsSync(gitignorePath)) {
+    const existing = fs4.readFileSync(gitignorePath, "utf-8");
     const missing = gitignoreEntries.filter((e) => !existing.includes(e));
     if (missing.length > 0) {
-      fs3.appendFileSync(gitignorePath, `
+      fs4.appendFileSync(gitignorePath, `
 ${missing.join(`
 `)}
 `);
       console.log(chalk4.green("✓"), "Added", missing.join(", "), "to .gitignore");
     }
   } else {
-    fs3.writeFileSync(gitignorePath, `${gitignoreEntries.join(`
+    fs4.writeFileSync(gitignorePath, `${gitignoreEntries.join(`
 `)}
 `);
     console.log(chalk4.green("✓"), "Created .gitignore");
@@ -324,23 +450,27 @@ Run`, chalk4.cyan("chronicle dev"), "to start development server");
 // src/cli/commands/serve.ts
 import chalk5 from "chalk";
 import { Command as Command4 } from "commander";
-var serveCommand = new Command4("serve").description("Build and start production server").option("-p, --port <port>", "Port number", "3000").option("-c, --content <path>", "Content directory").option("--preset <preset>", "Deploy preset (vercel, cloudflare, node-server)").action(async (options) => {
-  const contentDir = resolveContentDir(options.content);
+var serveCommand = new Command4("serve").description("Build and start production server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").option("--config <path>", "Path to chronicle.yaml").option("--preset <preset>", "Deploy preset (vercel, cloudflare, node-server)").action(async (options) => {
+  const { contentDir, configPath, preset } = await loadCLIConfig(options.config, {
+    content: options.content,
+    preset: options.preset
+  });
   const port = parseInt(options.port, 10);
   await linkContent(contentDir);
   const { build, preview } = await import("vite");
   const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_vite_config(), exports_vite_config));
-  const config = await createViteConfig2({
+  const config2 = await createViteConfig2({
     packageRoot: PACKAGE_ROOT,
     projectRoot: process.cwd(),
     contentDir,
-    preset: options.preset
+    configPath,
+    preset
   });
   console.log(chalk5.cyan("Building for production..."));
-  await build(config);
+  await build(config2);
   console.log(chalk5.cyan("Starting production server..."));
   const server = await preview({
-    ...config,
+    ...config2,
     preview: { port }
   });
   server.printUrls();
@@ -349,16 +479,16 @@ var serveCommand = new Command4("serve").description("Build and start production
 // src/cli/commands/start.ts
 import chalk6 from "chalk";
 import { Command as Command5 } from "commander";
-var startCommand = new Command5("start").description("Start production server").option("-p, --port <port>", "Port number", "3000").option("-c, --content <path>", "Content directory").action(async (options) => {
-  const contentDir = resolveContentDir(options.content);
+var startCommand = new Command5("start").description("Start production server").option("-p, --port <port>", "Port number", "3000").option("--content <path>", "Content directory").action(async (options) => {
+  const { contentDir, configPath } = await loadCLIConfig(undefined, { content: options.content });
   const port = parseInt(options.port, 10);
   await linkContent(contentDir);
   console.log(chalk6.cyan("Starting production server..."));
   const { preview } = await import("vite");
   const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_vite_config(), exports_vite_config));
-  const config = await createViteConfig2({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir });
+  const config2 = await createViteConfig2({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
   const server = await preview({
-    ...config,
+    ...config2,
     preview: { port }
   });
   server.printUrls();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -51,21 +51,22 @@
     "lodash": "^4.17.23",
     "mermaid": "^11.13.0",
     "minisearch": "^7.2.0",
-    "nitro": "latest",
+    "nitro": "3.0.260311-beta",
     "openapi-types": "^12.1.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-router": "^7.13.1",
     "remark-directive": "^4.0.0",
-    "remark-parse": "^11.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
     "remark-mdx-frontmatter": "^5.2.0",
+    "remark-parse": "^11.0.0",
     "satori": "^0.25.0",
     "slugify": "^1.6.6",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "vite": "^8.0.0",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
   }
 }

package/src/cli/commands/build.ts

@@ -1,18 +1,22 @@
 import chalk from 'chalk';
 import { Command } from 'commander';
-import { resolveContentDir } from '@/cli/utils/config';
+import { loadCLIConfig } from '@/cli/utils/config';
 import { PACKAGE_ROOT } from '@/cli/utils/resolve';
 import { linkContent } from '@/cli/utils/scaffold';
 
 export const buildCommand = new Command('build')
   .description('Build for production')
-  .option('-c, --content <path>', 'Content directory')
+  .option('--content <path>', 'Content directory')
+  .option('--config <path>', 'Path to chronicle.yaml')
   .option(
     '--preset <preset>',
     'Deploy preset (vercel, cloudflare, node-server)'
   )
   .action(async options => {
-    const contentDir = resolveContentDir(options.content);
+    const { contentDir, configPath, preset } = await loadCLIConfig(options.config, {
+      content: options.content,
+      preset: options.preset,
+    });
     await linkContent(contentDir);
 
     console.log(chalk.cyan('Building for production...'));
@@ -24,7 +28,8 @@ export const buildCommand = new Command('build')
       packageRoot: PACKAGE_ROOT,
       projectRoot: process.cwd(),
       contentDir,
-      preset: options.preset
+      configPath,
+      preset
     });
 
     const builder = await createBuilder({ ...config, builder: {} });

package/src/cli/commands/dev.ts

@@ -1,17 +1,16 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import chalk from 'chalk';
 import { Command } from 'commander';
-import { resolveContentDir } from '@/cli/utils/config';
+import { loadCLIConfig } from '@/cli/utils/config';
 import { PACKAGE_ROOT } from '@/cli/utils/resolve';
 import { linkContent } from '@/cli/utils/scaffold';
 
 export const devCommand = new Command('dev')
   .description('Start development server')
   .option('-p, --port <port>', 'Port number', '3000')
-  .option('-c, --content <path>', 'Content directory')
+  .option('--content <path>', 'Content directory')
+  .option('--config <path>', 'Path to chronicle.yaml')
   .action(async options => {
-    const contentDir = resolveContentDir(options.content);
+    const { contentDir, configPath } = await loadCLIConfig(options.config, { content: options.content });
     const port = parseInt(options.port, 10);
 
     await linkContent(contentDir);
@@ -21,7 +20,7 @@ export const devCommand = new Command('dev')
     const { createServer } = await import('vite');
     const { createViteConfig } = await import('@/server/vite-config');
 
-    const config = await createViteConfig({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir });
+    const config = await createViteConfig({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
     const server = await createServer({
       ...config,
       server: { ...config.server, port }

package/src/cli/commands/serve.ts

@@ -1,19 +1,23 @@
 import chalk from 'chalk';
 import { Command } from 'commander';
-import { resolveContentDir } from '@/cli/utils/config';
+import { loadCLIConfig } from '@/cli/utils/config';
 import { PACKAGE_ROOT } from '@/cli/utils/resolve';
 import { linkContent } from '@/cli/utils/scaffold';
 
 export const serveCommand = new Command('serve')
   .description('Build and start production server')
   .option('-p, --port <port>', 'Port number', '3000')
-  .option('-c, --content <path>', 'Content directory')
+  .option('--content <path>', 'Content directory')
+  .option('--config <path>', 'Path to chronicle.yaml')
   .option(
     '--preset <preset>',
     'Deploy preset (vercel, cloudflare, node-server)'
   )
   .action(async options => {
-    const contentDir = resolveContentDir(options.content);
+    const { contentDir, configPath, preset } = await loadCLIConfig(options.config, {
+      content: options.content,
+      preset: options.preset,
+    });
     const port = parseInt(options.port, 10);
     await linkContent(contentDir);
 
@@ -24,7 +28,8 @@ export const serveCommand = new Command('serve')
       packageRoot: PACKAGE_ROOT,
       projectRoot: process.cwd(),
       contentDir,
-      preset: options.preset
+      configPath,
+      preset
     });
 
     console.log(chalk.cyan('Building for production...'));

package/src/cli/commands/start.ts

@@ -1,15 +1,15 @@
 import chalk from 'chalk';
 import { Command } from 'commander';
-import { resolveContentDir } from '@/cli/utils/config';
+import { loadCLIConfig } from '@/cli/utils/config';
 import { PACKAGE_ROOT } from '@/cli/utils/resolve';
 import { linkContent } from '@/cli/utils/scaffold';
 
 export const startCommand = new Command('start')
   .description('Start production server')
   .option('-p, --port <port>', 'Port number', '3000')
-  .option('-c, --content <path>', 'Content directory')
+  .option('--content <path>', 'Content directory')
   .action(async options => {
-    const contentDir = resolveContentDir(options.content);
+    const { contentDir, configPath } = await loadCLIConfig(undefined, { content: options.content });
     const port = parseInt(options.port, 10);
     await linkContent(contentDir);
 
@@ -18,7 +18,7 @@ export const startCommand = new Command('start')
     const { preview } = await import('vite');
     const { createViteConfig } = await import('@/server/vite-config');
 
-    const config = await createViteConfig({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir });
+    const config = await createViteConfig({ packageRoot: PACKAGE_ROOT, projectRoot: process.cwd(), contentDir, configPath });
     const server = await preview({
       ...config,
       preview: { port }

package/src/cli/utils/config.ts

@@ -1,42 +1,71 @@
-import fs from 'node:fs';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import chalk from 'chalk';
 import { parse } from 'yaml';
-import type { ChronicleConfig } from '@/types';
+import { chronicleConfigSchema, type ChronicleConfig } from '@/types';
 
 export interface CLIConfig {
   config: ChronicleConfig;
   configPath: string;
   contentDir: string;
+  preset?: string;
 }
 
-export function resolveContentDir(contentFlag?: string): string {
-  if (contentFlag) return path.resolve(contentFlag);
-  return path.resolve('content');
+export function resolveConfigPath(configPath?: string): string | undefined {
+  if (configPath) return path.resolve(configPath);
+  return undefined;
 }
 
-function resolveConfigPath(contentDir: string): string | null {
-  const cwdPath = path.join(process.cwd(), 'chronicle.yaml');
-  if (fs.existsSync(cwdPath)) return cwdPath;
-  const contentPath = path.join(contentDir, 'chronicle.yaml');
-  if (fs.existsSync(contentPath)) return contentPath;
-  return null;
+async function readConfig(configPath: string): Promise<string> {
+  return fs.readFile(configPath, 'utf-8').catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') {
+      console.log(chalk.red(`Error: chronicle.yaml not found at '${configPath}'`));
+      console.log(chalk.gray("Run 'chronicle init' to create one"));
+    } else {
+      console.log(chalk.red(`Error: Failed to read '${configPath}'`));
+      console.log(chalk.gray(error.message));
+    }
+    process.exit(1);
+  });
 }
 
-export function loadCLIConfig(contentDir: string): CLIConfig {
-  const configPath = resolveConfigPath(contentDir);
+function validateConfig(raw: string, configPath: string): ChronicleConfig {
+  const parsed = parse(raw);
+  const result = chronicleConfigSchema.safeParse(parsed);
 
-  if (!configPath) {
-    console.log(
-      chalk.red(
-        `Error: chronicle.yaml not found in '${process.cwd()}' or '${contentDir}'`
-      )
-    );
-    console.log(chalk.gray("Run 'chronicle init' to create one"));
+  if (!result.success) {
+    console.log(chalk.red(`Error: Invalid chronicle.yaml at '${configPath}'`));
+    for (const issue of result.error.issues) {
+      const path = issue.path.join('.');
+      console.log(chalk.gray(`  ${path ? `${path}: ` : ''}${issue.message}`));
+    }
     process.exit(1);
   }
 
-  const config = parse(fs.readFileSync(configPath, 'utf-8')) as ChronicleConfig;
+  return result.data;
+}
+
+export function resolveContentDir(config: ChronicleConfig, configPath: string, contentFlag?: string): string {
+  if (contentFlag) return path.resolve(contentFlag);
+  if (config.content) return path.resolve(path.dirname(configPath), config.content);
+  return path.resolve('content');
+}
+
+export function resolvePreset(config: ChronicleConfig, presetFlag?: string): string | undefined {
+  return presetFlag ?? config.preset;
+}
+
+export async function loadCLIConfig(
+  configPath?: string,
+  options?: { content?: string; preset?: string }
+): Promise<CLIConfig> {
+  const resolvedConfigPath = resolveConfigPath(configPath)
+    ?? path.join(process.cwd(), 'chronicle.yaml');
+
+  const raw = await readConfig(resolvedConfigPath);
+  const config = validateConfig(raw, resolvedConfigPath);
+  const contentDir = resolveContentDir(config, resolvedConfigPath, options?.content);
+  const preset = resolvePreset(config, options?.preset);
 
-  return { config, configPath, contentDir };
+  return { config, configPath: resolvedConfigPath, contentDir, preset };
 }

package/src/server/vite-config.ts

@@ -19,26 +19,30 @@ export interface ViteConfigOptions {
   packageRoot: string;
   projectRoot: string;
   contentDir: string;
+  configPath?: string;
   preset?: string;
 }
 
-async function readChronicleConfig(projectRoot: string, contentDir: string): Promise<string | null> {
-  for (const dir of [projectRoot, contentDir]) {
-    const filePath = path.join(dir, 'chronicle.yaml');
+async function readChronicleConfig(projectRoot: string, configPath?: string): Promise<string | null> {
+  if (configPath) {
     try {
-      return await fs.readFile(filePath, 'utf-8');
-    } catch {
-      // not found, try next
+      return await fs.readFile(configPath, 'utf-8');
+    } catch (error) {
+      throw new Error(`Failed to read config file '${configPath}': ${(error as Error).message}`);
     }
   }
-  return null;
+  try {
+    return await fs.readFile(path.join(projectRoot, 'chronicle.yaml'), 'utf-8');
+  } catch {
+    return null;
+  }
 }
 
 export async function createViteConfig(
   options: ViteConfigOptions
 ): Promise<InlineConfig> {
-  const { packageRoot, projectRoot, contentDir, preset } = options;
-  const rawConfig = await readChronicleConfig(projectRoot, contentDir);
+  const { packageRoot, projectRoot, contentDir, configPath, preset } = options;
+  const rawConfig = await readChronicleConfig(projectRoot, configPath);
 
   return {
     root: packageRoot,

package/src/types/config.ts

@@ -1,80 +1,99 @@
-export interface ChronicleConfig {
-  title: string
-  description?: string
-  url?: string
-  logo?: LogoConfig
-  theme?: ThemeConfig
-  navigation?: NavigationConfig
-  search?: SearchConfig
-  footer?: FooterConfig
-  api?: ApiConfig[]
-  llms?: LlmsConfig
-  analytics?: AnalyticsConfig
-}
+import { z } from 'zod'
 
-export interface LlmsConfig {
-  enabled?: boolean
-}
+const logoSchema = z.object({
+  light: z.string().optional(),
+  dark: z.string().optional(),
+})
 
-export interface AnalyticsConfig {
-  enabled?: boolean
-  googleAnalytics?: GoogleAnalyticsConfig
-}
+const themeSchema = z.object({
+  name: z.enum(['default', 'paper']),
+  colors: z.record(z.string(), z.string()).optional(),
+})
 
-export interface GoogleAnalyticsConfig {
-  measurementId: string
-}
+const navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+})
 
-export interface ApiConfig {
-  name: string
-  spec: string
-  basePath: string
-  server: ApiServerConfig
-  auth?: ApiAuthConfig
-}
+const socialLinkSchema = z.object({
+  type: z.string(),
+  href: z.string(),
+})
 
-export interface ApiServerConfig {
-  url: string
-  description?: string
-}
+const navigationSchema = z.object({
+  links: z.array(navLinkSchema).optional(),
+  social: z.array(socialLinkSchema).optional(),
+})
 
-export interface ApiAuthConfig {
-  type: string
-  header: string
-  placeholder?: string
-}
+const searchSchema = z.object({
+  enabled: z.boolean().optional(),
+  placeholder: z.string().optional(),
+})
 
-export interface LogoConfig {
-  light?: string
-  dark?: string
-}
+const apiServerSchema = z.object({
+  url: z.string(),
+  description: z.string().optional(),
+})
 
-export interface ThemeConfig {
-  name: 'default' | 'paper'
-  colors?: Record<string, string>
-}
+const apiAuthSchema = z.object({
+  type: z.string(),
+  header: z.string(),
+  placeholder: z.string().optional(),
+})
 
-export interface NavigationConfig {
-  links?: NavLink[]
-  social?: SocialLink[]
-}
+const apiSchema = z.object({
+  name: z.string(),
+  spec: z.string(),
+  basePath: z.string(),
+  server: apiServerSchema,
+  auth: apiAuthSchema.optional(),
+})
 
-export interface NavLink {
-  label: string
-  href: string
-}
+const footerSchema = z.object({
+  copyright: z.string().optional(),
+  links: z.array(navLinkSchema).optional(),
+})
 
-export interface SocialLink {
-  type: 'github' | 'twitter' | 'discord' | string
-  href: string
-}
+const llmsSchema = z.object({
+  enabled: z.boolean().optional(),
+})
 
-export interface SearchConfig {
-  enabled?: boolean
-  placeholder?: string
-}
+const googleAnalyticsSchema = z.object({
+  measurementId: z.string(),
+})
 
-export interface FooterConfig {
-  copyright?: string
-  links?: NavLink[]
-}
+const analyticsSchema = z.object({
+  enabled: z.boolean().optional(),
+  googleAnalytics: googleAnalyticsSchema.optional(),
+})
+
+export const chronicleConfigSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  url: z.string().optional(),
+  content: z.string().optional(),
+  preset: z.string().optional(),
+  logo: logoSchema.optional(),
+  theme: themeSchema.optional(),
+  navigation: navigationSchema.optional(),
+  search: searchSchema.optional(),
+  footer: footerSchema.optional(),
+  api: z.array(apiSchema).optional(),
+  llms: llmsSchema.optional(),
+  analytics: analyticsSchema.optional(),
+})
+
+export type ChronicleConfig = z.infer<typeof chronicleConfigSchema>
+export type LogoConfig = z.infer<typeof logoSchema>
+export type ThemeConfig = z.infer<typeof themeSchema>
+export type NavigationConfig = z.infer<typeof navigationSchema>
+export type NavLink = z.infer<typeof navLinkSchema>
+export type SocialLink = z.infer<typeof socialLinkSchema>
+export type SearchConfig = z.infer<typeof searchSchema>
+export type ApiConfig = z.infer<typeof apiSchema>
+export type ApiServerConfig = z.infer<typeof apiServerSchema>
+export type ApiAuthConfig = z.infer<typeof apiAuthSchema>
+export type FooterConfig = z.infer<typeof footerSchema>
+export type LlmsConfig = z.infer<typeof llmsSchema>
+export type AnalyticsConfig = z.infer<typeof analyticsSchema>
+export type GoogleAnalyticsConfig = z.infer<typeof googleAnalyticsSchema>