@orhancodestudio/ocsm-core 0.1.0-alpha.1 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog — @orhancodestudio/ocsm-core
 
+## 0.1.0-alpha.3
+
+### Added
+
+- `ocsm.public` — a filesystem-only reader (`listDocuments`, `getDocument`,
+  `getLayout`, `getTheme`) for the public site. Decouples the production build
+  from GitHub: public pages read the committed checkout instead of the API
+  (faster, no rate limits, build never depends on GitHub availability). The live
+  GitHub backend still powers the editor's reads, writes, and media serving.
+
+## 0.1.0-alpha.2
+
+### Added
+
+- Visual full-screen **page builder** with section blocks (navbar, hero, heading,
+  rich text, image, button, quote, banner, marquee, video, spacer), per-block
+  styling (colors, gradients, fonts, spacing), drag-and-drop reorder, visibility
+  toggle, device preview, and live themed canvas.
+- Global **header/footer** regions (`LayoutStore`) shared across pages.
+- **Dynamic roles & permissions** (`RoleStore`) with a reusable `Modal`, a redesigned
+  Users page, and a tabbed **Settings** page (Roles & Permissions).
+- **Media upload** from device: `MediaStore` + `handleMediaRequest` route helper,
+  served live via `/ocsm-media/*` (works before rebuild).
+- Reusable `DataTable`; versioned sessions (auto-invalidate stale cookies).
+
+### Changed
+
+- Markdown rendering moved from `next-mdx-remote` to `react-markdown`.
+- Content layer unified on a single `FileBackend` abstraction (fs + GitHub),
+  now with binary read/write for media.
+
 ## 0.1.0-alpha.1
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orhancodestudio/ocsm-core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "OCS Management — the git-based CMS core for Next.js. Built by Orhan Code Studio.",
   "license": "MIT",
   "author": "Orhan Code Studio (https://orhancodestudio.com)",

package/src/admin/admin.module.css

@@ -1310,3 +1310,24 @@ a.card:hover {
   color: var(--p-muted);
   margin-top: 2px;
 }
+
+/* ---------- Media input ---------- */
+.mediaRow {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.mediaRow .fsInput {
+  flex: 1;
+}
+
+.mediaPreview {
+  margin-top: 8px;
+  max-width: 100%;
+  max-height: 120px;
+  border-radius: 8px;
+  border: 1px solid #e2e8f0;
+  display: block;
+  object-fit: contain;
+}

package/src/admin/admin.types.ts

@@ -60,6 +60,15 @@ export type UpdateRoleAction = (
 ) => Promise<ActionResult>;
 export type DeleteRoleAction = (id: string) => Promise<ActionResult>;
 
+// --- Media ---
+export interface UploadMediaResult {
+  ok: boolean;
+  url?: string;
+  message?: string;
+}
+/** Uploads a file (FormData field `file`) and returns its public URL. */
+export type UploadMediaAction = (form: FormData) => Promise<UploadMediaResult>;
+
 export type SaveThemeAction = (theme: OcsmTheme) => Promise<ActionResult>;
 
 export type SaveLayoutAction = (
@@ -79,6 +88,7 @@ export interface OcsmAdminActions {
   createRole: CreateRoleAction;
   updateRole: UpdateRoleAction;
   deleteRole: DeleteRoleAction;
+  uploadMedia: UploadMediaAction;
   saveTheme: SaveThemeAction;
   saveLayout: SaveLayoutAction;
   signOut: SignOutAction;

package/src/admin/components/media-input.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useRef, useState } from "react";
+import {
+  ACCEPTED_UPLOAD_HINT,
+  UPLOAD_ACCEPT_ATTR,
+} from "../../media/mime";
+import type { UploadMediaAction } from "../admin.types";
+import styles from "../admin.module.css";
+
+export interface MediaInputProps {
+  value: string;
+  onChange: (url: string) => void;
+  uploadMedia: UploadMediaAction;
+  placeholder?: string;
+}
+
+/**
+ * Image field with both a URL text input and a "device upload" button. Uploads
+ * go through the host's {@link UploadMediaAction} (stored via the CMS backend)
+ * and the returned URL is written back into the field.
+ */
+export function MediaInput({
+  value,
+  onChange,
+  uploadMedia,
+  placeholder,
+}: MediaInputProps) {
+  const fileRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function onFile(file: File) {
+    setError(null);
+    setBusy(true);
+    try {
+      const form = new FormData();
+      form.append("file", file);
+      const result = await uploadMedia(form);
+      if (result.ok && result.url) {
+        onChange(result.url);
+      } else {
+        setError(result.message ?? "Yükleme başarısız");
+      }
+    } catch {
+      setError("Yükleme sırasında hata oluştu");
+    } finally {
+      setBusy(false);
+      if (fileRef.current) fileRef.current.value = "";
+    }
+  }
+
+  return (
+    <div>
+      <div className={styles.mediaRow}>
+        <input
+          className={styles.fsInput}
+          value={value}
+          placeholder={placeholder ?? "https://… veya cihazdan yükle"}
+          onChange={(event) => onChange(event.target.value)}
+        />
+        <button
+          type="button"
+          className={`${styles.btn} ${styles.btnSm}`}
+          disabled={busy}
+          onClick={() => fileRef.current?.click()}
+        >
+          {busy ? "Yükleniyor…" : "Yükle"}
+        </button>
+        <input
+          ref={fileRef}
+          type="file"
+          accept={UPLOAD_ACCEPT_ATTR}
+          hidden
+          onChange={(event) => {
+            const file = event.target.files?.[0];
+            if (file) void onFile(file);
+          }}
+        />
+      </div>
+      {value ? (
+        // biome-ignore lint/a11y/useAltText: decorative thumbnail preview
+        <img src={value} alt="" className={styles.mediaPreview} />
+      ) : null}
+      {error ? (
+        <p className={styles.errorText}>{error}</p>
+      ) : (
+        <p className={styles.help}>{ACCEPTED_UPLOAD_HINT}</p>
+      )}
+    </div>
+  );
+}

package/src/admin/components/page-builder.tsx

@@ -18,7 +18,11 @@ import {
 import { BlockItem } from "../../blocks/block-renderer";
 import { themeToCssVariables } from "../../theme/css";
 import type { OcsmTheme } from "../../theme/theme.types";
-import type { SaveDocumentAction, SaveLayoutAction } from "../admin.types";
+import type {
+  SaveDocumentAction,
+  SaveLayoutAction,
+  UploadMediaAction,
+} from "../admin.types";
 import styles from "../admin.module.css";
 import {
   IconEye,
@@ -29,6 +33,7 @@ import {
   IconPhone,
   IconTrash,
 } from "./icons";
+import { MediaInput } from "./media-input";
 
 export interface PageBuilderProps {
   collection: string;
@@ -36,6 +41,7 @@ export interface PageBuilderProps {
   backHref: string;
   saveAction: SaveDocumentAction;
   saveLayout: SaveLayoutAction;
+  uploadMedia: UploadMediaAction;
   theme: OcsmTheme;
   initialSlug?: string;
   initialTitle?: string;
@@ -62,6 +68,7 @@ export function PageBuilder({
   backHref,
   saveAction,
   saveLayout,
+  uploadMedia,
   theme,
   initialSlug,
   initialTitle,
@@ -365,6 +372,7 @@ export function PageBuilder({
                     block={selectedBlock}
                     onContent={patchContent}
                     onStyle={patchStyle}
+                    uploadMedia={uploadMedia}
                   />
                 </div>
               </div>
@@ -589,17 +597,23 @@ function Inspector({
   block,
   onContent,
   onStyle,
+  uploadMedia,
 }: {
   block: Block;
   onContent: (patch: Record<string, unknown>) => void;
   onStyle: (patch: Partial<BlockStyle>) => void;
+  uploadMedia: UploadMediaAction;
 }) {
   const noAlign = block.type === "marquee" || block.type === "navbar";
   return (
     <>
       <div className={styles.fsGroup}>
         <h3 className={styles.fsGroupTitle}>İçerik</h3>
-        <ContentFields block={block} onChange={onContent} />
+        <ContentFields
+          block={block}
+          onChange={onContent}
+          uploadMedia={uploadMedia}
+        />
       </div>
       {block.type === "spacer" ? (
         <div className={styles.fsGroup}>
@@ -624,9 +638,11 @@ function Inspector({
 function ContentFields({
   block,
   onChange,
+  uploadMedia,
 }: {
   block: Block;
   onChange: (patch: Record<string, unknown>) => void;
+  uploadMedia: UploadMediaAction;
 }) {
   switch (block.type) {
     case "navbar":
@@ -639,12 +655,12 @@ function ContentFields({
               onChange={(e) => onChange({ logoText: e.target.value })}
             />
           </Control>
-          <Control label="Logo görseli (opsiyonel URL)">
-            <input
-              className={styles.fsInput}
+          <Control label="Logo görseli (opsiyonel)">
+            <MediaInput
               value={block.logoImageUrl}
-              placeholder="https://… (boşsa metin gösterilir)"
-              onChange={(e) => onChange({ logoImageUrl: e.target.value })}
+              onChange={(url) => onChange({ logoImageUrl: url })}
+              uploadMedia={uploadMedia}
+              placeholder="Boşsa logo metni gösterilir"
             />
           </Control>
           <Control label="Logo bağlantısı">
@@ -777,12 +793,11 @@ function ContentFields({
     case "image":
       return (
         <>
-          <Control label="Görsel URL">
-            <input
-              className={styles.fsInput}
+          <Control label="Görsel">
+            <MediaInput
               value={block.url}
-              placeholder="https://…"
-              onChange={(e) => onChange({ url: e.target.value })}
+              onChange={(url) => onChange({ url })}
+              uploadMedia={uploadMedia}
             />
           </Control>
           <Control label="Alternatif metin (erişilebilirlik)">

package/src/admin/index.ts

@@ -17,4 +17,6 @@ export type {
   UpdateRoleAction,
   UpdateUserAction,
   UpdateUserActionInput,
+  UploadMediaAction,
+  UploadMediaResult,
 } from "./admin.types";

package/src/admin/ocsm-admin.tsx

@@ -147,6 +147,7 @@ export async function OcsmAdmin({
           backHref={`/ocsm-admin/${collection.name}`}
           saveAction={actions.saveDocument}
           saveLayout={actions.saveLayout}
+          uploadMedia={actions.uploadMedia}
           theme={theme}
           initialBlocks={[]}
           initialHeader={headerBlocks}
@@ -169,6 +170,7 @@ export async function OcsmAdmin({
           backHref={`/ocsm-admin/${collection.name}`}
           saveAction={actions.saveDocument}
           saveLayout={actions.saveLayout}
+          uploadMedia={actions.uploadMedia}
           theme={theme}
           initialSlug={seg1}
           initialTitle={asString(document?.frontmatter.title)}

package/src/media/index.ts

@@ -0,0 +1,15 @@
+export {
+  MEDIA_DIR,
+  MEDIA_URL_PREFIX,
+  type MediaContent,
+  MediaStore,
+  type StoredMedia,
+} from "./media-store";
+export {
+  ACCEPTED_UPLOAD_HINT,
+  extForMime,
+  isAllowedUploadMime,
+  MAX_UPLOAD_BYTES,
+  mimeForExt,
+  UPLOAD_ACCEPT_ATTR,
+} from "./mime";

package/src/media/media-store.ts

@@ -0,0 +1,95 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import type { FileBackend } from "../storage/file-backend";
+import {
+  extForMime,
+  isAllowedUploadMime,
+  MAX_UPLOAD_BYTES,
+  mimeForExt,
+} from "./mime";
+
+/** Directory (within the repo) where uploaded media is stored. */
+export const MEDIA_DIR = "ocsm/media";
+
+/** Public URL prefix the serving route is mounted at. */
+export const MEDIA_URL_PREFIX = "/ocsm-media";
+
+export interface StoredMedia {
+  /** File name within the media directory (also the URL segment). */
+  name: string;
+  /** Public URL to reference the file (served by the media route). */
+  url: string;
+}
+
+export interface MediaContent {
+  data: Buffer;
+  contentType: string;
+}
+
+/**
+ * Stores and retrieves uploaded media through a {@link FileBackend}. Files live
+ * under {@link MEDIA_DIR} and are served via {@link MEDIA_URL_PREFIX} (a route
+ * handler reading from the backend), so uploads are available immediately —
+ * even in production, before any rebuild.
+ */
+export class MediaStore {
+  constructor(private readonly backend: FileBackend) {}
+
+  /** Validates and stores an uploaded file, returning its public URL. */
+  async save(input: {
+    data: Buffer;
+    mime: string;
+    originalName?: string;
+  }): Promise<StoredMedia> {
+    if (!isAllowedUploadMime(input.mime)) {
+      throw new Error("OCSM: desteklenmeyen dosya türü");
+    }
+    if (input.data.byteLength > MAX_UPLOAD_BYTES) {
+      throw new Error("OCSM: dosya çok büyük (en fazla 5 MB)");
+    }
+    const ext = extForMime(input.mime);
+    if (!ext) throw new Error("OCSM: desteklenmeyen dosya türü");
+
+    const name = `${baseName(input.originalName)}-${randomBytes(4).toString("hex")}.${ext}`;
+    await this.backend.writeBinary(
+      `${MEDIA_DIR}/${name}`,
+      input.data,
+      `ocsm: upload media ${name}`,
+    );
+    return { name, url: `${MEDIA_URL_PREFIX}/${name}` };
+  }
+
+  /** Reads a stored file by name, inferring its content type. */
+  async read(name: string): Promise<MediaContent | null> {
+    if (!isSafeName(name)) return null;
+    const data = await this.backend.readBinary(`${MEDIA_DIR}/${name}`);
+    if (!data) return null;
+    return { data, contentType: mimeForExt(extension(name)) };
+  }
+
+  /** Lists stored media file names. */
+  async list(): Promise<string[]> {
+    return this.backend.listFiles(MEDIA_DIR);
+  }
+}
+
+/** Slugified base of the original name (without extension), capped in length. */
+function baseName(original?: string): string {
+  const stem = (original ?? "dosya").replace(/\.[^.]+$/, "");
+  const slug = stem
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return slug || "dosya";
+}
+
+/** Rejects names with path separators or traversal. */
+function isSafeName(name: string): boolean {
+  return /^[a-zA-Z0-9._-]+$/.test(name) && !name.includes("..");
+}
+
+function extension(name: string): string {
+  const match = name.match(/\.([^.]+)$/);
+  return match?.[1] ?? "";
+}

package/src/media/mime.ts

@@ -0,0 +1,41 @@
+/** Allowed image upload types, mapped to their canonical file extension. */
+const MIME_TO_EXT: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+  "image/avif": "avif",
+};
+
+const EXT_TO_MIME: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+};
+
+/** Largest accepted upload, in bytes (5 MB). */
+export const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+
+/** Human-readable list of accepted formats, for UI hints. */
+export const ACCEPTED_UPLOAD_HINT = "PNG, JPG, GIF, WEBP, AVIF · en fazla 5 MB";
+
+/** The `accept` attribute value for a file input. */
+export const UPLOAD_ACCEPT_ATTR = Object.keys(MIME_TO_EXT).join(",");
+
+/** Returns the canonical extension for an upload MIME type, or `null` if not allowed. */
+export function extForMime(mime: string): string | null {
+  return MIME_TO_EXT[mime.toLowerCase()] ?? null;
+}
+
+/** Returns the MIME type for a file extension, or a generic fallback. */
+export function mimeForExt(ext: string): string {
+  return EXT_TO_MIME[ext.toLowerCase()] ?? "application/octet-stream";
+}
+
+/** Whether a MIME type is an accepted upload format. */
+export function isAllowedUploadMime(mime: string): boolean {
+  return mime.toLowerCase() in MIME_TO_EXT;
+}

package/src/server/create-ocsm.ts

@@ -1,3 +1,4 @@
+import type { Block } from "../blocks/block.types";
 import type { OcsmConfig, ResolvedOcsmConfig } from "../config/config.types";
 import { resolveOcsmConfig } from "../config/resolve-config";
 import type { ContentStore } from "../content/content-store.interface";
@@ -6,38 +7,63 @@ import type {
   ContentDocumentMeta,
 } from "../content/content.types";
 import { createContentStore } from "../content/create-content-store";
-import { LayoutStore } from "../layout/layout-store";
+import { type LayoutRegion, LayoutStore } from "../layout/layout-store";
+import { MediaStore } from "../media/media-store";
 import { RoleStore } from "../roles/role-store";
 import { createFileBackend } from "../storage/create-file-backend";
+import { FsFileBackend } from "../storage/fs-file-backend";
 import { JsonStore } from "../storage/json-store";
 import { ThemeStore } from "../theme/theme-store";
+import type { OcsmTheme } from "../theme/theme.types";
 import { UserStore } from "../users/user-store";
 
+/**
+ * Read-only content access that always reads from the **local filesystem** (the
+ * repository checkout), regardless of the GitHub env. Use this for the public
+ * site so the production build/render never depends on the GitHub API — content
+ * is baked from the committed files and refreshed on each rebuild.
+ */
+export interface PublicReader {
+  listDocuments(collection: string): Promise<ContentDocumentMeta[]>;
+  getDocument(collection: string, slug: string): Promise<ContentDocument | null>;
+  getLayout(region: LayoutRegion): Promise<Block[]>;
+  getTheme(): Promise<OcsmTheme>;
+}
+
 /** A configured OCS Management instance, bound to a config and storage backend. */
 export interface Ocsm {
   /** The fully-resolved configuration. */
   readonly config: ResolvedOcsmConfig;
-  /** Content access (collections of MDX documents). */
+  /** Live content access (GitHub in production) — for the editor and writes. */
   readonly store: ContentStore;
   /** User management. */
   readonly users: UserStore;
   /** Role & permission management. */
   readonly roles: RoleStore;
-  /** Public-site theme. */
+  /** Public-site theme (live backend). */
   readonly theme: ThemeStore;
-  /** Global header/footer sections shared across every page. */
+  /** Global header/footer sections shared across every page (live backend). */
   readonly layout: LayoutStore;
-  /** Lists documents in a collection. */
+  /** Uploaded media (images) storage (live backend). */
+  readonly media: MediaStore;
+  /**
+   * Filesystem-only reader for the public site. Decouples the build from GitHub:
+   * public pages read the checked-out files, not the API.
+   */
+  readonly public: PublicReader;
+  /** Lists documents in a collection (live backend). */
   listDocuments(collection: string): Promise<ContentDocumentMeta[]>;
-  /** Reads a single document, or `null` if it does not exist. */
+  /** Reads a single document, or `null` if it does not exist (live backend). */
   getDocument(collection: string, slug: string): Promise<ContentDocument | null>;
 }
 
 /**
  * Creates an {@link Ocsm} instance from an author-supplied config. Call once in a
- * server-only module and reuse the returned instance across the app. Content,
- * users, and theme all share a single storage backend (filesystem in dev,
- * GitHub in production).
+ * server-only module and reuse the returned instance across the app.
+ *
+ * The **live backend** (filesystem in dev, GitHub in production) powers the
+ * editor's live reads and all writes. A separate **filesystem reader**
+ * ({@link Ocsm.public}) serves the public site so the build never calls GitHub.
  *
  * @example
  * ```ts
@@ -50,10 +76,19 @@ export interface Ocsm {
  */
 export function createOcsm(config: OcsmConfig): Ocsm {
   const resolved = resolveOcsmConfig(config);
+
+  // Live backend: GitHub in production, filesystem in dev.
   const backend = createFileBackend();
   const store = createContentStore(resolved, backend);
   const json = new JsonStore(backend);
 
+  // Public reader: always the local filesystem (the repo checkout).
+  const fsBackend = new FsFileBackend();
+  const publicStore = createContentStore(resolved, fsBackend);
+  const publicJson = new JsonStore(fsBackend);
+  const publicLayout = new LayoutStore(publicJson);
+  const publicTheme = new ThemeStore(publicJson);
+
   return {
     config: resolved,
     store,
@@ -61,6 +96,13 @@ export function createOcsm(config: OcsmConfig): Ocsm {
     roles: new RoleStore(json),
     theme: new ThemeStore(json),
     layout: new LayoutStore(json),
+    media: new MediaStore(backend),
+    public: {
+      listDocuments: (collection) => publicStore.list(collection),
+      getDocument: (collection, slug) => publicStore.read(collection, slug),
+      getLayout: (region) => publicLayout.get(region),
+      getTheme: () => publicTheme.get(),
+    },
     listDocuments: (collection) => store.list(collection),
     getDocument: (collection, slug) => store.read(collection, slug),
   };

package/src/server/index.ts

@@ -1,7 +1,18 @@
-export { createOcsm, type Ocsm } from "./create-ocsm";
+export { createOcsm, type Ocsm, type PublicReader } from "./create-ocsm";
 export { deleteDocument, writeDocument } from "./documents";
+export { handleMediaRequest } from "./media-route";
 export { OcsmContent, type OcsmContentProps } from "./render-mdx";
 
+// Media
+export {
+  ACCEPTED_UPLOAD_HINT,
+  MAX_UPLOAD_BYTES,
+  type MediaContent,
+  MediaStore,
+  type StoredMedia,
+  UPLOAD_ACCEPT_ATTR,
+} from "../media";
+
 // Auth, users & roles
 export { authenticate, setupFirstAdmin } from "../auth/authenticate";
 export { hashPassword, verifyPassword } from "../auth/password";

package/src/server/media-route.ts

@@ -0,0 +1,32 @@
+import type { Ocsm } from "./create-ocsm";
+
+/**
+ * Serves an uploaded media file as a web `Response`. Mount this in a Route
+ * Handler at `app/ocsm-media/[...path]/route.ts`:
+ *
+ * ```ts
+ * import { handleMediaRequest } from "@orhancodestudio/ocsm-core/server";
+ * import { ocsm } from "@/lib/ocsm";
+ *
+ * export async function GET(_req: Request, ctx: { params: Promise<{ path: string[] }> }) {
+ *   const { path } = await ctx.params;
+ *   return handleMediaRequest(ocsm, path.join("/"));
+ * }
+ * ```
+ */
+export async function handleMediaRequest(
+  ocsm: Ocsm,
+  name: string,
+): Promise<Response> {
+  const file = await ocsm.media.read(name);
+  if (!file) {
+    return new Response("Not found", { status: 404 });
+  }
+  return new Response(new Uint8Array(file.data), {
+    headers: {
+      "content-type": file.contentType,
+      // Filenames are unique per upload, so they are safe to cache forever.
+      "cache-control": "public, max-age=31536000, immutable",
+    },
+  });
+}

package/src/storage/file-backend.ts

@@ -8,6 +8,10 @@ export interface FileBackend {
   read(path: string): Promise<string | null>;
   /** Creates or overwrites a file. `message` is used as the commit message by git backends. */
   write(path: string, content: string, message?: string): Promise<void>;
+  /** Reads a binary file, or returns `null` if it does not exist. */
+  readBinary(path: string): Promise<Buffer | null>;
+  /** Creates or overwrites a binary file. */
+  writeBinary(path: string, data: Buffer, message?: string): Promise<void>;
   /** Deletes a file. No-op if it does not exist. */
   remove(path: string, message?: string): Promise<void>;
   /** Lists file names (not directories) directly inside `dir`. Returns `[]` if missing. */

package/src/storage/fs-file-backend.ts

@@ -21,6 +21,21 @@ export class FsFileBackend implements FileBackend {
     await fs.writeFile(absolute, content, "utf8");
   }
 
+  async readBinary(filePath: string): Promise<Buffer | null> {
+    try {
+      return await fs.readFile(this.resolve(filePath));
+    } catch (error) {
+      if (isNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+
+  async writeBinary(filePath: string, data: Buffer): Promise<void> {
+    const absolute = this.resolve(filePath);
+    await fs.mkdir(path.dirname(absolute), { recursive: true });
+    await fs.writeFile(absolute, data);
+  }
+
   async remove(filePath: string): Promise<void> {
     await fs.rm(this.resolve(filePath), { force: true });
   }

package/src/storage/github-file-backend.ts

@@ -37,12 +37,44 @@ export class GitHubFileBackend implements FileBackend {
   }
 
   async write(filePath: string, content: string, message?: string): Promise<void> {
+    await this.writeBinary(filePath, Buffer.from(content, "utf8"), message);
+  }
+
+  async readBinary(filePath: string): Promise<Buffer | null> {
+    try {
+      const { data } = await this.octokit.repos.getContent({
+        ...this.base(),
+        ref: this.options.branch,
+        path: filePath,
+      });
+      if (Array.isArray(data) || data.type !== "file") return null;
+      if (data.content) {
+        return Buffer.from(data.content, "base64");
+      }
+      // Files larger than ~1MB return empty content; fetch the raw blob instead.
+      if (data.download_url) {
+        const res = await fetch(data.download_url);
+        if (!res.ok) return null;
+        return Buffer.from(await res.arrayBuffer());
+      }
+      return null;
+    } catch (error) {
+      if (isNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+
+  async writeBinary(
+    filePath: string,
+    data: Buffer,
+    message?: string,
+  ): Promise<void> {
     await this.octokit.repos.createOrUpdateFileContents({
       ...this.base(),
       branch: this.options.branch,
       path: filePath,
       message: message ?? `ocsm: update ${filePath}`,
-      content: Buffer.from(content, "utf8").toString("base64"),
+      content: data.toString("base64"),
       sha: await this.shaFor(filePath),
     });
   }

package/src/version.ts

@@ -5,7 +5,7 @@
  * update checker ({@link ./update/check-for-updates}) and the admin "update available"
  * notice.
  */
-export const OCSM_VERSION = "0.1.0-alpha.1";
+export const OCSM_VERSION = "0.1.0-alpha.3";
 
 /** The published npm package name for the OCS Management core. */
 export const OCSM_PACKAGE_NAME = "@orhancodestudio/ocsm-core";