pandorga 1.2.1

data/functions/api/studio/_lib/paths.js

@@ -0,0 +1,76 @@
+/**
+ * Studio API path guards. Spec: docs/features/studio.md (AC-STU path allowlist).
+ */
+
+const ALLOWED_PREFIXES = ["content/"];
+
+const BLOCKED_SEGMENTS = new Set([
+  ".git",
+  ".github",
+  "_plugins",
+  "node_modules",
+  "studio-app",
+  "functions",
+  ".env",
+  "secrets",
+]);
+
+export function normalizeRepoPath(raw) {
+  const path = String(raw || "")
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+/g, "/");
+  if (!path || path.includes("\0")) return null;
+  if (path.split("/").some((seg) => seg === ".." || BLOCKED_SEGMENTS.has(seg))) {
+    return null;
+  }
+  if (!ALLOWED_PREFIXES.some((prefix) => path === prefix.slice(0, -1) || path.startsWith(prefix))) {
+    return null;
+  }
+  return path;
+}
+
+export function collectionDir(name, schema) {
+  const found = findEntry(schema?.content, name);
+  return found?.path || null;
+}
+
+function findEntry(nodes, name) {
+  for (const entry of nodes || []) {
+    if (!entry || typeof entry !== "object") continue;
+    if (entry.type === "group") {
+      const nested = findEntry(entry.items, name);
+      if (nested) return nested;
+    } else if (entry.name === name) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+export function listSchemaCollections(schema) {
+  const out = [];
+  walk(schema?.content, out);
+  return out;
+}
+
+function walk(nodes, out) {
+  for (const entry of nodes || []) {
+    if (!entry || typeof entry !== "object") continue;
+    if (entry.type === "group") {
+      walk(entry.items, out);
+    } else if (entry.type === "collection" || entry.type === "file") {
+      out.push({
+        name: entry.name,
+        label: entry.label || entry.name,
+        type: entry.type,
+        path: entry.path,
+        format: entry.format || "yaml-frontmatter",
+        filename: entry.filename,
+        fields: entry.fields || [],
+        view: entry.view || {},
+        operations: entry.operations || {},
+      });
+    }
+  }
+}

data/functions/api/studio/_lib/prompts.js

@@ -0,0 +1,165 @@
+/**
+ * Gemini prompt builders for Studio Correct / Refine.
+ * Spec: docs/features/studio-proof.md §8 (AC-PRF-11, AC-PRF-15, AC-PRF-17).
+ */
+
+import { formatBlocksForPrompt } from "./blocks.js";
+
+const CORRECT_SCHEMA = {
+  type: "object",
+  properties: {
+    patches: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["start", "end", "original", "replacement", "category", "reason"],
+        properties: {
+          start: { type: "integer" },
+          end: { type: "integer" },
+          original: { type: "string" },
+          replacement: { type: "string" },
+          category: { type: "string" },
+          reason: { type: "string" },
+        },
+      },
+    },
+  },
+  required: ["patches"],
+};
+
+const REFINE_SCHEMA = {
+  type: "object",
+  properties: {
+    patches: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["block", "original", "replacement", "category", "reason"],
+        properties: {
+          block: { type: "integer" },
+          original: { type: "string" },
+          replacement: { type: "string" },
+          category: { type: "string" },
+          reason: { type: "string" },
+        },
+      },
+    },
+  },
+  required: ["patches"],
+};
+
+const CORRECT_SYSTEM = `You are a mechanical corrector for a personal site CMS. You are not a co-author and not a stylist.
+
+Language: all judgments use the language code from the user message (from the entry front matter). Spelling and idiom follow that language's norms.
+
+Allowed patch categories only: spelling, typo, grammar, punctuation, idiom. If unsure whether a change is required for correctness, omit it.
+
+Hard bans:
+- Do not improve rhythm, voice, imagery, or “style”.
+- Do not change meaning, add or remove ideas, or reorder paragraphs.
+- Do not edit Liquid {% … %} tags (include, cite, or any other) or their attributes.
+- Do not touch fenced code blocks or inline \`code\`.
+- Do not translate into another language.
+- Do not invent citations, links, or facts.
+
+Offsets start/end are JavaScript string indices (UTF-16 code units) into the exact text field. original must equal text.slice(start, end). Prefer the smallest edit that makes the sentence correct.
+
+Emit JSON only matching the schema. No prose outside JSON.`;
+
+function refineSystem(guidelinesBody) {
+  const pack = String(guidelinesBody || "").trim();
+  return `You are an editorial refiner for a personal site CMS under the owner's writing law. The user invoked Refine on purpose: improve fluidity, clarity, correctness, and prose quality inside the submitted blocks. You are not a co-author: do not change stance, invent structure, headings hierarchy, or claims.
+
+Preserve tone consistency with the submitted text and with any provided article context (before/after). Stay in the language code from the user message.
+
+Allowed patch categories: clarity, flow, prose, grammar, punctuation, spelling, typo, idiom.
+
+When to patch:
+- For each prose block, look for sentences that can be tightened, clarified, or made to flow better without changing meaning.
+- Prefer one local edit per issue (a clause or a sentence). original must be an exact substring of that block.
+- Skip heading-only blocks, blocks that are only Liquid/HTML, and figure/include-only blocks.
+- Empty patches only when every prose block is already tight under the guidelines. Do not return an empty list just because the prose is already good if a clearer local wording exists.
+
+Hard bans:
+- Do not edit Liquid {% … %} tags (include, cite, or any other) or code fences / inline code. Leave those substrings untouched inside original/replacement.
+- Do not translate.
+- Do not homogenize into generic AI-essay voice, mic-drop closers, or banned patterns from the guidelines.
+- Do not leak private repository paths or internal tooling into the prose.
+- Do not replace an entire long paragraph in one patch; keep each replacement short and local.
+
+Each patch must set block to the integer index shown as [n] in the user message.
+
+Writing guidelines (published pack):
+<<<
+${pack}
+>>>
+
+Emit JSON only matching the schema. No prose outside JSON.`;
+}
+
+/**
+ * Prefer Fundamental + Cadence/Typography + site overlay if over budget.
+ * @param {string} body
+ * @param {number} maxChars
+ */
+export function truncateGuidelines(body, maxChars = 48_000) {
+  const text = String(body || "");
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n\n[guidelines truncated for context budget]\n`;
+}
+
+/**
+ * @param {object} opts
+ * @param {"correct"|"refine"} opts.mode
+ * @param {string} opts.language
+ * @param {string} opts.path
+ * @param {string} opts.text
+ * @param {{ before?: string, after?: string } | null} [opts.context]
+ * @param {string} [opts.guidelinesBody]
+ * @param {{ index: number, text: string }[] | null} [opts.blocks]
+ */
+export function buildGeminiRequest({
+  mode,
+  language,
+  path,
+  text,
+  context = null,
+  guidelinesBody = "",
+  blocks = null,
+}) {
+  const system =
+    mode === "refine"
+      ? refineSystem(truncateGuidelines(guidelinesBody))
+      : CORRECT_SYSTEM;
+
+  const parts = [
+    `mode: ${mode}`,
+    `language: ${language}`,
+    `path: ${path || ""}`,
+  ];
+  if (mode === "refine" && context?.before) {
+    parts.push("context.before:", "<<<", String(context.before), ">>>");
+  }
+  if (mode === "refine" && Array.isArray(blocks) && blocks.length) {
+    parts.push(formatBlocksForPrompt(blocks));
+  } else {
+    parts.push("text:", "<<<", String(text ?? ""), ">>>");
+  }
+  if (mode === "refine" && context?.after) {
+    parts.push("context.after:", "<<<", String(context.after), ">>>");
+  }
+
+  return {
+    systemInstruction: { parts: [{ text: system }] },
+    contents: [{ role: "user", parts: [{ text: parts.join("\n") }] }],
+    generationConfig: {
+      temperature: mode === "refine" ? 0.35 : 0,
+      responseMimeType: "application/json",
+      responseSchema: mode === "refine" ? REFINE_SCHEMA : CORRECT_SCHEMA,
+    },
+  };
+}
+
+export { CORRECT_SCHEMA, REFINE_SCHEMA, CORRECT_SYSTEM };
+/** @deprecated use CORRECT_SCHEMA — kept for static contract greps */
+export const RESPONSE_SCHEMA = CORRECT_SCHEMA;

data/functions/api/studio/_lib/rate-limit.js

@@ -0,0 +1,40 @@
+/**
+ * Fixed-window request budget for Studio mutating routes.
+ * Spec: docs/features/studio.md §4 — throttle writes, not reads.
+ */
+
+/**
+ * @param {Map<string, {start: number, count: number}>} store
+ * @param {string} key
+ * @param {number} now
+ * @param {{ windowMs: number, max: number }} limits
+ * @returns {{ allowed: boolean, retryAfterSec: number }}
+ */
+export function takeToken(store, key, now, limits) {
+  const windowMs = limits.windowMs;
+  const max = limits.max;
+  let bucket = store.get(key);
+  if (!bucket || now < bucket.start || now - bucket.start >= windowMs) {
+    bucket = { start: now, count: 0 };
+    store.set(key, bucket);
+  }
+  bucket.count += 1;
+  if (bucket.count <= max) {
+    return { allowed: true, retryAfterSec: 0 };
+  }
+  const retryAfterSec = Math.max(
+    1,
+    Math.ceil((bucket.start + windowMs - now) / 1000)
+  );
+  return { allowed: false, retryAfterSec };
+}
+
+/** PUT/POST/PATCH/DELETE. GET (tree, file, search, session) must not spend this. */
+export function isMutatingMethod(method) {
+  const verb = String(method || "").toUpperCase();
+  return verb === "POST" || verb === "PUT" || verb === "PATCH" || verb === "DELETE";
+}
+
+export function clientAddress(request) {
+  return request.headers.get("CF-Connecting-IP") || "unknown";
+}

data/functions/api/studio/_lib/rewrite.js

@@ -0,0 +1,136 @@
+/**
+ * Studio rewrite orchestration (Correct / Refine).
+ * Spec: docs/features/studio-proof.md §7.
+ */
+
+import { flattenBlockPatches, splitIntoBlocks } from "./blocks.js";
+import { buildGeminiRequest } from "./prompts.js";
+import { callGemini } from "./gemini.js";
+import { loadGuidelinesPack } from "./guidelines.js";
+import { clientAddress, takeToken } from "./rate-limit.js";
+import { sanitizePatches } from "./sanitize.js";
+
+const MAX_TEXT = 100_000;
+const MAX_CONTEXT = 2_000;
+const REWRITE_RATE = new Map();
+const REWRITE_WINDOW_MS = 60_000;
+const REWRITE_MAX = 5;
+/** Allow more local patches when refining a long multi-block selection. */
+const REFINE_MAX_PATCHES = 60;
+
+/**
+ * @param {Request} request
+ * @param {string} userId
+ * @returns {{ allowed: boolean, retryAfterSec: number }}
+ */
+export function rewriteRateLimit(request, userId) {
+  return takeToken(
+    REWRITE_RATE,
+    `rewrite:${userId}:${clientAddress(request)}`,
+    Date.now(),
+    { windowMs: REWRITE_WINDOW_MS, max: REWRITE_MAX }
+  );
+}
+
+/**
+ * @param {object} env
+ * @param {object} body — parsed JSON body
+ */
+export async function runRewrite(env, body) {
+  const mode = String(body?.mode || "").toLowerCase();
+  if (mode !== "correct" && mode !== "refine") {
+    const err = new Error("invalid_body");
+    err.code = "invalid_body";
+    err.status = 400;
+    throw err;
+  }
+
+  const language = String(body?.language || "").trim();
+  if (!language) {
+    const err = new Error("language_required");
+    err.code = "language_required";
+    err.status = 400;
+    throw err;
+  }
+
+  const text = String(body?.text ?? "");
+  if (!text) {
+    const err = new Error("invalid_body");
+    err.code = "invalid_body";
+    err.status = 400;
+    throw err;
+  }
+  if (text.length > MAX_TEXT) {
+    const err = new Error("invalid_body");
+    err.code = "invalid_body";
+    err.status = 400;
+    throw err;
+  }
+
+  const path = String(body?.path || "");
+  // Spec: when selection is present, `text` is already the slice; offsets are
+  // relative to that slice. SPA applies against the same `text` it sent.
+  const workText = text;
+
+  let context = null;
+  if (mode === "refine" && body?.context && typeof body.context === "object") {
+    context = {
+      before: String(body.context.before || "").slice(-MAX_CONTEXT),
+      after: String(body.context.after || "").slice(0, MAX_CONTEXT),
+    };
+  }
+
+  let guidelinesVersion = null;
+  let guidelinesBody = "";
+  if (mode === "refine") {
+    const pack = await loadGuidelinesPack(env);
+    guidelinesBody = pack.body_markdown;
+    guidelinesVersion = pack.body_sha256;
+  }
+
+  const blocks = mode === "refine" ? splitIntoBlocks(workText) : null;
+
+  const geminiBody = buildGeminiRequest({
+    mode,
+    language,
+    path,
+    text: workText,
+    context,
+    guidelinesBody,
+    blocks,
+  });
+
+  let gemini;
+  try {
+    gemini = await callGemini(env, geminiBody);
+  } catch (err) {
+    if (err.code === "gemini_unconfigured") {
+      err.status = 503;
+      err.code = "gemini_upstream";
+    } else if (!err.status) {
+      err.status = 502;
+      err.code = err.code || "gemini_upstream";
+    }
+    throw err;
+  }
+
+  const rawPatches =
+    mode === "refine"
+      ? flattenBlockPatches(blocks, gemini.patches)
+      : gemini.patches;
+
+  const { patches, stats } = sanitizePatches({
+    mode,
+    text: workText,
+    patches: rawPatches,
+    maxPatches: mode === "refine" ? REFINE_MAX_PATCHES : 40,
+  });
+
+  return {
+    mode,
+    guidelines_version: guidelinesVersion,
+    model: gemini.model,
+    patches,
+    stats,
+  };
+}

data/functions/api/studio/_lib/sanitize.js

@@ -0,0 +1,143 @@
+/**
+ * Patch sanitizer for Studio Correct / Refine.
+ * Spec: docs/features/studio-proof.md §3, §8 (AC-PRF-05–07).
+ */
+
+import { locateUnique } from "./blocks.js";
+
+export const CORRECT_CATEGORIES = new Set([
+  "spelling",
+  "typo",
+  "grammar",
+  "punctuation",
+  "idiom",
+]);
+
+export const REFINE_CATEGORIES = new Set([
+  "spelling",
+  "typo",
+  "grammar",
+  "punctuation",
+  "idiom",
+  "clarity",
+  "flow",
+  "prose",
+]);
+
+/** Any Liquid tag — include, cite, etc. */
+const LIQUID_RE = /\{%[\s\S]*?%\}/g;
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`\n]+`/g;
+
+/** @param {string} text */
+export function protectedRanges(text) {
+  const ranges = [];
+  const pushAll = (re) => {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      ranges.push({ start: m.index, end: m.index + m[0].length });
+    }
+  };
+  pushAll(LIQUID_RE);
+  pushAll(FENCE_RE);
+  pushAll(INLINE_CODE_RE);
+  return ranges;
+}
+
+function overlapsProtected(start, end, ranges) {
+  return ranges.some((r) => start < r.end && end > r.start);
+}
+
+/**
+ * @param {object} opts
+ * @param {"correct"|"refine"} opts.mode
+ * @param {string} opts.text
+ * @param {unknown[]} opts.patches
+ * @param {number} [opts.maxPatches]
+ * @param {number} [opts.maxReplacement]
+ * @returns {{ patches: object[], stats: { proposed: number, kept: number, dropped: number } }}
+ */
+export function sanitizePatches({
+  mode,
+  text,
+  patches,
+  maxPatches = 40,
+  maxReplacement = mode === "refine" ? 500 : 200,
+}) {
+  const allowed = mode === "refine" ? REFINE_CATEGORIES : CORRECT_CATEGORIES;
+  const protected_ = protectedRanges(text || "");
+  const src = typeof text === "string" ? text : "";
+  const list = Array.isArray(patches) ? patches : [];
+  const out = [];
+  const seen = [];
+
+  for (const raw of list) {
+    if (!raw || typeof raw !== "object") continue;
+
+    const original = String(raw.original ?? "");
+    const replacement = String(raw.replacement ?? "");
+    const category = String(raw.category || "").toLowerCase();
+    const reason = String(raw.reason || "").slice(0, 160);
+
+    if (!allowed.has(category)) continue;
+    if (!original || replacement === original) continue;
+    if (replacement.length > maxReplacement) continue;
+    if (replacement.length === 0 && original.length > 8) continue;
+
+    let start = Number(raw.start);
+    let end = Number(raw.end);
+    if (
+      !Number.isInteger(start) ||
+      !Number.isInteger(end) ||
+      start < 0 ||
+      end < start ||
+      end > src.length ||
+      src.slice(start, end) !== original
+    ) {
+      const hint = Number.isInteger(start) ? start : 0;
+      const loc = locateUnique(src, original, hint);
+      if (!loc) continue;
+      start = loc.start;
+      end = loc.end;
+    }
+
+    if (overlapsProtected(start, end, protected_)) continue;
+    if (seen.some((r) => start < r.end && end > r.start)) continue;
+
+    seen.push({ start, end });
+    out.push({
+      start,
+      end,
+      original,
+      replacement,
+      category,
+      reason,
+    });
+    if (out.length >= maxPatches) break;
+  }
+
+  out.sort((a, b) => a.start - b.start);
+  return {
+    patches: out,
+    stats: {
+      proposed: list.length,
+      kept: out.length,
+      dropped: Math.max(0, list.length - out.length),
+    },
+  };
+}
+
+/**
+ * Remap selection-relative patches onto full-body offsets.
+ * @param {unknown[]} patches
+ * @param {number} base
+ */
+export function remapPatchOffsets(patches, base) {
+  const b = Number(base) || 0;
+  return (Array.isArray(patches) ? patches : []).map((p) => ({
+    ...p,
+    start: Number(p.start) + b,
+    end: Number(p.end) + b,
+  }));
+}

data/lib/pandorga/cli.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "commands/doctor"
+require_relative "commands/export"
+require_relative "commands/serve"
+require_relative "commands/publish"
+require_relative "commands/install_functions"
+require_relative "commands/studio_schema"
+require_relative "commands/new"
+
+module Pandorga
+  # Dispatch for `exe/pandorga`.
+  module CLI
+    COMMANDS = {
+      "new" => Commands::New,
+      "doctor" => Commands::Doctor,
+      "export" => Commands::Export,
+      "serve" => Commands::Serve,
+      "publish" => Commands::Publish,
+      "install-functions" => Commands::InstallFunctions,
+      "studio-schema" => Commands::StudioSchema
+    }.freeze
+
+    module_function
+
+    def run(argv)
+      command = argv.shift
+      if command.nil? || %w[-h --help help].include?(command)
+        print_help
+        return 0
+      end
+      if %w[-v --version].include?(command)
+        puts "pandorga #{Pandorga::VERSION}"
+        return 0
+      end
+
+      klass = COMMANDS[command]
+      unless klass
+        warn "Unknown command: #{command}"
+        print_help
+        return 1
+      end
+
+      klass.new.run(argv)
+    end
+
+    def print_help
+      puts <<~HELP
+        pandorga #{Pandorga::VERSION} — static shell + JSON content platform
+
+        Usage:
+          pandorga new PATH               Scaffold a site from the minimal example
+          pandorga doctor                 Check site config and environment
+          pandorga export [src] [dest]    Export content collections to JSON
+          pandorga serve                  Local Jekyll serve with JSON re-export
+          pandorga publish                Sync content JSON to R2
+          pandorga install-functions      Copy functions/ and studio/ into site root
+          pandorga studio-schema          Compose studio/schema.yml from templates
+
+        Options:
+          -h, --help      Show this help
+          -v, --version   Show version
+      HELP
+    end
+  end
+end

data/lib/pandorga/commands/doctor.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+require "date"
+
+module Pandorga
+  module Commands
+    # Sanity-check a site directory for pandorga configuration.
+    class Doctor
+      def run(argv)
+        root = Pathname.new(argv[0] || Dir.pwd).expand_path
+        errors = []
+        warnings = []
+
+        config_path = root.join("_config.yml")
+        unless config_path.file?
+          warn "error: no _config.yml in #{root}"
+          return 1
+        end
+
+        config = YAML.safe_load(config_path.read, permitted_classes: [Date]) || {}
+        pandorga = config["pandorga"]
+        unless pandorga.is_a?(Hash)
+          errors << "missing top-level `pandorga:` key (identity, content, pages)"
+        else
+          identity = pandorga["identity"]
+          if !identity.is_a?(Hash) || identity["name"].to_s.strip.empty?
+            errors << "pandorga.identity.name is required"
+          end
+          pages = pandorga["pages"]
+          if pages.nil?
+            warnings << "pandorga.pages is empty — no pages will be generated"
+          elsif !pages.is_a?(Array)
+            errors << "pandorga.pages must be an array"
+          else
+            keys = pages.map { |p| p.is_a?(Hash) ? p["key"] : nil }
+            dup = keys.compact.group_by(&:itself).select { |_, v| v.size > 1 }.keys
+            errors << "duplicate page keys: #{dup.join(', ')}" if dup.any?
+            pages.each_with_index do |page, i|
+              next unless page.is_a?(Hash)
+
+              errors << "pages[#{i}]: missing key" if page["key"].to_s.empty?
+              errors << "pages[#{i}] (#{page['key']}): missing template" if page["template"].to_s.empty?
+            end
+          end
+        end
+
+        gemfile = root.join("Gemfile")
+        warnings << "Gemfile does not mention pandorga" if gemfile.file? && !gemfile.read.include?("pandorga")
+
+        if errors.empty? && warnings.empty?
+          puts "pandorga doctor: ok (#{root})"
+          return 0
+        end
+
+        warnings.each { |w| warn "warning: #{w}" }
+        errors.each { |e| warn "error: #{e}" }
+        return 1 if errors.any?
+
+        puts "pandorga doctor: ok with warnings (#{root})"
+        0
+      end
+    end
+  end
+end