freelang-editor 11.7.4

package/src/stdlib-async.ts

@@ -0,0 +1,179 @@
+// FreeLang v9: Async Standard Library
+// Phase 23: Async/await primitives - promise creation, awaiting, and composition
+
+import { FreeLangPromise, resolvedPromise, rejectedPromise } from "./async-runtime";
+
+type CallFn = (name: string, args: any[]) => any;
+
+/**
+ * Create the async module for FreeLang v9
+ * Provides: async_call, await_result, promise_all, promise_race,
+ *           promise_delay, promise_timeout
+ */
+export function createAsyncModule(callFn: CallFn) {
+  return {
+    // async_call fn_name args -> Promise
+    // Call a function asynchronously and return a promise
+    "async_call": (fnName: string, args: any[] = []): FreeLangPromise => {
+      return new FreeLangPromise((resolve, reject) => {
+        setImmediate(() => {
+          try {
+            const result = callFn(fnName, args);
+            resolve(result);
+          } catch (e: any) {
+            reject(new Error(`async_call error: ${e.message}`));
+          }
+        });
+      });
+    },
+
+    // await_result promise -> value|error
+    // Wait for a promise to resolve and get its value
+    "await_result": (promise: FreeLangPromise): any => {
+      const state = promise.getState();
+      if (state === "resolved") {
+        return promise.getValue();
+      } else if (state === "rejected") {
+        throw promise.getError() || new Error("Promise rejected");
+      } else {
+        // Still pending - throw error (should use real async/await in practice)
+        throw new Error("Promise still pending - use proper async handling");
+      }
+    },
+
+    // promise_all promises -> Promise
+    // Wait for all promises to resolve
+    "promise_all": (promises: FreeLangPromise[]): FreeLangPromise => {
+      return new FreeLangPromise((resolve, reject) => {
+        if (!Array.isArray(promises) || promises.length === 0) {
+          resolve([]);
+          return;
+        }
+
+        const results: any[] = [];
+        let completed = 0;
+
+        promises.forEach((p, idx) => {
+          if (!(p instanceof FreeLangPromise)) {
+            reject(new Error(`promise_all: element ${idx} is not a promise`));
+            return;
+          }
+
+          const state = p.getState();
+          if (state === "resolved") {
+            results[idx] = p.getValue();
+            completed++;
+            if (completed === promises.length) resolve(results);
+          } else if (state === "rejected") {
+            reject(p.getError() || new Error(`promise_all: promise ${idx} rejected`));
+          } else {
+            // For pending promises, we'd need proper async handling
+            reject(new Error(`promise_all: promise ${idx} still pending`));
+          }
+        });
+      });
+    },
+
+    // promise_race promises -> Promise
+    // Return first resolved promise
+    "promise_race": (promises: FreeLangPromise[]): FreeLangPromise => {
+      return new FreeLangPromise((resolve, reject) => {
+        if (!Array.isArray(promises) || promises.length === 0) {
+          reject(new Error("promise_race: empty promise array"));
+          return;
+        }
+
+        for (let i = 0; i < promises.length; i++) {
+          const p = promises[i];
+          if (!(p instanceof FreeLangPromise)) {
+            reject(new Error(`promise_race: element ${i} is not a promise`));
+            return;
+          }
+
+          const state = p.getState();
+          if (state === "resolved") {
+            resolve(p.getValue());
+            return;
+          } else if (state === "rejected") {
+            reject(p.getError() || new Error(`promise_race: promise ${i} rejected`));
+            return;
+          }
+        }
+
+        // All pending
+        reject(new Error("promise_race: all promises still pending"));
+      });
+    },
+
+    // promise_delay ms -> Promise
+    // Create a promise that resolves after delay
+    "promise_delay": (ms: number): FreeLangPromise => {
+      return new FreeLangPromise((resolve) => {
+        setTimeout(() => resolve(null), ms);
+      });
+    },
+
+    // promise_timeout ms fn_name args -> Promise
+    // Call function with timeout
+    "promise_timeout": (ms: number, fnName: string, args: any[] = []): FreeLangPromise => {
+      return new FreeLangPromise((resolve, reject) => {
+        let done = false;
+        const timeout = setTimeout(() => {
+          if (!done) {
+            done = true;
+            reject(new Error(`promise_timeout: timed out after ${ms}ms`));
+          }
+        }, ms);
+
+        try {
+          const result = callFn(fnName, args);
+          done = true;
+          clearTimeout(timeout);
+          resolve(result);
+        } catch (e: any) {
+          done = true;
+          clearTimeout(timeout);
+          reject(new Error(`promise_timeout: ${e.message}`));
+        }
+      });
+    },
+
+    // promise_resolve value -> Promise
+    // Create immediately resolved promise
+    "promise_resolve": (value: any): FreeLangPromise => {
+      return resolvedPromise(value);
+    },
+
+    // promise_reject error -> Promise
+    // Create immediately rejected promise
+    "promise_reject": (error: any): FreeLangPromise => {
+      const err = error instanceof Error ? error : new Error(String(error));
+      return rejectedPromise(err);
+    },
+
+    // promise_state promise -> "pending"|"resolved"|"rejected"
+    // Get promise state
+    "promise_state": (promise: FreeLangPromise): string => {
+      if (!(promise instanceof FreeLangPromise)) {
+        return "unknown";
+      }
+      return promise.getState();
+    },
+
+    // promise_then promise fn_name -> Promise
+    // Chain promise with handler function
+    "promise_then": (promise: FreeLangPromise, fnName: string): FreeLangPromise => {
+      if (!(promise instanceof FreeLangPromise)) {
+        return rejectedPromise(new Error("promise_then: first arg is not a promise"));
+      }
+
+      return promise.then((value) => {
+        try {
+          return callFn(fnName, [value]);
+        } catch (e: any) {
+          throw new Error(`promise_then handler error: ${e.message}`);
+        }
+      });
+    },
+  };
+}

package/src/stdlib-audit.ts

@@ -0,0 +1,94 @@
+// FreeLang v11: Audit Log Standard Library
+// audit_log — 서비스 감사 로그를 중앙 서버로 전송
+// 실패해도 본 작업을 막지 않음 (fire-and-forget)
+
+import { spawnSync } from "child_process";
+
+function postJson(url: string, body: string, apiKey: string): { ok: boolean; status: number } {
+  const args = [
+    "-s", "-o", "/dev/null", "-w", "%{http_code}",
+    "-X", "POST",
+    "-H", "Content-Type: application/json",
+    ...(apiKey ? ["-H", `X-Service-Key: ${apiKey}`] : []),
+    "-d", body,
+    url,
+  ];
+  try {
+    const result = spawnSync("curl", args, { timeout: 3000 });
+    const code = parseInt(result.stdout?.toString().trim() ?? "0", 10);
+    return { ok: code >= 200 && code < 300, status: code };
+  } catch {
+    return { ok: false, status: 0 };
+  }
+}
+
+export function createAuditModule() {
+  return {
+    // audit_log serviceId actorId action resource detail
+    //   → {:ok true :status 200} | {:ok false :status N}
+    // actorId가 nil이면 serviceId로 자동 대체
+    // 실패해도 nil 반환 (본 작업 차단 없음)
+    "audit_log": (
+      serviceId: string,
+      actorId: string | null,
+      action: string,
+      resource: string,
+      detail: string
+    ): any => {
+      const url = process.env.AUDIT_URL ?? "";
+      const key = process.env.AUDIT_SERVICE_KEY ?? "";
+      if (!url) return null;
+
+      const payload = JSON.stringify({
+        service_id: serviceId,
+        actor_id:   actorId ?? serviceId,
+        action,
+        resource,
+        detail,
+        timestamp:  new Date().toISOString(),
+      });
+
+      try {
+        return postJson(url, payload, key);
+      } catch {
+        return null;
+      }
+    },
+
+    // audit_log_custom serviceId actorId action resource detail extraMap
+    //   → extraMap을 페이로드에 병합
+    "audit_log_custom": (
+      serviceId: string,
+      actorId: string | null,
+      action: string,
+      resource: string,
+      detail: string,
+      extra: Record<string, any>
+    ): any => {
+      const url = process.env.AUDIT_URL ?? "";
+      const key = process.env.AUDIT_SERVICE_KEY ?? "";
+      if (!url) return null;
+
+      const payload = JSON.stringify({
+        service_id: serviceId,
+        actor_id:   actorId ?? serviceId,
+        action,
+        resource,
+        detail,
+        timestamp:  new Date().toISOString(),
+        ...(extra && typeof extra === "object" ? extra : {}),
+      });
+
+      try {
+        return postJson(url, payload, key);
+      } catch {
+        return null;
+      }
+    },
+
+    // audit_log_ok? result → true/false (결과 확인용)
+    "audit_log_ok?": (result: any): boolean => {
+      return result !== null && result !== undefined && result.ok === true;
+    },
+  };
+}

package/src/stdlib-auth.ts

@@ -0,0 +1,196 @@
+// FreeLang v9: Authentication Standard Library
+// Phase 21: JWT (native crypto), API key, password hashing, session tokens
+
+import { createHmac, createHash, randomBytes, timingSafeEqual, scryptSync } from "crypto";
+
+// ── JWT helpers (Node.js crypto only — no external deps) ─────────────────────
+
+function b64url(input: Buffer | string): string {
+  const buf = typeof input === "string" ? Buffer.from(input) : input;
+  return buf.toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+function b64urlDecode(s: string): string {
+  return Buffer.from(s, "base64url").toString("utf8");
+}
+
+function jwtSign(payload: any, secret: string, expirySeconds: number): string {
+  const iat = Math.floor(Date.now() / 1000);
+  const header = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body   = b64url(JSON.stringify({ ...payload, iat, exp: iat + expirySeconds }));
+  const sig    = b64url(createHmac("sha256", secret).update(`${header}.${body}`).digest());
+  return `${header}.${body}.${sig}`;
+}
+
+function jwtVerify(token: string, secret: string): any | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const [header, body, sig] = parts;
+    const expected = b64url(createHmac("sha256", secret).update(`${header}.${body}`).digest());
+    // timing-safe compare
+    const a = Buffer.from(sig + "=".repeat((4 - sig.length % 4) % 4), "base64");
+    const b = Buffer.from(expected + "=".repeat((4 - expected.length % 4) % 4), "base64");
+    if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+    const payload = JSON.parse(b64urlDecode(body));
+    if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) return null;
+    return payload;
+  } catch { return null; }
+}
+
+// ── Module ────────────────────────────────────────────────────────────────────
+
+export function createAuthModule() {
+  return {
+    // ── JWT ──────────────────────────────────────────────────
+
+    // auth_jwt_sign payload secret expiry_seconds → token
+    "auth_jwt_sign": (payload: any, secret: string, expiry: number = 3600): string => {
+      return jwtSign(payload, secret, expiry);
+    },
+
+    // auth_jwt_verify token secret → payload or null (null = invalid/expired)
+    "auth_jwt_verify": (token: string, secret: string): any => {
+      return jwtVerify(token, secret);
+    },
+
+    // auth_jwt_decode token → payload (no signature check)
+    "auth_jwt_decode": (token: string): any => {
+      try {
+        const [, body] = token.split(".");
+        return JSON.parse(b64urlDecode(body));
+      } catch { return null; }
+    },
+
+    // auth_jwt_expired token → boolean
+    "auth_jwt_expired": (token: string): boolean => {
+      try {
+        const [, body] = token.split(".");
+        const { exp } = JSON.parse(b64urlDecode(body));
+        return exp ? exp < Math.floor(Date.now() / 1000) : false;
+      } catch { return true; }
+    },
+
+    // ── Bearer / API Key extraction ──────────────────────────
+
+    // auth_bearer_extract req → token string or null
+    "auth_bearer_extract": (req: any): string | null => {
+      const auth = req?.headers?.authorization ?? req?.headers?.Authorization ?? "";
+      return typeof auth === "string" && auth.startsWith("Bearer ")
+        ? auth.slice(7)
+        : null;
+    },
+
+    // auth_apikey_valid req validKeys → boolean
+    // Checks X-API-Key header, then ?api_key query param
+    "auth_apikey_valid": (req: any, validKeys: string[]): boolean => {
+      const key = req?.headers?.["x-api-key"]
+        ?? req?.query?.api_key
+        ?? req?.body?.api_key
+        ?? "";
+      return Array.isArray(validKeys) && validKeys.includes(String(key));
+    },
+
+    // auth_apikey_get req → string (the raw key, or "")
+    "auth_apikey_get": (req: any): string => {
+      return String(
+        req?.headers?.["x-api-key"] ?? req?.query?.api_key ?? req?.body?.api_key ?? ""
+      );
+    },
+
+    // ── Password hashing ──────────────────────────────────
+    // v1: SHA256+salt (legacy, 빠른 단점)
+    // v2: scrypt (RFC 7914, memory-hard, 산업 표준급)
+    //
+    // 신규 비밀번호는 v2 사용. 기존 v1 해시는 verify 시 성공하면 v2로 자동 마이그레이션
+    // (호출 측에서 새 해시 받아 DB 업데이트).
+    //
+    // 형식:
+    //   v1: "salt_hex:sha256_hex"
+    //   v2: "$scrypt$N=16384,r=8,p=1$salt_b64$hash_b64"   (PHC 풍 식별자)
+
+    // auth_hash_password password → "$scrypt$..." (v2)
+    "auth_hash_password": (password: string): string => {
+      const N = 16384, r = 8, p = 1, keyLen = 64;
+      const salt = randomBytes(16);
+      const hash = scryptSync(password, salt, keyLen, { N, r, p });
+      return `$scrypt$N=${N},r=${r},p=${p}$${salt.toString("base64")}$${hash.toString("base64")}`;
+    },
+
+    // auth_verify_password password stored → boolean
+    // 두 포맷 모두 자동 인식.
+    "auth_verify_password": (password: string, stored: string): boolean => {
+      try {
+        if (stored.startsWith("$scrypt$")) {
+          const parts = stored.split("$"); // ["", "scrypt", "N=...,r=...,p=...", saltB64, hashB64]
+          if (parts.length !== 5) return false;
+          const params = Object.fromEntries(
+            parts[2].split(",").map((kv) => kv.split("=").map((s) => s.trim()))
+          );
+          const N = Number(params.N), r = Number(params.r), p = Number(params.p);
+          const salt = Buffer.from(parts[3], "base64");
+          const expected = Buffer.from(parts[4], "base64");
+          const computed = scryptSync(password, salt, expected.length, { N, r, p });
+          return expected.length === computed.length && timingSafeEqual(expected, computed);
+        }
+        // v1 legacy
+        const [salt, hash] = stored.split(":");
+        const computed = createHash("sha256").update(salt + password).digest("hex");
+        const a = Buffer.from(hash, "hex");
+        const b = Buffer.from(computed, "hex");
+        return a.length === b.length && timingSafeEqual(a, b);
+      } catch { return false; }
+    },
+
+    // auth_password_needs_rehash stored → boolean
+    // true면 호출 측은 새로 hash 후 DB 업데이트 (점진적 v1→v2 마이그레이션)
+    "auth_password_needs_rehash": (stored: string): boolean => {
+      return !stored.startsWith("$scrypt$");
+    },
+
+    // ── Tokens / HMAC ────────────────────────────────────────
+
+    // auth_random_token bytes → hex string
+    "auth_random_token": (bytes: number = 32): string => {
+      return randomBytes(bytes).toString("hex");
+    },
+
+    // auth_hmac data secret → hex-string (소문자 hex 64자)
+    // ※ secret은 UTF-8 문자열로 처리됨. SigV4 key chain에서 hex 출력을 다음 key로 재사용 가능.
+    // ⚠️ SigV4 정식 구현 시 raw-bytes key 필요 → auth_hmac_raw 사용 권장 (LIR-003)
+    "auth_hmac": (data: string, secret: string): string => {
+      return createHmac("sha256", secret).update(data).digest("hex");
+    },
+
+    // auth_sha256 data → hex-string (소문자 hex 64자)
+    "auth_sha256": (data: string): string => {
+      return createHash("sha256").update(data).digest("hex");
+    },
+
+    // auth_base64 data → base64 string
+    "auth_base64": (data: string): string => Buffer.from(data).toString("base64"),
+
+    // auth_base64_decode b64 → string
+    "auth_base64_decode": (b64: string): string => Buffer.from(b64, "base64").toString("utf8"),
+
+    // ── CSRF 방어 ────────────────────────────────────────
+
+    // auth_csrf_token secret → "timestamp.hmac" (60분 유효)
+    "auth_csrf_token": (secret: string): string => {
+      const ts = Math.floor(Date.now() / 1000).toString();
+      const sig = createHmac("sha256", secret).update(ts).digest("hex").slice(0, 16);
+      return `${ts}.${sig}`;
+    },
+
+    // auth_csrf_verify token secret → boolean
+    "auth_csrf_verify": (token: string, secret: string): boolean => {
+      const parts = (token || "").split(".");
+      if (parts.length !== 2) return false;
+      const [ts, sig] = parts;
+      const age = Math.floor(Date.now() / 1000) - parseInt(ts, 10);
+      if (isNaN(age) || age < 0 || age > 3600) return false;
+      const expected = createHmac("sha256", secret).update(ts).digest("hex").slice(0, 16);
+      return sig === expected;
+    },
+  };
+}

package/src/stdlib-bits.ts

@@ -0,0 +1,86 @@
+// FreeLang v11: Bitwise Operations Standard Library
+// Provides bitwise AND, OR, XOR, NOT, shift operations
+// Essential for CRC32 and other cryptographic operations
+
+/**
+ * Create the bitwise operations module for FreeLang
+ * Provides: bit_and, bit_or, bit_xor, bit_not, bit_shr, bit_shl
+ */
+export function createBitsModule() {
+  return {
+    // bit_and a b -> number (bitwise AND: a & b)
+    "bit_and": (a: number, b: number): number => {
+      return (a & b) >>> 0; // Ensure unsigned 32-bit
+    },
+
+    // bit_or a b -> number (bitwise OR: a | b)
+    "bit_or": (a: number, b: number): number => {
+      return (a | b) >>> 0;
+    },
+
+    // bit_xor a b -> number (bitwise XOR: a ^ b)
+    "bit_xor": (a: number, b: number): number => {
+      return (a ^ b) >>> 0;
+    },
+
+    // bit_not a -> number (bitwise NOT: ~a)
+    "bit_not": (a: number): number => {
+      return (~a) >>> 0;
+    },
+
+    // bit_shl a n -> number (shift left: a << n)
+    "bit_shl": (a: number, n: number): number => {
+      return (a << n) >>> 0;
+    },
+
+    // bit_shr a n -> number (unsigned right shift: a >>> n)
+    "bit_shr": (a: number, n: number): number => {
+      return (a >>> n) >>> 0;
+    },
+
+    // bit_sar a n -> number (arithmetic right shift: a >> n)
+    "bit_sar": (a: number, n: number): number => {
+      return (a >> n) >>> 0;
+    },
+
+    // bit_popcount a -> number (count set bits)
+    "bit_popcount": (a: number): number => {
+      a = a >>> 0; // Ensure unsigned
+      let count = 0;
+      while (a) {
+        count += a & 1;
+        a = a >>> 1;
+      }
+      return count;
+    },
+
+    // bit_test a n -> boolean (test bit at position n)
+    "bit_test": (a: number, n: number): boolean => {
+      return ((a >>> n) & 1) === 1;
+    },
+
+    // bit_set a n -> number (set bit at position n)
+    "bit_set": (a: number, n: number): number => {
+      return (a | (1 << n)) >>> 0;
+    },
+
+    // bit_clear a n -> number (clear bit at position n)
+    "bit_clear": (a: number, n: number): number => {
+      return (a & ~(1 << n)) >>> 0;
+    },
+
+    // bit_rotate_left a n -> number (rotate left: (a << n) | (a >>> (32-n)))
+    "bit_rotate_left": (a: number, n: number): number => {
+      a = a >>> 0;
+      n = n % 32;
+      return ((a << n) | (a >>> (32 - n))) >>> 0;
+    },
+
+    // bit_rotate_right a n -> number (rotate right: (a >>> n) | (a << (32-n)))
+    "bit_rotate_right": (a: number, n: number): number => {
+      a = a >>> 0;
+      n = n % 32;
+      return ((a >>> n) | (a << (32 - n))) >>> 0;
+    },
+  };
+}

package/src/stdlib-blog.ts

@@ -0,0 +1,127 @@
+// FreeLang v11 — Blog helpers (tags, related posts, search index)
+// Zero deps. Operates on arrays of post objects.
+
+interface Post {
+  slug: string;
+  title: string;
+  url?: string;
+  date?: string;
+  tags?: string[];
+  body?: string;   // plain text for search index
+  summary?: string;
+}
+
+function normalize(s: string): string {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9가-힣\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function createBlogModule() {
+  return {
+    // blog_all_tags [posts] → [tag1, tag2, ...] unique, sorted by count desc
+    "blog_all_tags": (posts: Post[]): string[] => {
+      const counts = new Map<string, number>();
+      for (const p of posts || []) {
+        for (const t of p.tags || []) {
+          counts.set(t, (counts.get(t) || 0) + 1);
+        }
+      }
+      return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map((e) => e[0]);
+    },
+
+    // blog_posts_by_tag [posts] tag → posts with that tag, newest first
+    "blog_posts_by_tag": (posts: Post[], tag: string): Post[] => {
+      const filtered = (posts || []).filter((p) => (p.tags || []).includes(tag));
+      return filtered.sort((a, b) => (b.date || "").localeCompare(a.date || ""));
+    },
+
+    // blog_tag_counts [posts] → {tag: count, ...}
+    "blog_tag_counts": (posts: Post[]): Record<string, number> => {
+      const counts: Record<string, number> = {};
+      for (const p of posts || []) {
+        for (const t of p.tags || []) {
+          counts[t] = (counts[t] || 0) + 1;
+        }
+      }
+      return counts;
+    },
+
+    // blog_related [posts] currentSlug limit → posts sharing most tags,
+    // excluding the current post, newest as tiebreak.
+    "blog_related": (posts: Post[], currentSlug: string, limit: number = 5): Post[] => {
+      const current = (posts || []).find((p) => p.slug === currentSlug);
+      if (!current) return [];
+      const currentTags = new Set(current.tags || []);
+      const scored = (posts || [])
+        .filter((p) => p.slug !== currentSlug)
+        .map((p) => ({
+          post: p,
+          score: (p.tags || []).filter((t) => currentTags.has(t)).length,
+          date: p.date || "",
+        }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score || b.date.localeCompare(a.date));
+      return scored.slice(0, Math.max(0, limit)).map((x) => x.post);
+    },
+
+    // blog_search_index [posts] → [{slug, title, url, body_terms}] compact JSON
+    // body_terms: space-joined normalized words, limited to 500 chars.
+    "blog_search_index": (posts: Post[]): Array<{ slug: string; title: string; url: string; terms: string }> => {
+      return (posts || []).map((p) => ({
+        slug: p.slug,
+        title: p.title,
+        url: p.url || `/blog/${p.slug}`,
+        terms: normalize(`${p.title} ${p.summary || ""} ${p.body || ""}`).slice(0, 500),
+      }));
+    },
+
+    // blog_search [index] query → top matches by term overlap score
+    "blog_search": (index: Array<{ slug: string; title: string; url: string; terms: string }>, query: string, limit: number = 10): any[] => {
+      const q = normalize(query);
+      if (!q) return [];
+      const terms = q.split(" ").filter(Boolean);
+      const results = (index || [])
+        .map((entry) => {
+          let score = 0;
+          for (const t of terms) {
+            if (entry.title.toLowerCase().includes(t)) score += 3;
+            if (entry.terms.includes(t)) score += 1;
+          }
+          return { entry, score };
+        })
+        .filter((r) => r.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, Math.max(0, limit))
+        .map((r) => ({ slug: r.entry.slug, title: r.entry.title, url: r.entry.url, score: r.score }));
+      return results;
+    },
+
+    // blog_posts_sorted [posts] → newest first
+    "blog_posts_sorted": (posts: Post[]): Post[] => {
+      return [...(posts || [])].sort((a, b) => (b.date || "").localeCompare(a.date || ""));
+    },
+
+    // blog_paginate [posts] page per-page → {items, total, page, pages}
+    "blog_paginate": (posts: Post[], page: number = 1, perPage: number = 10): any => {
+      const all = posts || [];
+      const pp = Math.max(1, perPage);
+      const pages = Math.max(1, Math.ceil(all.length / pp));
+      const p = Math.min(Math.max(1, page), pages);
+      const start = (p - 1) * pp;
+      return {
+        items: all.slice(start, start + pp),
+        total: all.length,
+        page: p,
+        pages,
+        perPage: pp,
+        hasPrev: p > 1,
+        hasNext: p < pages,
+      };
+    },
+  };
+}