@sourcepress/media 0.1.0

package/src/interface.ts

@@ -0,0 +1,42 @@
+import type { MediaRef, MediaUploadInput } from "@sourcepress/core";
+
+/**
+ * Pluggable media storage interface.
+ * Implementations: GitMediaStorage (default), R2MediaStorage, S3MediaStorage (future).
+ */
+export interface MediaStorage {
+	/**
+	 * Upload a file and register it in the media registry.
+	 * Returns the MediaRef with hash and metadata.
+	 */
+	upload(input: MediaUploadInput): Promise<MediaRef>;
+
+	/**
+	 * Get file contents by path.
+	 * Returns null if the file does not exist.
+	 */
+	get(path: string): Promise<Buffer | null>;
+
+	/**
+	 * Delete a file and remove it from the registry.
+	 */
+	delete(path: string): Promise<void>;
+
+	/**
+	 * List all media entries, optionally filtered by path prefix.
+	 */
+	list(prefix?: string): Promise<MediaRef[]>;
+
+	/**
+	 * Get metadata for a single file from the registry.
+	 */
+	getMeta(path: string): Promise<MediaRef | null>;
+
+	/**
+	 * Update metadata for an existing file (e.g., alt-text).
+	 */
+	updateMeta(
+		path: string,
+		updates: Partial<Pick<MediaRef, "alt" | "source" | "generated_by" | "prompt">>,
+	): Promise<MediaRef>;
+}

package/src/registry.ts

@@ -0,0 +1,105 @@
+import type { MediaRef, MediaRegistry } from "@sourcepress/core";
+import type { GitHubClient } from "@sourcepress/github";
+
+/**
+ * MediaRegistryManager reads/writes the media.json file in Git.
+ * This is the source of truth for all media metadata.
+ */
+export class MediaRegistryManager {
+	private github: GitHubClient;
+	private registryPath: string;
+	private cache: MediaRegistry | null = null;
+	private registrySha: string | null = null;
+
+	constructor(github: GitHubClient, registryPath: string) {
+		this.github = github;
+		this.registryPath = registryPath;
+	}
+
+	/**
+	 * Load the full registry from Git.
+	 */
+	async load(): Promise<MediaRegistry> {
+		if (this.cache) return this.cache;
+
+		const file = await this.github.getFile(this.registryPath);
+		if (!file) {
+			this.cache = {};
+			this.registrySha = null;
+			return this.cache;
+		}
+
+		this.registrySha = file.sha;
+		try {
+			this.cache = JSON.parse(file.content) as MediaRegistry;
+		} catch {
+			console.error("Failed to parse media registry JSON, falling back to empty registry");
+			this.cache = {};
+		}
+		return this.cache;
+	}
+
+	/**
+	 * Save the registry back to Git.
+	 */
+	async save(message: string): Promise<void> {
+		const content = JSON.stringify(this.cache ?? {}, null, 2);
+		const result = await this.github.createOrUpdateFile(
+			this.registryPath,
+			content,
+			message,
+			undefined,
+			this.registrySha ?? undefined,
+		);
+		this.registrySha = result.sha;
+	}
+
+	/**
+	 * Add or update an entry in the registry.
+	 */
+	async set(path: string, ref: MediaRef): Promise<void> {
+		await this.load();
+		if (!this.cache) this.cache = {};
+		this.cache[path] = ref;
+	}
+
+	/**
+	 * Get a single entry.
+	 */
+	async get(path: string): Promise<MediaRef | null> {
+		const registry = await this.load();
+		return registry[path] ?? null;
+	}
+
+	/**
+	 * Remove an entry from the registry.
+	 */
+	async remove(path: string): Promise<void> {
+		await this.load();
+		if (this.cache) {
+			delete this.cache[path];
+		}
+	}
+
+	/**
+	 * List entries, optionally filtered by prefix.
+	 */
+	async list(prefix?: string): Promise<MediaRef[]> {
+		const registry = await this.load();
+		const entries = Object.entries(registry);
+
+		if (prefix) {
+			return entries.filter(([key]) => key.startsWith(prefix)).map(([, ref]) => ref);
+		}
+
+		return entries.map(([, ref]) => ref);
+	}
+
+	/**
+	 * Invalidate the in-memory cache.
+	 */
+	invalidate(): void {
+		this.cache = null;
+		this.registrySha = null;
+	}
+}

package/src/types.ts

@@ -0,0 +1 @@
+export type { MediaRef, MediaRegistry, MediaUploadInput, MediaConfig } from "@sourcepress/core";

package/src/validation.ts

@@ -0,0 +1,70 @@
+import { posix } from "node:path";
+import type { MediaConfig } from "@sourcepress/core";
+
+const DEFAULT_ALLOWED_TYPES = [
+	"image/jpeg",
+	"image/png",
+	"image/webp",
+	"image/gif",
+	"image/svg+xml",
+	"application/pdf",
+];
+
+const DEFAULT_MAX_SIZE_MB = 10;
+
+export interface ValidationResult {
+	valid: boolean;
+	error?: string;
+}
+
+export function validateUpload(
+	contentType: string,
+	sizeBytes: number,
+	config?: Partial<MediaConfig>,
+): ValidationResult {
+	const allowedTypes = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
+	const maxSizeMb = config?.maxSizeMb ?? DEFAULT_MAX_SIZE_MB;
+
+	if (!allowedTypes.includes(contentType)) {
+		return {
+			valid: false,
+			error: `Content type "${contentType}" is not allowed. Allowed: ${allowedTypes.join(", ")}`,
+		};
+	}
+
+	const maxBytes = maxSizeMb * 1024 * 1024;
+	if (sizeBytes > maxBytes) {
+		return {
+			valid: false,
+			error: `File size ${(sizeBytes / 1024 / 1024).toFixed(1)}MB exceeds maximum ${maxSizeMb}MB`,
+		};
+	}
+
+	return { valid: true };
+}
+
+/**
+ * Sanitize a media path — no traversal, lowercase, forward slashes.
+ * Iterates until stable, then verifies no traversal sequences remain.
+ */
+export function sanitizePath(path: string): string {
+	let current = path.replace(/\\/g, "/").replace(/^\//, "").toLowerCase();
+
+	// Iteratively remove traversal sequences until stable
+	let prev: string;
+	do {
+		prev = current;
+		current = current
+			.replace(/\.{2,}/g, "")
+			.replace(/\/+/g, "/")
+			.replace(/^\//, "");
+	} while (current !== prev);
+
+	// Final check via posix.normalize
+	const normalized = posix.normalize(current);
+	if (normalized.includes("..") || normalized.startsWith("/")) {
+		throw new Error(`Path traversal detected in: ${path}`);
+	}
+
+	return normalized;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		environment: "node",
+	},
+});