CLI for exporting standard.site data to an output directory

bun.lock

···
   "configVersion": 1,
   "workspaces": {
     "": {
-      "name": "stdpub",
+      "name": "site-editor",
       "devDependencies": {
         "@biomejs/biome": "^2.3.11",
       },
     },
-    "packages/lib": {
-      "name": "@stdpub/lib",
+    "packages/cli": {
+      "name": "@stdsite/cli",
+      "version": "0.0.1",
+      "bin": {
+        "stdsite": "./src/index.ts",
+      },
+      "dependencies": {
+        "@stdsite/cli": ".",
+        "@stdsite/core": "workspace:*",
+        "commander": "^12.1.0",
+      },
+    },
+    "packages/core": {
+      "name": "@stdsite/core",
+      "version": "0.0.1",
+      "dependencies": {
+        "handlebars": "^4.7.8",
+      },
     },
     "packages/web": {
-      "name": "@stdpub/web",
+      "name": "@site-editor/web",
       "dependencies": {
         "@atproto/api": "^0.18.13",
         "@atproto/jwk-jose": "^0.1.11",
···
 
     "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.3.11", "", { "os": "win32", "cpu": "x64" }, "sha512-43VrG813EW+b5+YbDbz31uUsheX+qFKCpXeY9kfdAx+ww3naKxeVkTD9zLIWxUPfJquANMHrmW3wbe/037G0Qg=="],
 
-    "@stdpub/lib": ["@stdpub/lib@workspace:packages/lib"],
+    "@site-editor/web": ["@site-editor/web@workspace:packages/web"],
 
-    "@stdpub/web": ["@stdpub/web@workspace:packages/web"],
+    "@stdsite/cli": ["@stdsite/cli@workspace:packages/cli"],
+
+    "@stdsite/core": ["@stdsite/core@workspace:packages/core"],
 
     "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
···
 
     "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
+    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
     "core-js": ["core-js@3.47.0", "", {}, "sha512-c3Q2VVkGAUyupsjRnaNX6u8Dq2vAdzm9iuPj5FW0fRxzlxgq9Q39MDq10IvmQSpLgHQNyQzQmOo6bgGHmH3NNg=="],
+
+    "handlebars": ["handlebars@4.7.8", "", { "dependencies": { "minimist": "^1.2.5", "neo-async": "^2.6.2", "source-map": "^0.6.1", "wordwrap": "^1.0.0" }, "optionalDependencies": { "uglify-js": "^3.1.4" }, "bin": { "handlebars": "bin/handlebars" } }, "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ=="],
 
     "hono": ["hono@4.11.4", "", {}, "sha512-U7tt8JsyrxSRKspfhtLET79pU8K+tInj5QZXs1jSugO1Vq5dFj3kmZsRldo29mTBfcjDRVRXrEZ6LS63Cog9ZA=="],
 
···
 
     "marked": ["marked@15.0.12", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA=="],
 
+    "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
+
     "multiformats": ["multiformats@9.9.0", "", {}, "sha512-HoMUjhH9T8DDBNT+6xzkrd9ga/XiBI4xLr58LJACwK6G3HTOPeMz4nB4KJs33L2BelrIJa7P0VuNaVF3hMYfjg=="],
 
+    "neo-async": ["neo-async@2.6.2", "", {}, "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw=="],
+
+    "source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
+
     "tlds": ["tlds@1.261.0", "", { "bin": { "tlds": "bin.js" } }, "sha512-QXqwfEl9ddlGBaRFXIvNKK6OhipSiLXuRuLJX5DErz0o0Q0rYxulWLdFryTkV5PkdZct5iMInwYEGe/eR++1AA=="],
 
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "uglify-js": ["uglify-js@3.19.3", "", { "bin": { "uglifyjs": "bin/uglifyjs" } }, "sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ=="],
 
     "uint8arrays": ["uint8arrays@3.0.0", "", { "dependencies": { "multiformats": "^9.4.2" } }, "sha512-HRCx0q6O9Bfbp+HHSfQQKD7wU70+lydKVt4EghkdOvlK/NlrF90z+eXV34mUd48rNvVJXwkrMSPpCATkct8fJA=="],
 
···
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
     "unicode-segmenter": ["unicode-segmenter@0.14.5", "", {}, "sha512-jHGmj2LUuqDcX3hqY12Ql+uhUTn8huuxNZGq7GvtF6bSybzH3aFgedYu/KTzQStEgt1Ra2F3HxadNXsNjb3m3g=="],
+
+    "wordwrap": ["wordwrap@1.0.0", "", {}, "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q=="],
 
     "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
   }

package.json

···
 {
-  "name": "stdpub",
+  "name": "site-editor",
   "private": true,
   "workspaces": [
     "packages/*"

packages/cli/package.json

···
+{
+	"name": "@stdsite/cli",
+	"type": "module",
+	"version": "0.0.1",
+	"bin": {
+		"stdsite": "./src/index.ts"
+	},
+	"dependencies": {
+		"@stdsite/cli": "workspace:*",
+		"@stdsite/core": "workspace:*",
+		"commander": "^12.1.0"
+	}
+}

packages/cli/src/index.ts

···
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import {
+	DEFAULT_FILENAME_TEMPLATE,
+	exportPublication,
+} from "@stdsite/core";
+
+const program = new Command();
+
+program
+	.name("stdsite")
+	.description("CLI tools for standard.site publications")
+	.version("0.0.1");
+
+program
+	.command("export")
+	.description("Export a publication to markdown files")
+	.argument("<at-uri>", "AT URI of the publication to export")
+	.requiredOption("-o, --output <dir>", "Output directory for markdown files")
+	.option("-t, --template <file>", "Path to custom content template file")
+	.option("--filename-template <template>", "Handlebars template for filenames")
+	.option(
+		"--include-tags <tags>",
+		"Only include documents with these tags (comma-separated)",
+	)
+	.option(
+		"--exclude-tags <tags>",
+		"Exclude documents with these tags (comma-separated)",
+	)
+	.action(
+		async (
+			atUri: string,
+			options: {
+				output: string;
+				template?: string;
+				filenameTemplate?: string;
+				includeTags?: string;
+				excludeTags?: string;
+			},
+		) => {
+			try {
+				// Parse tag options
+				const includeTags = options.includeTags
+					? options.includeTags.split(",").map((t) => t.trim())
+					: undefined;
+				const excludeTags = options.excludeTags
+					? options.excludeTags.split(",").map((t) => t.trim())
+					: undefined;
+
+				// Load custom content template if provided
+				let contentTemplate: string | undefined;
+				if (options.template) {
+					const templatePath = resolve(options.template);
+					contentTemplate = await readFile(templatePath, "utf-8");
+				}
+
+				// Use custom filename template or default
+				const filenameTemplate =
+					options.filenameTemplate || DEFAULT_FILENAME_TEMPLATE;
+
+				console.log(`Exporting publication: ${atUri}`);
+				console.log(`Output directory: ${options.output}`);
+
+				const result = await exportPublication({
+					publicationUri: atUri,
+					outputDir: resolve(options.output),
+					contentTemplate,
+					filenameTemplate,
+					includeTags,
+					excludeTags,
+				});
+
+				console.log(`\nExport complete:`);
+				console.log(`  Documents processed: ${result.documentsProcessed}`);
+				console.log(`  Documents skipped: ${result.documentsSkipped}`);
+				console.log(`  Files written: ${result.filesWritten.length}`);
+
+				if (result.warnings.length > 0) {
+					console.log(`\nWarnings:`);
+					for (const warning of result.warnings) {
+						console.log(`  - ${warning}`);
+					}
+				}
+
+				if (result.filesWritten.length > 0) {
+					console.log(`\nFiles:`);
+					for (const file of result.filesWritten) {
+						console.log(`  - ${file}`);
+					}
+				}
+			} catch (error) {
+				console.error(
+					`Error: ${error instanceof Error ? error.message : String(error)}`,
+				);
+				process.exit(1);
+			}
+		},
+	);
+
+program.parse();

packages/core/package.json

···
+{
+	"name": "@stdsite/core",
+	"type": "module",
+	"version": "0.0.1",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"dependencies": {
+		"handlebars": "^4.7.8"
+	}
+}

packages/core/src/atproto.ts

···
+import type { Document, Publication } from "./types.ts";
+
+const DOCUMENT_COLLECTION = "site.standard.document";
+const PUBLICATION_COLLECTION = "site.standard.publication";
+
+interface AtUri {
+	did: string;
+	collection: string;
+	rkey: string;
+}
+
+/**
+ * Parse an AT URI into its components
+ * Format: at://did:plc:xyz/collection/rkey
+ */
+export function parseAtUri(uri: string): AtUri {
+	const match = uri.match(/^at:\/\/(did:[^/]+)\/([^/]+)\/([^/]+)$/);
+	if (!match) {
+		throw new Error(`Invalid AT URI: ${uri}`);
+	}
+	return {
+		did: match[1],
+		collection: match[2],
+		rkey: match[3],
+	};
+}
+
+/**
+ * Get the PDS endpoint for a DID by resolving through plc.directory
+ */
+export async function getPdsEndpoint(did: string): Promise<string> {
+	const response = await fetch(`https://plc.directory/${did}`);
+	if (!response.ok) {
+		throw new Error(`Failed to resolve DID ${did}: ${response.status}`);
+	}
+
+	const doc = (await response.json()) as {
+		service?: Array<{ id: string; serviceEndpoint: string }>;
+	};
+	const pdsService = doc.service?.find((s) => s.id === "#atproto_pds");
+
+	if (!pdsService) {
+		throw new Error(`No PDS service found for DID ${did}`);
+	}
+
+	return pdsService.serviceEndpoint;
+}
+
+/**
+ * Fetch a publication record from a PDS
+ */
+export async function fetchPublication(
+	pdsEndpoint: string,
+	did: string,
+	rkey: string,
+): Promise<Publication> {
+	const url = `${pdsEndpoint}/xrpc/com.atproto.repo.getRecord?repo=${encodeURIComponent(did)}&collection=${PUBLICATION_COLLECTION}&rkey=${encodeURIComponent(rkey)}`;
+
+	const response = await fetch(url);
+	if (!response.ok) {
+		throw new Error(`Failed to fetch publication: ${response.status}`);
+	}
+
+	const data = (await response.json()) as { value: Publication };
+	return data.value;
+}
+
+/**
+ * Fetch all documents for a publication from a PDS
+ */
+export async function fetchDocuments(
+	pdsEndpoint: string,
+	did: string,
+	publicationUri: string,
+): Promise<Document[]> {
+	const documents: Document[] = [];
+	let cursor: string | undefined;
+
+	do {
+		const params = new URLSearchParams({
+			repo: did,
+			collection: DOCUMENT_COLLECTION,
+			limit: "100",
+		});
+		if (cursor) {
+			params.set("cursor", cursor);
+		}
+
+		const url = `${pdsEndpoint}/xrpc/com.atproto.repo.listRecords?${params}`;
+		const response = await fetch(url);
+
+		if (!response.ok) {
+			throw new Error(`Failed to fetch documents: ${response.status}`);
+		}
+
+		const data = (await response.json()) as {
+			records: Array<{ value: Document }>;
+			cursor?: string;
+		};
+
+		// Filter to only documents belonging to this publication
+		for (const record of data.records) {
+			if (record.value.site === publicationUri) {
+				documents.push(record.value);
+			}
+		}
+
+		cursor = data.cursor;
+	} while (cursor);
+
+	return documents;
+}
+
+/**
+ * Fetch a publication and its documents given a publication AT URI
+ */
+export async function fetchPublicationWithDocuments(
+	publicationUri: string,
+): Promise<{
+	publication: Publication;
+	documents: Document[];
+}> {
+	const { did, collection, rkey } = parseAtUri(publicationUri);
+
+	if (collection !== PUBLICATION_COLLECTION) {
+		throw new Error(
+			`Expected ${PUBLICATION_COLLECTION} collection, got ${collection}`,
+		);
+	}
+
+	const pdsEndpoint = await getPdsEndpoint(did);
+	const publication = await fetchPublication(pdsEndpoint, did, rkey);
+	const documents = await fetchDocuments(pdsEndpoint, did, publicationUri);
+
+	return { publication, documents };
+}

packages/core/src/export.ts

···
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fetchPublicationWithDocuments } from "./atproto.ts";
+import {
+	createHandlebars,
+	DEFAULT_CONTENT_TEMPLATE,
+	DEFAULT_FILENAME_TEMPLATE,
+	generateContent,
+	generateFilename,
+} from "./templates.ts";
+import type {
+	Document,
+	ExportOptions,
+	ExportResult,
+	Publication,
+	TemplateData,
+} from "./types.ts";
+
+/**
+ * Get the text content from a document, handling different content formats
+ */
+function getDocumentContent(doc: Document): string {
+	// textContent is the raw markdown
+	if (doc.textContent) {
+		return doc.textContent;
+	}
+	// content might be a string or structured content
+	if (typeof doc.content === "string") {
+		return doc.content;
+	}
+	return "";
+}
+
+/**
+ * Filter documents based on tag inclusion/exclusion rules
+ */
+function filterDocuments(
+	documents: Document[],
+	includeTags?: string[],
+	excludeTags?: string[],
+): { included: Document[]; skipped: number } {
+	let filtered = documents;
+	let skipped = 0;
+
+	// If includeTags specified, only keep docs with at least one matching tag
+	if (includeTags && includeTags.length > 0) {
+		filtered = filtered.filter((doc) => {
+			const docTags = doc.tags || [];
+			const matches = includeTags.some((tag) => docTags.includes(tag));
+			if (!matches) skipped++;
+			return matches;
+		});
+	} else {
+		// Default behavior: exclude drafts unless explicitly included
+		filtered = filtered.filter((doc) => {
+			const docTags = doc.tags || [];
+			const isDraft = docTags.includes("draft");
+			if (isDraft) skipped++;
+			return !isDraft;
+		});
+	}
+
+	// Exclude docs with any of the excludeTags
+	if (excludeTags && excludeTags.length > 0) {
+		const beforeExclude = filtered.length;
+		filtered = filtered.filter((doc) => {
+			const docTags = doc.tags || [];
+			return !excludeTags.some((tag) => docTags.includes(tag));
+		});
+		skipped += beforeExclude - filtered.length;
+	}
+
+	return { included: filtered, skipped };
+}
+
+/**
+ * Build template data from a document and publication
+ */
+function buildTemplateData(
+	doc: Document,
+	publication: Publication,
+): TemplateData {
+	return {
+		title: doc.title,
+		path: doc.path,
+		description: doc.description,
+		content: getDocumentContent(doc),
+		tags: doc.tags || [],
+		publishedAt: doc.publishedAt,
+		updatedAt: doc.updatedAt,
+		publication: {
+			name: publication.name,
+			url: publication.url,
+			description: publication.description,
+		},
+	};
+}
+
+/**
+ * Export a publication to markdown files
+ */
+export async function exportPublication(
+	options: ExportOptions,
+): Promise<ExportResult> {
+	const {
+		publicationUri,
+		outputDir,
+		contentTemplate = DEFAULT_CONTENT_TEMPLATE,
+		filenameTemplate = DEFAULT_FILENAME_TEMPLATE,
+		includeTags,
+		excludeTags,
+	} = options;
+
+	const result: ExportResult = {
+		filesWritten: [],
+		documentsProcessed: 0,
+		documentsSkipped: 0,
+		warnings: [],
+	};
+
+	// Fetch publication and documents
+	const { publication, documents } =
+		await fetchPublicationWithDocuments(publicationUri);
+
+	// Filter documents by tags
+	const { included, skipped } = filterDocuments(
+		documents,
+		includeTags,
+		excludeTags,
+	);
+	result.documentsSkipped = skipped;
+
+	// Create output directory
+	await mkdir(outputDir, { recursive: true });
+
+	// Track filenames to detect conflicts
+	const usedFilenames = new Set<string>();
+
+	// Set up Handlebars
+	const hbs = createHandlebars();
+
+	// Process each document
+	for (const doc of included) {
+		result.documentsProcessed++;
+
+		const data = buildTemplateData(doc, publication);
+
+		// Generate filename
+		const filename = generateFilename(hbs, filenameTemplate, data);
+
+		if (!filename) {
+			result.warnings.push(
+				`Skipping document "${doc.title}": could not generate filename`,
+			);
+			result.documentsSkipped++;
+			continue;
+		}
+
+		// Check for filename conflicts
+		if (usedFilenames.has(filename)) {
+			result.warnings.push(
+				`Skipping document "${doc.title}": filename conflict with "${filename}"`,
+			);
+			result.documentsSkipped++;
+			continue;
+		}
+		usedFilenames.add(filename);
+
+		// Generate content
+		const content = generateContent(hbs, contentTemplate, data);
+
+		// Write file
+		const filePath = join(outputDir, filename);
+		await writeFile(filePath, content, "utf-8");
+		result.filesWritten.push(filePath);
+	}
+
+	return result;
+}

packages/core/src/index.ts

···
+// Main export function
+export { exportPublication } from "./export.ts";
+
+// Templates
+export {
+	DEFAULT_CONTENT_TEMPLATE,
+	DEFAULT_FILENAME_TEMPLATE,
+	createHandlebars,
+	generateContent,
+	generateFilename,
+	renderTemplate,
+} from "./templates.ts";
+
+// AT Protocol utilities
+export {
+	fetchDocuments,
+	fetchPublication,
+	fetchPublicationWithDocuments,
+	getPdsEndpoint,
+	parseAtUri,
+} from "./atproto.ts";
+
+// Types
+export type {
+	Document,
+	ExportOptions,
+	ExportResult,
+	Publication,
+	TemplateData,
+} from "./types.ts";

packages/core/src/templates.ts

···
+import Handlebars from "handlebars";
+import type { TemplateData } from "./types.ts";
+
+/**
+ * Default template for generating filenames
+ */
+export const DEFAULT_FILENAME_TEMPLATE = `{{dateFormat publishedAt "YYYY-MM-DD"}}_{{slug (default path title)}}.md`;
+
+/**
+ * Default template for generating file content
+ */
+export const DEFAULT_CONTENT_TEMPLATE = `---
+title: "{{title}}"
+date: {{publishedAt}}
+{{#if tags.length}}
+tags:
+{{#each tags}}
+  - {{this}}
+{{/each}}
+{{/if}}
+---
+
+{{content}}
+`;
+
+/**
+ * Convert a string to a URL-safe slug
+ */
+function slugify(text: string): string {
+	return text
+		.toString()
+		.toLowerCase()
+		.trim()
+		.replace(/^\/+/, "") // Remove leading slashes
+		.replace(/\/+$/, "") // Remove trailing slashes
+		.replace(/\s+/g, "-") // Replace spaces with -
+		.replace(/[^\w-]+/g, "") // Remove non-word chars (except -)
+		.replace(/--+/g, "-") // Replace multiple - with single -
+		.replace(/^-+/, "") // Trim - from start
+		.replace(/-+$/, ""); // Trim - from end
+}
+
+/**
+ * Format a date string
+ */
+function formatDate(dateStr: string | undefined, format: string): string {
+	if (!dateStr) {
+		return "";
+	}
+
+	const date = new Date(dateStr);
+	if (Number.isNaN(date.getTime())) {
+		return "";
+	}
+
+	// Simple format replacements
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+
+	return format
+		.replace("YYYY", String(year))
+		.replace("MM", month)
+		.replace("DD", day);
+}
+
+/**
+ * Register custom Handlebars helpers
+ */
+function registerHelpers(hbs: typeof Handlebars): void {
+	// Slug helper: {{slug text}}
+	hbs.registerHelper("slug", (text: unknown) => {
+		if (typeof text !== "string") {
+			return "";
+		}
+		return slugify(text);
+	});
+
+	// Date format helper: {{dateFormat date "YYYY-MM-DD"}}
+	hbs.registerHelper("dateFormat", (date: unknown, format: unknown) => {
+		if (typeof date !== "string" || typeof format !== "string") {
+			return "";
+		}
+		return formatDate(date, format);
+	});
+
+	// Default helper: {{default value fallback}}
+	hbs.registerHelper("default", (value: unknown, fallback: unknown) => {
+		if (value !== undefined && value !== null && value !== "") {
+			return value;
+		}
+		return fallback;
+	});
+}
+
+/**
+ * Create a configured Handlebars instance with helpers registered
+ */
+export function createHandlebars(): typeof Handlebars {
+	const hbs = Handlebars.create();
+	registerHelpers(hbs);
+	return hbs;
+}
+
+/**
+ * Compile and render a template with the given data
+ */
+export function renderTemplate(
+	hbs: typeof Handlebars,
+	template: string,
+	data: TemplateData,
+): string {
+	const compiled = hbs.compile(template);
+	return compiled(data);
+}
+
+/**
+ * Generate a filename from template and data
+ */
+export function generateFilename(
+	hbs: typeof Handlebars,
+	template: string,
+	data: TemplateData,
+): string {
+	const filename = renderTemplate(hbs, template, data);
+	// Sanitize filename - remove any path traversal attempts
+	return filename.replace(/\.\./g, "").replace(/[<>:"|?*]/g, "");
+}
+
+/**
+ * Generate file content from template and data
+ */
+export function generateContent(
+	hbs: typeof Handlebars,
+	template: string,
+	data: TemplateData,
+): string {
+	return renderTemplate(hbs, template, data);
+}

packages/core/src/types.ts

···
+/**
+ * Options for exporting a publication to markdown files
+ */
+export interface ExportOptions {
+	/** AT URI of the publication (e.g., at://did:plc:xyz/site.standard.publication/rkey) */
+	publicationUri: string;
+	/** Directory to write output files */
+	outputDir: string;
+	/** Handlebars template for file content (uses default if not provided) */
+	contentTemplate?: string;
+	/** Handlebars template for filename (uses default if not provided) */
+	filenameTemplate?: string;
+	/** Only include documents with ANY of these tags */
+	includeTags?: string[];
+	/** Exclude documents with ANY of these tags */
+	excludeTags?: string[];
+}
+
+/**
+ * Result of an export operation
+ */
+export interface ExportResult {
+	/** Paths of successfully written files */
+	filesWritten: string[];
+	/** Number of documents processed */
+	documentsProcessed: number;
+	/** Number of documents skipped (filtered out or errored) */
+	documentsSkipped: number;
+	/** Warnings encountered during export */
+	warnings: string[];
+}
+
+/**
+ * Publication record from site.standard.publication
+ */
+export interface Publication {
+	name: string;
+	url: string;
+	description?: string;
+}
+
+/**
+ * Document record from site.standard.document
+ */
+export interface Document {
+	title: string;
+	path?: string;
+	description?: string;
+	content?: string;
+	textContent?: string;
+	tags?: string[];
+	publishedAt?: string;
+	updatedAt?: string;
+	site: string;
+}
+
+/**
+ * Data passed to Handlebars templates
+ */
+export interface TemplateData {
+	title: string;
+	path?: string;
+	description?: string;
+	content: string;
+	tags: string[];
+	publishedAt?: string;
+	updatedAt?: string;
+	publication: Publication;
+}