nebula-cms 0.1.0 → 0.1.4

package/dist/client/js/storage/client.d.ts

@@ -0,0 +1,72 @@
+import type { StorageRequest, FileEntry, FileWrite } from './adapter';
+export declare class StorageClient {
+    private port;
+    private pending;
+    private idCounter;
+    /**
+     * Creates a client wrapping the given port.
+     * @param {MessagePort} port - The port connected to the storage SharedWorker
+     */
+    constructor(port: MessagePort);
+    /**
+     * Routes responses to their pending promises. Responses without an _id are broadcast (like port-connected) and are ignored here.
+     * @param {StorageResponse & { _id?: string }} data - The response data
+     * @return {void}
+     */
+    private handleResponse;
+    /**
+     * Sends a request and waits for the matching response.
+     * @param {StorageRequest} msg - The request to send
+     * @return {Promise<StorageResponse>} The matched response
+     */
+    private send;
+    /**
+     * Initializes the backend adapter in the SharedWorker.
+     * @param {StorageRequest & { type: 'init' }} config - The init config
+     * @return {Promise<void>}
+     */
+    init(config: StorageRequest & {
+        type: 'init';
+    }): Promise<void>;
+    /**
+     * Lists files in a collection matching the given extensions.
+     * @param {string} collection - The collection name
+     * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+     * @return {Promise<FileEntry[]>} Array of file entries
+     */
+    listFiles(collection: string, extensions: string[]): Promise<FileEntry[]>;
+    /**
+     * Reads a single file's content.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @return {Promise<string>} The file content
+     */
+    readFile(collection: string, filename: string): Promise<string>;
+    /**
+     * Writes a single file.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @param {string} content - The content to write
+     * @return {Promise<void>}
+     */
+    writeFile(collection: string, filename: string, content: string): Promise<void>;
+    /**
+     * Writes multiple files atomically.
+     * @param {FileWrite[]} files - Array of files to write
+     * @return {Promise<void>}
+     */
+    writeFiles(files: FileWrite[]): Promise<void>;
+    /**
+     * Deletes a file from a collection. Used during file type conversion to remove the old file after the new one is written.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename to delete
+     * @return {Promise<void>}
+     */
+    deleteFile(collection: string, filename: string): Promise<void>;
+    /**
+     * Tears down the active backend adapter.
+     * @return {Promise<void>}
+     */
+    teardown(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client/js/storage/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/client/js/storage/client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,cAAc,EAEd,SAAS,EACT,SAAS,EACV,MAAM,WAAW,CAAC;AAEnB,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,OAAO,CAGX;IACJ,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;gBACS,IAAI,EAAE,WAAW;IAQ7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAQZ;;;;OAIG;IACG,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;OAKG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,SAAS,EAAE,CAAC;IAWvB;;;;;OAKG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWrE;;;;;;OAMG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;;;;OAKG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/client/js/storage/client.js

@@ -0,0 +1,121 @@
+/*
+ * Typed client for communicating with the storage SharedWorker over a MessagePort.
+ * Wraps postMessage/onmessage into async request/response calls.
+ */
+export class StorageClient {
+    port;
+    pending = new Map();
+    idCounter = 0;
+    /**
+     * Creates a client wrapping the given port.
+     * @param {MessagePort} port - The port connected to the storage SharedWorker
+     */
+    constructor(port) {
+        this.port = port;
+        this.port.addEventListener('message', (event) => {
+            this.handleResponse(event.data);
+        });
+        this.port.start();
+    }
+    /**
+     * Routes responses to their pending promises. Responses without an _id are broadcast (like port-connected) and are ignored here.
+     * @param {StorageResponse & { _id?: string }} data - The response data
+     * @return {void}
+     */
+    handleResponse(data) {
+        if (!data._id)
+            return;
+        const entry = this.pending.get(data._id);
+        if (!entry)
+            return;
+        this.pending.delete(data._id);
+        if ('ok' in data && data.ok === false && 'error' in data) {
+            entry.reject(new Error(data.error));
+        }
+        else {
+            entry.resolve(data);
+        }
+    }
+    /**
+     * Sends a request and waits for the matching response.
+     * @param {StorageRequest} msg - The request to send
+     * @return {Promise<StorageResponse>} The matched response
+     */
+    send(msg) {
+        const _id = String(++this.idCounter);
+        return new Promise((resolve, reject) => {
+            this.pending.set(_id, { resolve, reject });
+            this.port.postMessage({ ...msg, _id });
+        });
+    }
+    /**
+     * Initializes the backend adapter in the SharedWorker.
+     * @param {StorageRequest & { type: 'init' }} config - The init config
+     * @return {Promise<void>}
+     */
+    async init(config) {
+        await this.send(config);
+    }
+    /**
+     * Lists files in a collection matching the given extensions.
+     * @param {string} collection - The collection name
+     * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+     * @return {Promise<FileEntry[]>} Array of file entries
+     */
+    async listFiles(collection, extensions) {
+        const res = await this.send({
+            type: 'listFiles',
+            collection,
+            extensions,
+        });
+        return res.files;
+    }
+    /**
+     * Reads a single file's content.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @return {Promise<string>} The file content
+     */
+    async readFile(collection, filename) {
+        const res = await this.send({
+            type: 'readFile',
+            collection,
+            filename,
+        });
+        return res.content;
+    }
+    /**
+     * Writes a single file.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @param {string} content - The content to write
+     * @return {Promise<void>}
+     */
+    async writeFile(collection, filename, content) {
+        await this.send({ type: 'writeFile', collection, filename, content });
+    }
+    /**
+     * Writes multiple files atomically.
+     * @param {FileWrite[]} files - Array of files to write
+     * @return {Promise<void>}
+     */
+    async writeFiles(files) {
+        await this.send({ type: 'writeFiles', files });
+    }
+    /**
+     * Deletes a file from a collection. Used during file type conversion to remove the old file after the new one is written.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename to delete
+     * @return {Promise<void>}
+     */
+    async deleteFile(collection, filename) {
+        await this.send({ type: 'deleteFile', collection, filename });
+    }
+    /**
+     * Tears down the active backend adapter.
+     * @return {Promise<void>}
+     */
+    async teardown() {
+        await this.send({ type: 'teardown' });
+    }
+}

package/dist/client/js/storage/db.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Opens (or returns the cached) shared IndexedDB database, creating or upgrading stores as needed.
+ * The connection is opened once and reused, avoiding a new indexedDB.open() round-trip per call.
+ * Version 1: handles store only. Version 2: adds drafts store.
+ * @return {Promise<IDBDatabase>} Promise resolving to the database instance
+ */
+export declare function openDB(): Promise<IDBDatabase>;
+//# sourceMappingURL=db.d.ts.map

package/dist/client/js/storage/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../../src/client/js/storage/db.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,CAqB7C"}

package/dist/client/js/storage/db.js

@@ -0,0 +1,35 @@
+// Database name for admin CMS persistence
+const DB_NAME = 'cms-admin';
+// Current database version — bumped from 1 to add the drafts store
+const DB_VERSION = 2;
+// Cached database promise — opened once, reused by all callers
+let dbPromise = null;
+/**
+ * Opens (or returns the cached) shared IndexedDB database, creating or upgrading stores as needed.
+ * The connection is opened once and reused, avoiding a new indexedDB.open() round-trip per call.
+ * Version 1: handles store only. Version 2: adds drafts store.
+ * @return {Promise<IDBDatabase>} Promise resolving to the database instance
+ */
+export function openDB() {
+    if (dbPromise)
+        return dbPromise;
+    dbPromise = new Promise((resolve, reject) => {
+        const request = indexedDB.open(DB_NAME, DB_VERSION);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains('handles')) {
+                db.createObjectStore('handles');
+            }
+            if (!db.objectStoreNames.contains('drafts')) {
+                db.createObjectStore('drafts', { keyPath: 'id' });
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => {
+            // Reset cache so the next caller retries instead of getting a stale rejection
+            dbPromise = null;
+            reject(request.error);
+        };
+    });
+    return dbPromise;
+}

package/dist/client/js/storage/fsa.d.ts

@@ -0,0 +1,51 @@
+import type { StorageAdapter, FileEntry, FileWrite } from './adapter';
+export declare class FsaAdapter implements StorageAdapter {
+    private root;
+    /**
+     * Creates an FSA adapter rooted at the given directory handle.
+     * @param {FileSystemDirectoryHandle} root - The project root directory handle
+     */
+    constructor(root: FileSystemDirectoryHandle);
+    /**
+     * Traverses root → src → content → {collection}.
+     * @param {string} collection - The collection name
+     * @return {Promise<FileSystemDirectoryHandle>} The collection directory handle
+     */
+    private getCollectionDir;
+    /**
+     * Lists files in the collection matching the given extensions, with their content.
+     * @param {string} collection - The collection name
+     * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+     * @return {Promise<FileEntry[]>} Array of filename + content pairs
+     */
+    listFiles(collection: string, extensions: string[]): Promise<FileEntry[]>;
+    /**
+     * Deletes a file from the collection directory.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename to delete
+     * @return {Promise<void>}
+     */
+    deleteFile(collection: string, filename: string): Promise<void>;
+    /**
+     * Reads a single file's content from the collection.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @return {Promise<string>} The file content
+     */
+    readFile(collection: string, filename: string): Promise<string>;
+    /**
+     * Writes content to a file, creating it if necessary.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @param {string} content - The content to write
+     * @return {Promise<void>}
+     */
+    writeFile(collection: string, filename: string, content: string): Promise<void>;
+    /**
+     * Writes multiple files sequentially (FSA has no atomic multi-file write).
+     * @param {FileWrite[]} files - Array of files to write
+     * @return {Promise<void>}
+     */
+    writeFiles(files: FileWrite[]): Promise<void>;
+}
+//# sourceMappingURL=fsa.d.ts.map

package/dist/client/js/storage/fsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsa.d.ts","sourceRoot":"","sources":["../../../../src/client/js/storage/fsa.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtE,qBAAa,UAAW,YAAW,cAAc;IAKnC,OAAO,CAAC,IAAI;IAJxB;;;OAGG;gBACiB,IAAI,EAAE,yBAAyB;IAEnD;;;;OAIG;YACW,gBAAgB;IAQ9B;;;;;OAKG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBvB;;;;;OAKG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrE;;;;;OAKG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOrE;;;;;;OAMG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAKpD"}

package/dist/client/js/storage/fsa.js

@@ -0,0 +1,91 @@
+/*
+ * Storage adapter backed by the File System Access API.
+ * Traverses from a project root handle through src/content/{collection}/ for all operations.
+ */
+// FSA adapter implementation
+export class FsaAdapter {
+    root;
+    /**
+     * Creates an FSA adapter rooted at the given directory handle.
+     * @param {FileSystemDirectoryHandle} root - The project root directory handle
+     */
+    constructor(root) {
+        this.root = root;
+    }
+    /**
+     * Traverses root → src → content → {collection}.
+     * @param {string} collection - The collection name
+     * @return {Promise<FileSystemDirectoryHandle>} The collection directory handle
+     */
+    async getCollectionDir(collection) {
+        const src = await this.root.getDirectoryHandle('src');
+        const content = await src.getDirectoryHandle('content');
+        return content.getDirectoryHandle(collection);
+    }
+    /**
+     * Lists files in the collection matching the given extensions, with their content.
+     * @param {string} collection - The collection name
+     * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+     * @return {Promise<FileEntry[]>} Array of filename + content pairs
+     */
+    async listFiles(collection, extensions) {
+        const dir = await this.getCollectionDir(collection);
+        const entries = [];
+        for await (const [name, entry] of dir.entries()) {
+            if (entry.kind !== 'file' ||
+                !extensions.some((ext) => name.endsWith(ext))) {
+                continue;
+            }
+            const file = await entry.getFile();
+            const content = await file.text();
+            entries.push({ filename: name, content });
+        }
+        return entries;
+    }
+    /**
+     * Deletes a file from the collection directory.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename to delete
+     * @return {Promise<void>}
+     */
+    async deleteFile(collection, filename) {
+        const dir = await this.getCollectionDir(collection);
+        await dir.removeEntry(filename);
+    }
+    /**
+     * Reads a single file's content from the collection.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @return {Promise<string>} The file content
+     */
+    async readFile(collection, filename) {
+        const dir = await this.getCollectionDir(collection);
+        const fileHandle = await dir.getFileHandle(filename);
+        const file = await fileHandle.getFile();
+        return file.text();
+    }
+    /**
+     * Writes content to a file, creating it if necessary.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @param {string} content - The content to write
+     * @return {Promise<void>}
+     */
+    async writeFile(collection, filename, content) {
+        const dir = await this.getCollectionDir(collection);
+        const fileHandle = await dir.getFileHandle(filename, { create: true });
+        const writable = await fileHandle.createWritable();
+        await writable.write(content);
+        await writable.close();
+    }
+    /**
+     * Writes multiple files sequentially (FSA has no atomic multi-file write).
+     * @param {FileWrite[]} files - Array of files to write
+     * @return {Promise<void>}
+     */
+    async writeFiles(files) {
+        for (const f of files) {
+            await this.writeFile(f.collection, f.filename, f.content);
+        }
+    }
+}

package/dist/client/js/storage/github.d.ts

@@ -0,0 +1,62 @@
+import type { StorageAdapter, FileEntry, FileWrite } from './adapter';
+export declare class GitHubAdapter implements StorageAdapter {
+    private token;
+    private owner;
+    private repo;
+    private defaultBranch;
+    /**
+     * @param {string} token - GitHub Personal Access Token
+     * @param {string} repoSlug - Repository in "owner/repo" format
+     */
+    constructor(token: string, repoSlug: string);
+    /**
+     * Validates credentials by fetching repo metadata and caches the default branch.
+     * @return {Promise<void>}
+     */
+    validate(): Promise<void>;
+    /**
+     * Lists files in a collection matching the given extensions, with their raw content.
+     * @param {string} collection - The collection name
+     * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+     * @return {Promise<FileEntry[]>} Array of filename + content pairs
+     */
+    listFiles(collection: string, extensions: string[]): Promise<FileEntry[]>;
+    /**
+     * Deletes a file from the repository via the Contents API.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename to delete
+     * @return {Promise<void>}
+     */
+    deleteFile(collection: string, filename: string): Promise<void>;
+    /**
+     * Reads a single file's raw content via the raw+json Accept header.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @return {Promise<string>} The file content
+     */
+    readFile(collection: string, filename: string): Promise<string>;
+    /**
+     * Writes a single file via the Contents API. Fetches the current SHA for updates.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @param {string} content - The content to write
+     * @return {Promise<void>}
+     */
+    writeFile(collection: string, filename: string, content: string): Promise<void>;
+    /**
+     * Writes multiple files in a single atomic commit using the Git Trees + Commits API.
+     * @param {FileWrite[]} files - Array of files to write
+     * @return {Promise<void>}
+     */
+    writeFiles(files: FileWrite[]): Promise<void>;
+    /**
+     * Makes an authenticated request to the GitHub API.
+     * @param {string} method - HTTP method
+     * @param {string} path - API path (appended to https://api.github.com)
+     * @param {Record<string, string>} [extraHeaders] - Additional headers to merge
+     * @param {unknown} [body] - JSON body to send
+     * @return {Promise<Response>} The fetch response
+     */
+    private request;
+}
+//# sourceMappingURL=github.d.ts.map

package/dist/client/js/storage/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../src/client/js/storage/github.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAatE,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAS;IAErB,OAAO,CAAC,aAAa,CAAkB;IAEvC;;;OAGG;gBACS,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAO3C;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAc/B;;;;;OAKG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,SAAS,EAAE,CAAC;IA2BvB;;;;;OAKG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrE;;;;;OAKG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAarE;;;;;;OAMG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAgChB;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4EnD;;;;;;;OAOG;YACW,OAAO;CAyBtB"}

package/dist/client/js/storage/github.js

@@ -0,0 +1,216 @@
+/*
+ * Storage adapter backed by the GitHub REST API.
+ * Uses a Personal Access Token for authentication. All file operations
+ * target src/content/{collection}/ within the repository.
+ */
+/**
+ * Encodes a Uint8Array to a base64 string without using deprecated unescape().
+ * @param {Uint8Array} bytes - The bytes to encode
+ * @return {string} Base64-encoded string
+ */
+function uint8ToBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+export class GitHubAdapter {
+    token;
+    owner;
+    repo;
+    // Cached on validate(); defaults to 'main' before validation
+    defaultBranch = 'main';
+    /**
+     * @param {string} token - GitHub Personal Access Token
+     * @param {string} repoSlug - Repository in "owner/repo" format
+     */
+    constructor(token, repoSlug) {
+        this.token = token;
+        const [owner, repo] = repoSlug.split('/');
+        this.owner = owner;
+        this.repo = repo;
+    }
+    /**
+     * Validates credentials by fetching repo metadata and caches the default branch.
+     * @return {Promise<void>}
+     */
+    async validate() {
+        const res = await this.request('GET', `/repos/${this.owner}/${this.repo}`);
+        if (!res.ok) {
+            const status = res.status;
+            if (status === 401)
+                throw new Error('Invalid or expired token');
+            if (status === 403)
+                throw new Error('Token lacks repository access');
+            if (status === 404)
+                throw new Error(`Repository "${this.owner}/${this.repo}" not found`);
+            throw new Error(`GitHub API error: ${status}`);
+        }
+        const data = await res.json();
+        this.defaultBranch = data.default_branch;
+    }
+    /**
+     * Lists files in a collection matching the given extensions, with their raw content.
+     * @param {string} collection - The collection name
+     * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+     * @return {Promise<FileEntry[]>} Array of filename + content pairs
+     */
+    async listFiles(collection, extensions) {
+        const path = `src/content/${collection}`;
+        // Get directory listing
+        const listRes = await this.request('GET', `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`);
+        if (!listRes.ok) {
+            if (listRes.status === 404)
+                return [];
+            throw new Error(`Failed to list files: ${listRes.status}`);
+        }
+        const listing = await listRes.json();
+        // Filter to requested extensions and fetch all files in parallel
+        const filtered = listing.filter((f) => extensions.some((ext) => f.name.endsWith(ext)));
+        return Promise.all(filtered.map(async (file) => ({
+            filename: file.name,
+            content: await this.readFile(collection, file.name),
+        })));
+    }
+    /**
+     * Deletes a file from the repository via the Contents API.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename to delete
+     * @return {Promise<void>}
+     */
+    async deleteFile(collection, filename) {
+        const path = `src/content/${collection}/${filename}`;
+        // Get the current SHA (required by the GitHub Contents API for deletion)
+        const existing = await this.request('GET', `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`);
+        if (!existing.ok)
+            throw new Error(`File not found for deletion: ${path}`);
+        const data = await existing.json();
+        const res = await this.request('DELETE', `/repos/${this.owner}/${this.repo}/contents/${path}`, undefined, {
+            message: `Delete ${path}`,
+            sha: data.sha,
+            branch: this.defaultBranch,
+        });
+        if (!res.ok)
+            throw new Error(`Failed to delete ${path}: ${res.status}`);
+    }
+    /**
+     * Reads a single file's raw content via the raw+json Accept header.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @return {Promise<string>} The file content
+     */
+    async readFile(collection, filename) {
+        const path = `src/content/${collection}/${filename}`;
+        const res = await this.request('GET', `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`, { Accept: 'application/vnd.github.raw+json' });
+        if (!res.ok) {
+            throw new Error(`Failed to read ${path}: ${res.status}`);
+        }
+        return res.text();
+    }
+    /**
+     * Writes a single file via the Contents API. Fetches the current SHA for updates.
+     * @param {string} collection - The collection name
+     * @param {string} filename - The filename
+     * @param {string} content - The content to write
+     * @return {Promise<void>}
+     */
+    async writeFile(collection, filename, content) {
+        const path = `src/content/${collection}/${filename}`;
+        // Get current SHA if file exists (required by GitHub API for updates)
+        let sha;
+        const existing = await this.request('GET', `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`);
+        if (existing.ok) {
+            const data = await existing.json();
+            sha = data.sha;
+        }
+        const body = {
+            message: `Update ${path}`,
+            content: uint8ToBase64(new TextEncoder().encode(content)),
+            branch: this.defaultBranch,
+        };
+        if (sha)
+            body.sha = sha;
+        const res = await this.request('PUT', `/repos/${this.owner}/${this.repo}/contents/${path}`, undefined, body);
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(`Failed to write ${path}: ${res.status} ${errText}`);
+        }
+    }
+    /**
+     * Writes multiple files in a single atomic commit using the Git Trees + Commits API.
+     * @param {FileWrite[]} files - Array of files to write
+     * @return {Promise<void>}
+     */
+    async writeFiles(files) {
+        if (files.length === 0)
+            return;
+        if (files.length === 1) {
+            await this.writeFile(files[0].collection, files[0].filename, files[0].content);
+            return;
+        }
+        // 1. Get current commit SHA for the default branch
+        const refRes = await this.request('GET', `/repos/${this.owner}/${this.repo}/git/ref/heads/${this.defaultBranch}`);
+        if (!refRes.ok)
+            throw new Error(`Failed to get branch ref: ${refRes.status}`);
+        const refData = await refRes.json();
+        const baseCommitSHA = refData.object.sha;
+        // Get the base tree SHA from the current commit
+        const commitRes = await this.request('GET', `/repos/${this.owner}/${this.repo}/git/commits/${baseCommitSHA}`);
+        if (!commitRes.ok)
+            throw new Error(`Failed to get commit: ${commitRes.status}`);
+        const commitData = await commitRes.json();
+        const baseTreeSHA = commitData.tree.sha;
+        // 2. Create a new tree containing all file changes
+        const tree = files.map((f) => ({
+            path: `src/content/${f.collection}/${f.filename}`,
+            mode: '100644',
+            type: 'blob',
+            content: f.content,
+        }));
+        const treeRes = await this.request('POST', `/repos/${this.owner}/${this.repo}/git/trees`, undefined, { base_tree: baseTreeSHA, tree });
+        if (!treeRes.ok)
+            throw new Error(`Failed to create tree: ${treeRes.status}`);
+        const treeData = await treeRes.json();
+        // 3. Create a new commit pointing at the new tree
+        const paths = files.map((f) => `${f.collection}/${f.filename}`).join(', ');
+        const newCommitRes = await this.request('POST', `/repos/${this.owner}/${this.repo}/git/commits`, undefined, {
+            message: `Update ${paths}`,
+            tree: treeData.sha,
+            parents: [baseCommitSHA],
+        });
+        if (!newCommitRes.ok)
+            throw new Error(`Failed to create commit: ${newCommitRes.status}`);
+        const newCommitData = await newCommitRes.json();
+        // 4. Advance the branch ref to the new commit
+        const updateRefRes = await this.request('PATCH', `/repos/${this.owner}/${this.repo}/git/refs/heads/${this.defaultBranch}`, undefined, { sha: newCommitData.sha });
+        if (!updateRefRes.ok)
+            throw new Error(`Failed to update ref: ${updateRefRes.status}`);
+    }
+    /**
+     * Makes an authenticated request to the GitHub API.
+     * @param {string} method - HTTP method
+     * @param {string} path - API path (appended to https://api.github.com)
+     * @param {Record<string, string>} [extraHeaders] - Additional headers to merge
+     * @param {unknown} [body] - JSON body to send
+     * @return {Promise<Response>} The fetch response
+     */
+    async request(method, path, extraHeaders, body) {
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'X-GitHub-Api-Version': '2026-03-10',
+            // Default to JSON so the browser cache distinguishes from raw content requests
+            Accept: 'application/vnd.github+json',
+            ...extraHeaders,
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        return fetch(`https://api.github.com${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            // API responses must never be served from browser cache
+            cache: 'no-store',
+        });
+    }
+}