Fix zero value handling in CLI output and explicit file protocol configuration

docs.config.schema.json

@@ -61,7 +61,19 @@
 					}
 				},
 				"toc": {
-					"type": "boolean"
+					"anyOf": [
+						{
+							"type": "boolean"
+						},
+						{
+							"type": "string",
+							"enum": ["tree", "compressed"]
+						}
+					]
+				},
+				"tocFormat": {
+					"type": "string",
+					"enum": ["tree", "compressed"]
 				}
 			},
 			"additionalProperties": false
@@ -146,7 +158,19 @@
 						"additionalProperties": false
 					},
 					"toc": {
-						"type": "boolean"
+						"anyOf": [
+							{
+								"type": "boolean"
+							},
+							{
+								"type": "string",
+								"enum": ["tree", "compressed"]
+							}
+						]
+					},
+					"tocFormat": {
+						"type": "string",
+						"enum": ["tree", "compressed"]
 					}
 				},
 				"required": ["id", "repo"],

src/config-schema.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 export const TargetModeSchema = z.enum(["symlink", "copy"]);
 export const CacheModeSchema = z.enum(["materialize"]);
+export const TocFormatSchema = z.enum(["tree", "compressed"]);
 export const IntegritySchema = z
 	.object({
 		type: z.enum(["commit", "manifest"]),
@@ -20,7 +21,8 @@ export const DefaultsSchema = z
 		maxBytes: z.number().min(1),
 		maxFiles: z.number().min(1).optional(),
 		allowHosts: z.array(z.string().min(1)).min(1),
-		toc: z.boolean().optional(),
+		toc: z.union([z.boolean(), TocFormatSchema]).optional(),
+		tocFormat: TocFormatSchema.optional(),
 	})
 	.strict();
 
@@ -39,7 +41,8 @@ export const SourceSchema = z
 		maxBytes: z.number().min(1).optional(),
 		maxFiles: z.number().min(1).optional(),
 		integrity: IntegritySchema.optional(),
-		toc: z.boolean().optional(),
+		toc: z.union([z.boolean(), TocFormatSchema]).optional(),
+		tocFormat: TocFormatSchema.optional(),
 	})
 	.strict();
 

src/config.ts

@@ -6,6 +6,8 @@ import { assertSafeSourceId } from "./source-id";
 
 export type CacheMode = "materialize";
 
+export type TocFormat = "tree" | "compressed";
+
 export type IntegrityType = "commit" | "manifest";
 
 export interface DocsCacheIntegrity {
@@ -23,7 +25,8 @@ export interface DocsCacheDefaults {
 	maxBytes: number;
 	maxFiles?: number;
 	allowHosts: string[];
-	toc?: boolean;
+	toc?: boolean | TocFormat;
+	tocFormat?: TocFormat;
 }
 
 export interface DocsCacheSource {
@@ -40,7 +43,8 @@ export interface DocsCacheSource {
 	maxBytes?: number;
 	maxFiles?: number;
 	integrity?: DocsCacheIntegrity;
-	toc?: boolean;
+	toc?: boolean | TocFormat;
+	tocFormat?: TocFormat;
 }
 
 export interface DocsCacheConfig {
@@ -65,7 +69,8 @@ export interface DocsCacheResolvedSource {
 	maxBytes: number;
 	maxFiles?: number;
 	integrity?: DocsCacheIntegrity;
-	toc?: boolean;
+	toc?: boolean | TocFormat;
+	tocFormat?: TocFormat;
 }
 
 export const DEFAULT_CONFIG_FILENAME = "docs.config.json";
@@ -83,7 +88,7 @@ export const DEFAULT_CONFIG: DocsCacheConfig = {
 		required: true,
 		maxBytes: 200000000,
 		allowHosts: ["github.com", "gitlab.com"],
-		toc: true,
+		tocFormat: "compressed",
 	},
 	sources: [],
 };
@@ -233,6 +238,29 @@ const assertIntegrity = (value: unknown, label: string): DocsCacheIntegrity => {
 	return { type, value: integrityValue };
 };
 
+const normalizeTocConfig = (
+	toc: boolean | TocFormat | undefined,
+	tocFormat: TocFormat | undefined,
+): { toc?: boolean | TocFormat; tocFormat?: TocFormat } => {
+	// If tocFormat is explicitly set, use it (and keep toc if it was set too)
+	if (tocFormat !== undefined) {
+		if (toc !== undefined) {
+			return { toc, tocFormat };
+		}
+		return { tocFormat };
+	}
+	// If toc is a format string, set tocFormat but also keep toc
+	if (typeof toc === "string") {
+		return { toc, tocFormat: toc };
+	}
+	// If toc is a boolean, keep it and set tocFormat accordingly
+	if (typeof toc === "boolean") {
+		return { toc, tocFormat: toc ? "compressed" : undefined };
+	}
+	// Default case - no toc or tocFormat provided
+	return {};
+};
+
 export const validateConfig = (input: unknown): DocsCacheConfig => {
 	if (!isRecord(input)) {
 		throw new Error("Config must be a JSON object.");
@@ -260,6 +288,13 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 		if (!isRecord(defaultsInput)) {
 			throw new Error("defaults must be an object.");
 		}
+
+		// Normalize toc/tocFormat config for defaults
+		const normalizedToc = normalizeTocConfig(
+			defaultsInput.toc as boolean | TocFormat | undefined,
+			defaultsInput.tocFormat as TocFormat | undefined,
+		);
+
 		defaults = {
 			ref:
 				defaultsInput.ref !== undefined
@@ -297,10 +332,11 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 				defaultsInput.allowHosts !== undefined
 					? assertStringArray(defaultsInput.allowHosts, "defaults.allowHosts")
 					: defaultValues.allowHosts,
-			toc:
-				defaultsInput.toc !== undefined
-					? assertBoolean(defaultsInput.toc, "defaults.toc")
-					: defaultValues.toc,
+			toc: normalizedToc.toc,
+			tocFormat:
+				normalizedToc.tocFormat !== undefined
+					? normalizedToc.tocFormat
+					: defaultValues.tocFormat,
 		};
 	} else if (targetModeOverride !== undefined) {
 		defaults = {
@@ -387,9 +423,19 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 				`sources[${index}].integrity`,
 			);
 		}
-		if (entry.toc !== undefined) {
-			source.toc = assertBoolean(entry.toc, `sources[${index}].toc`);
+
+		// Normalize toc/tocFormat config for this source
+		const normalizedToc = normalizeTocConfig(
+			entry.toc as boolean | TocFormat | undefined,
+			entry.tocFormat as TocFormat | undefined,
+		);
+		if (normalizedToc.toc !== undefined) {
+			source.toc = normalizedToc.toc;
+		}
+		if (normalizedToc.tocFormat !== undefined) {
+			source.tocFormat = normalizedToc.tocFormat;
 		}
+
 		return source;
 	});
 
@@ -436,6 +482,7 @@ export const resolveSources = (
 		maxFiles: source.maxFiles ?? defaults.maxFiles,
 		integrity: source.integrity,
 		toc: source.toc ?? defaults.toc,
+		tocFormat: source.tocFormat ?? defaults.tocFormat,
 	}));
 };
 

src/toc.ts

@@ -1,6 +1,6 @@
 import { access, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import type { DocsCacheResolvedSource } from "./config";
+import type { DocsCacheResolvedSource, TocFormat } from "./config";
 import type { DocsCacheLock } from "./lock";
 import { DEFAULT_TOC_FILENAME, resolveTargetDir, toPosixPath } from "./paths";
 
@@ -69,7 +69,20 @@ const renderTocTree = (tree: TocTree, depth: number, lines: string[]) => {
 	}
 };
 
-const generateSourceToc = (entry: TocEntry): string => {
+const renderCompressedToc = (files: string[], lines: string[]) => {
+	// Sort files alphabetically
+	const sortedFiles = [...files].sort((a, b) => a.localeCompare(b));
+
+	// Render as a flat list with paths
+	for (const file of sortedFiles) {
+		lines.push(`- [${file}](./${file})`);
+	}
+};
+
+const generateSourceToc = (
+	entry: TocEntry,
+	format: TocFormat = "compressed",
+): string => {
 	const lines: string[] = [];
 	lines.push("---");
 	lines.push(`id: ${entry.id}`);
@@ -85,8 +98,15 @@ const generateSourceToc = (entry: TocEntry): string => {
 	lines.push("");
 	lines.push("## Files");
 	lines.push("");
-	const tree = createTocTree(entry.files);
-	renderTocTree(tree, 0, lines);
+
+	if (format === "tree") {
+		const tree = createTocTree(entry.files);
+		renderTocTree(tree, 0, lines);
+	} else {
+		// compressed format
+		renderCompressedToc(entry.files, lines);
+	}
+
 	lines.push("");
 
 	return lines.join("\n");
@@ -154,11 +174,25 @@ export const writeToc = async (params: {
 			files,
 		};
 
-		// Generate per-source TOC if the source has TOC enabled
-		const sourceToc = source?.toc ?? true;
+		// Determine if TOC should be generated and what format to use
+		const sourceTocConfig = source?.toc;
+		const sourceTocFormat = source?.tocFormat;
+
+		// Determine if TOC is enabled (default: true)
+		const tocEnabled = sourceTocConfig !== false;
+
+		// Determine TOC format
+		let tocFormat: TocFormat = "compressed"; // default
+		if (sourceTocFormat) {
+			tocFormat = sourceTocFormat;
+		} else if (typeof sourceTocConfig === "string") {
+			// Backward compatibility: if toc is a format string, use it
+			tocFormat = sourceTocConfig;
+		}
+
 		const sourceTocPath = path.join(sourceDir, DEFAULT_TOC_FILENAME);
 
-		if (sourceToc) {
+		if (tocEnabled) {
 			const result = resultsById.get(id);
 			if (result?.status === "up-to-date") {
 				try {
@@ -168,7 +202,7 @@ export const writeToc = async (params: {
 					// Missing TOC; regenerate below.
 				}
 			}
-			const sourceTocContent = generateSourceToc(entry);
+			const sourceTocContent = generateSourceToc(entry, tocFormat);
 			await writeFile(sourceTocPath, sourceTocContent, "utf8");
 		} else {
 			// Remove TOC.md if it exists but toc is disabled