@orhancodestudio/ocsm-core 0.1.0-alpha.1

package/src/index.ts

@@ -0,0 +1,10 @@
+export { defineOcsmConfig } from "./config/define-config";
+export { resolveOcsmConfig } from "./config/resolve-config";
+export type {
+  OcsmBrandConfig,
+  OcsmConfig,
+  OcsmContentCollectionConfig,
+  ResolvedOcsmConfig,
+} from "./config/config.types";
+export { checkForUpdates, type UpdateStatus } from "./update/check-for-updates";
+export { OCSM_PACKAGE_NAME, OCSM_VERSION } from "./version";

package/src/layout/index.ts

@@ -0,0 +1 @@
+export { type LayoutRegion, LayoutStore } from "./layout-store";

package/src/layout/layout-store.ts

@@ -0,0 +1,27 @@
+import { type Block, normalizeBlocks } from "../blocks/block.types";
+import type { JsonStore } from "../storage/json-store";
+
+/** Global layout regions shared across every page. */
+export type LayoutRegion = "header" | "footer";
+
+const PATHS: Record<LayoutRegion, string> = {
+  header: "ocsm/header.json",
+  footer: "ocsm/footer.json",
+};
+
+/**
+ * Stores the global **header** and **footer** section blocks (Shopify-style),
+ * which render on every page. The per-page body lives in each document instead.
+ */
+export class LayoutStore {
+  constructor(private readonly json: JsonStore) {}
+
+  async get(region: LayoutRegion): Promise<Block[]> {
+    const data = await this.json.read<{ blocks: unknown }>(PATHS[region]);
+    return normalizeBlocks(data?.blocks);
+  }
+
+  async save(region: LayoutRegion, blocks: Block[]): Promise<void> {
+    await this.json.write(PATHS[region], { blocks }, `ocsm: update ${region}`);
+  }
+}

package/src/roles/index.ts

@@ -0,0 +1,10 @@
+export {
+  ALL_PERMISSIONS,
+  DEFAULT_ROLES,
+  type OcsmPermission,
+  type OcsmRole,
+  type RolesFile,
+  sanitizePermissions,
+  SYSTEM_ADMIN_ROLE_ID,
+} from "./role.types";
+export { type RoleInput, RoleStore } from "./role-store";

package/src/roles/role-store.ts

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import type { JsonStore } from "../storage/json-store";
+import {
+  DEFAULT_ROLES,
+  type OcsmPermission,
+  type OcsmRole,
+  type RolesFile,
+  sanitizePermissions,
+  SYSTEM_ADMIN_ROLE_ID,
+} from "./role.types";
+
+const ROLES_PATH = "ocsm/roles.json";
+
+export interface RoleInput {
+  name: string;
+  permissions: OcsmPermission[];
+}
+
+/** Manages roles persisted to `ocsm/roles.json`, seeded with defaults. */
+export class RoleStore {
+  constructor(private readonly json: JsonStore) {}
+
+  async list(): Promise<OcsmRole[]> {
+    const data = await this.json.read<RolesFile>(ROLES_PATH);
+    if (!data || !Array.isArray(data.roles) || data.roles.length === 0) {
+      return DEFAULT_ROLES.map((role) => ({ ...role }));
+    }
+    return data.roles;
+  }
+
+  async get(id: string): Promise<OcsmRole | null> {
+    return (await this.list()).find((role) => role.id === id) ?? null;
+  }
+
+  /** Resolves a role id to its name + permissions, with safe fallbacks. */
+  async resolve(id: string): Promise<{ name: string; permissions: OcsmPermission[] }> {
+    const role = await this.get(id);
+    if (role) return { name: role.name, permissions: role.permissions };
+    return { name: id, permissions: [] };
+  }
+
+  async create(input: RoleInput): Promise<OcsmRole> {
+    const roles = await this.list();
+    const name = input.name.trim();
+    if (!name) throw new Error("OCSM: rol adı boş olamaz");
+    if (roles.some((r) => r.name.toLowerCase() === name.toLowerCase())) {
+      throw new Error(`OCSM: "${name}" adlı bir rol zaten var`);
+    }
+    const role: OcsmRole = {
+      id: randomUUID(),
+      name,
+      permissions: sanitizePermissions(input.permissions),
+    };
+    await this.save([...roles, role]);
+    return role;
+  }
+
+  async update(id: string, input: RoleInput): Promise<void> {
+    const roles = await this.list();
+    const target = roles.find((r) => r.id === id);
+    if (!target) throw new Error("OCSM: rol bulunamadı");
+
+    const name = input.name.trim();
+    if (!name) throw new Error("OCSM: rol adı boş olamaz");
+    if (
+      roles.some(
+        (r) => r.id !== id && r.name.toLowerCase() === name.toLowerCase(),
+      )
+    ) {
+      throw new Error(`OCSM: "${name}" adlı bir rol zaten var`);
+    }
+
+    target.name = name;
+    // The system admin role always keeps every permission (prevents lockout).
+    if (id !== SYSTEM_ADMIN_ROLE_ID) {
+      target.permissions = sanitizePermissions(input.permissions);
+    }
+    await this.save(roles);
+  }
+
+  async remove(id: string, assignedRoleIds: string[] = []): Promise<void> {
+    const roles = await this.list();
+    const target = roles.find((r) => r.id === id);
+    if (!target) return;
+    if (target.system) throw new Error("OCSM: sistem rolü silinemez");
+    if (assignedRoleIds.includes(id)) {
+      throw new Error("OCSM: bu role atanmış kullanıcılar var; önce onları taşıyın");
+    }
+    await this.save(roles.filter((r) => r.id !== id));
+  }
+
+  private async save(roles: OcsmRole[]): Promise<void> {
+    await this.json.write<RolesFile>(ROLES_PATH, { roles }, "ocsm: update roles");
+  }
+}

package/src/roles/role.types.ts

@@ -0,0 +1,86 @@
+/** The fixed set of capabilities a role can grant. */
+export type OcsmPermission =
+  | "content:read"
+  | "content:write"
+  | "content:delete"
+  | "users:manage"
+  | "settings:manage";
+
+/** A role: a named set of permissions. Custom roles are user-defined. */
+export interface OcsmRole {
+  id: string;
+  name: string;
+  permissions: OcsmPermission[];
+  /** System roles cannot be deleted and (for admin) have locked permissions. */
+  system?: boolean;
+}
+
+/** On-disk shape of `ocsm/roles.json`. */
+export interface RolesFile {
+  roles: OcsmRole[];
+}
+
+/** Every permission, with a human-readable label, for the role editor UI. */
+export const ALL_PERMISSIONS: ReadonlyArray<{
+  key: OcsmPermission;
+  label: string;
+  description: string;
+}> = [
+  {
+    key: "content:read",
+    label: "İçerikleri görüntüle",
+    description: "Panelde içerikleri listeleyip görebilir.",
+  },
+  {
+    key: "content:write",
+    label: "İçerik oluştur / düzenle",
+    description: "Sayfa ve yazıları oluşturup düzenleyebilir.",
+  },
+  {
+    key: "content:delete",
+    label: "İçerik sil",
+    description: "Sayfa ve yazıları silebilir.",
+  },
+  {
+    key: "users:manage",
+    label: "Kullanıcıları yönet",
+    description: "Kullanıcı ekleyip düzenleyip silebilir.",
+  },
+  {
+    key: "settings:manage",
+    label: "Yapılandırmayı yönet",
+    description: "Rolleri ve sistem ayarlarını yönetebilir.",
+  },
+];
+
+const ALL_PERMISSION_KEYS: OcsmPermission[] = ALL_PERMISSIONS.map((p) => p.key);
+
+/** Default seed roles, used when `ocsm/roles.json` does not exist yet. */
+export const DEFAULT_ROLES: OcsmRole[] = [
+  {
+    id: "admin",
+    name: "Yönetici",
+    permissions: [...ALL_PERMISSION_KEYS],
+    system: true,
+  },
+  {
+    id: "editor",
+    name: "Editör",
+    permissions: ["content:read", "content:write", "content:delete"],
+  },
+];
+
+/** The role id always granted every permission and never deletable. */
+export const SYSTEM_ADMIN_ROLE_ID = "admin";
+
+/** Returns a deduplicated, valid permission list. */
+export function sanitizePermissions(input: unknown): OcsmPermission[] {
+  if (!Array.isArray(input)) return [];
+  const set = new Set<OcsmPermission>();
+  for (const value of input) {
+    if (ALL_PERMISSION_KEYS.includes(value as OcsmPermission)) {
+      set.add(value as OcsmPermission);
+    }
+  }
+  return [...set];
+}

package/src/server/create-ocsm.ts

@@ -0,0 +1,67 @@
+import type { OcsmConfig, ResolvedOcsmConfig } from "../config/config.types";
+import { resolveOcsmConfig } from "../config/resolve-config";
+import type { ContentStore } from "../content/content-store.interface";
+import type {
+  ContentDocument,
+  ContentDocumentMeta,
+} from "../content/content.types";
+import { createContentStore } from "../content/create-content-store";
+import { LayoutStore } from "../layout/layout-store";
+import { RoleStore } from "../roles/role-store";
+import { createFileBackend } from "../storage/create-file-backend";
+import { JsonStore } from "../storage/json-store";
+import { ThemeStore } from "../theme/theme-store";
+import { UserStore } from "../users/user-store";
+
+/** 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). */
+  readonly store: ContentStore;
+  /** User management. */
+  readonly users: UserStore;
+  /** Role & permission management. */
+  readonly roles: RoleStore;
+  /** Public-site theme. */
+  readonly theme: ThemeStore;
+  /** Global header/footer sections shared across every page. */
+  readonly layout: LayoutStore;
+  /** Lists documents in a collection. */
+  listDocuments(collection: string): Promise<ContentDocumentMeta[]>;
+  /** Reads a single document, or `null` if it does not exist. */
+  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).
+ *
+ * @example
+ * ```ts
+ * // lib/ocsm.ts
+ * import { createOcsm } from "@orhancodestudio/ocsm-core/server";
+ * import config from "@/ocsm.config";
+ *
+ * export const ocsm = createOcsm(config);
+ * ```
+ */
+export function createOcsm(config: OcsmConfig): Ocsm {
+  const resolved = resolveOcsmConfig(config);
+  const backend = createFileBackend();
+  const store = createContentStore(resolved, backend);
+  const json = new JsonStore(backend);
+
+  return {
+    config: resolved,
+    store,
+    users: new UserStore(json),
+    roles: new RoleStore(json),
+    theme: new ThemeStore(json),
+    layout: new LayoutStore(json),
+    listDocuments: (collection) => store.list(collection),
+    getDocument: (collection, slug) => store.read(collection, slug),
+  };
+}

package/src/server/documents.ts

@@ -0,0 +1,28 @@
+import type { SaveDocumentInput } from "../admin/admin.types";
+import type { Ocsm } from "./create-ocsm";
+
+/**
+ * Persists a document from the page builder. Section blocks are stored in the
+ * document's frontmatter. Wrap this in a `"use server"` action in your app.
+ */
+export async function writeDocument(
+  ocsm: Ocsm,
+  input: SaveDocumentInput,
+): Promise<void> {
+  await ocsm.store.write({
+    collection: input.collection,
+    slug: input.slug,
+    frontmatter: { title: input.title, blocks: input.blocks },
+    body: "",
+    message: `ocsm: save ${input.collection}/${input.slug}`,
+  });
+}
+
+/** Deletes a document. Wrap this in a `"use server"` action in your app. */
+export async function deleteDocument(
+  ocsm: Ocsm,
+  collection: string,
+  slug: string,
+): Promise<void> {
+  await ocsm.store.delete(collection, slug);
+}

package/src/server/index.ts

@@ -0,0 +1,59 @@
+export { createOcsm, type Ocsm } from "./create-ocsm";
+export { deleteDocument, writeDocument } from "./documents";
+export { OcsmContent, type OcsmContentProps } from "./render-mdx";
+
+// Auth, users & roles
+export { authenticate, setupFirstAdmin } from "../auth/authenticate";
+export { hashPassword, verifyPassword } from "../auth/password";
+export { requirePermission, userHasPermission } from "../auth/permissions";
+export {
+  createSession,
+  destroySession,
+  getSessionUser,
+  type SessionUser,
+} from "../auth/session";
+export {
+  type CreateUserInput,
+  type PublicUser,
+  type UpdateUserInput,
+  UserStore,
+} from "../users";
+export {
+  ALL_PERMISSIONS,
+  DEFAULT_ROLES,
+  type OcsmPermission,
+  type OcsmRole,
+  type RoleInput,
+  RoleStore,
+  SYSTEM_ADMIN_ROLE_ID,
+} from "../roles";
+
+// Theme
+export {
+  DEFAULT_THEME,
+  type OcsmTheme,
+  themeToCssString,
+  themeToCssVariables,
+  THEME_FIELDS,
+  ThemeStore,
+} from "../theme";
+
+// Layout (global header/footer)
+export { type LayoutRegion, LayoutStore } from "../layout";
+
+// Blocks & rendering
+export {
+  type Block,
+  BLOCK_TYPES,
+  BlockRenderer,
+  type BlockType,
+  createBlock,
+  normalizeBlocks,
+  OcsmMarkdown,
+} from "../blocks";
+
+// Content types
+export type {
+  ContentDocument,
+  ContentDocumentMeta,
+} from "../content/content.types";

package/src/server/render-mdx.tsx

@@ -0,0 +1,14 @@
+import { OcsmMarkdown } from "../blocks/markdown";
+
+export interface OcsmContentProps {
+  /** Raw Markdown body to render. */
+  source: string;
+}
+
+/**
+ * Renders a Markdown body. Kept for backward compatibility with documents that
+ * store a plain Markdown body instead of section blocks.
+ */
+export function OcsmContent({ source }: OcsmContentProps) {
+  return <OcsmMarkdown>{source}</OcsmMarkdown>;
+}

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

@@ -0,0 +1,26 @@
+import type { FileBackend } from "./file-backend";
+import { FsFileBackend } from "./fs-file-backend";
+import { GitHubFileBackend } from "./github-file-backend";
+
+/**
+ * Selects a {@link FileBackend} from the environment:
+ *
+ * - `OCSM_GITHUB_TOKEN` + `OCSM_GITHUB_REPO` set → {@link GitHubFileBackend}
+ *   (serverless production).
+ * - otherwise → {@link FsFileBackend} (local development).
+ */
+export function createFileBackend(): FileBackend {
+  const token = process.env.OCSM_GITHUB_TOKEN;
+  const repo = process.env.OCSM_GITHUB_REPO;
+  const branch = process.env.OCSM_GITHUB_BRANCH ?? "main";
+
+  if (token && repo) {
+    const [owner, name] = repo.split("/");
+    if (!owner || !name) {
+      throw new Error('OCSM: OCSM_GITHUB_REPO must use the "owner/repo" format');
+    }
+    return new GitHubFileBackend({ token, owner, repo: name, branch });
+  }
+
+  return new FsFileBackend();
+}

package/src/storage/file-backend.ts

@@ -0,0 +1,26 @@
+/**
+ * Low-level storage abstraction shared by the content layer and the JSON data
+ * stores (users, theme, settings). Implementations: {@link FsFileBackend} for
+ * local development and {@link GitHubFileBackend} for serverless production.
+ */
+export interface FileBackend {
+  /** Reads a UTF-8 file, or returns `null` if it does not exist. */
+  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>;
+  /** 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. */
+  listFiles(dir: string): Promise<string[]>;
+}
+
+/** Narrows an unknown error to a "not found" condition (filesystem or HTTP 404). */
+export function isNotFoundError(error: unknown): boolean {
+  if ((error as NodeJS.ErrnoException | null)?.code === "ENOENT") return true;
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    (error as { status: number }).status === 404
+  );
+}

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

@@ -0,0 +1,43 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { type FileBackend, isNotFoundError } from "./file-backend";
+
+/** Reads and writes files on the local filesystem, relative to a working directory. */
+export class FsFileBackend implements FileBackend {
+  constructor(private readonly cwd: string = process.cwd()) {}
+
+  async read(filePath: string): Promise<string | null> {
+    try {
+      return await fs.readFile(this.resolve(filePath), "utf8");
+    } catch (error) {
+      if (isNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+
+  async write(filePath: string, content: string): Promise<void> {
+    const absolute = this.resolve(filePath);
+    await fs.mkdir(path.dirname(absolute), { recursive: true });
+    await fs.writeFile(absolute, content, "utf8");
+  }
+
+  async remove(filePath: string): Promise<void> {
+    await fs.rm(this.resolve(filePath), { force: true });
+  }
+
+  async listFiles(dir: string): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(this.resolve(dir), {
+        withFileTypes: true,
+      });
+      return entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+    } catch (error) {
+      if (isNotFoundError(error)) return [];
+      throw error;
+    }
+  }
+
+  private resolve(filePath: string): string {
+    return path.join(this.cwd, filePath);
+  }
+}

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

@@ -0,0 +1,97 @@
+import { Buffer } from "node:buffer";
+import { Octokit } from "@octokit/rest";
+import { type FileBackend, isNotFoundError } from "./file-backend";
+
+export interface GitHubFileBackendOptions {
+  /** GitHub access token with `contents:write` on the target repo. */
+  token: string;
+  owner: string;
+  repo: string;
+  branch: string;
+}
+
+/**
+ * Reads files via the GitHub Contents API and writes them back as commits.
+ * Used in production (e.g. on Vercel) where the runtime filesystem is ephemeral.
+ */
+export class GitHubFileBackend implements FileBackend {
+  private readonly octokit: Octokit;
+
+  constructor(private readonly options: GitHubFileBackendOptions) {
+    this.octokit = new Octokit({ auth: options.token });
+  }
+
+  async read(filePath: string): Promise<string | 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;
+      return Buffer.from(data.content, "base64").toString("utf8");
+    } catch (error) {
+      if (isNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+
+  async write(filePath: string, content: string, 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"),
+      sha: await this.shaFor(filePath),
+    });
+  }
+
+  async remove(filePath: string, message?: string): Promise<void> {
+    const sha = await this.shaFor(filePath);
+    if (!sha) return;
+    await this.octokit.repos.deleteFile({
+      ...this.base(),
+      branch: this.options.branch,
+      path: filePath,
+      message: message ?? `ocsm: delete ${filePath}`,
+      sha,
+    });
+  }
+
+  async listFiles(dir: string): Promise<string[]> {
+    try {
+      const { data } = await this.octokit.repos.getContent({
+        ...this.base(),
+        ref: this.options.branch,
+        path: dir,
+      });
+      if (!Array.isArray(data)) return [];
+      return data
+        .filter((entry) => entry.type === "file")
+        .map((entry) => entry.name);
+    } catch (error) {
+      if (isNotFoundError(error)) return [];
+      throw error;
+    }
+  }
+
+  private base(): { owner: string; repo: string } {
+    return { owner: this.options.owner, repo: this.options.repo };
+  }
+
+  private async shaFor(filePath: string): Promise<string | undefined> {
+    try {
+      const { data } = await this.octokit.repos.getContent({
+        ...this.base(),
+        ref: this.options.branch,
+        path: filePath,
+      });
+      if (Array.isArray(data) || data.type !== "file") return undefined;
+      return data.sha;
+    } catch (error) {
+      if (isNotFoundError(error)) return undefined;
+      throw error;
+    }
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,8 @@
+export { type FileBackend, isNotFoundError } from "./file-backend";
+export { FsFileBackend } from "./fs-file-backend";
+export {
+  GitHubFileBackend,
+  type GitHubFileBackendOptions,
+} from "./github-file-backend";
+export { createFileBackend } from "./create-file-backend";
+export { JsonStore } from "./json-store";

package/src/storage/json-store.ts

@@ -0,0 +1,23 @@
+import type { FileBackend } from "./file-backend";
+
+/** Reads and writes JSON documents through a {@link FileBackend}. */
+export class JsonStore {
+  constructor(private readonly backend: FileBackend) {}
+
+  /** Reads and parses a JSON file, or returns `null` if it does not exist. */
+  async read<T>(path: string): Promise<T | null> {
+    const raw = await this.backend.read(path);
+    if (raw === null) return null;
+    return JSON.parse(raw) as T;
+  }
+
+  /** Reads a JSON file, falling back to `fallback` when it does not exist. */
+  async readOr<T>(path: string, fallback: T): Promise<T> {
+    return (await this.read<T>(path)) ?? fallback;
+  }
+
+  /** Serializes and writes a JSON file (pretty-printed). */
+  async write<T>(path: string, data: T, message?: string): Promise<void> {
+    await this.backend.write(path, `${JSON.stringify(data, null, 2)}\n`, message);
+  }
+}

package/src/theme/css.ts

@@ -0,0 +1,28 @@
+import type { OcsmTheme } from "./theme.types";
+
+/** Maps a theme to its CSS custom properties. */
+export function themeToCssVariables(theme: OcsmTheme): Record<string, string> {
+  return {
+    "--ocsm-primary": theme.primaryColor,
+    "--ocsm-accent": theme.accentColor,
+    "--ocsm-bg": theme.backgroundColor,
+    "--ocsm-surface": theme.surfaceColor,
+    "--ocsm-text": theme.textColor,
+    "--ocsm-muted": theme.mutedColor,
+    "--ocsm-font": theme.fontFamily,
+    "--ocsm-font-heading": theme.headingFontFamily,
+    "--ocsm-radius": theme.radius,
+    "--ocsm-max-width": theme.maxWidth,
+  };
+}
+
+/**
+ * Renders a theme as a `:root { ... }` CSS string. Inject the result into a
+ * `<style>` tag in your site layout so pages can use `var(--ocsm-*)`.
+ */
+export function themeToCssString(theme: OcsmTheme): string {
+  const declarations = Object.entries(themeToCssVariables(theme))
+    .map(([name, value]) => `${name}: ${value};`)
+    .join(" ");
+  return `:root { ${declarations} }`;
+}

package/src/theme/index.ts

@@ -0,0 +1,8 @@
+export {
+  DEFAULT_THEME,
+  type OcsmTheme,
+  type ThemeFieldDescriptor,
+  THEME_FIELDS,
+} from "./theme.types";
+export { ThemeStore } from "./theme-store";
+export { themeToCssString, themeToCssVariables } from "./css";