pandorga 1.2.1

data/scripts/test/test-studio-api-contract.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# AC-STU-01, AC-STU-02, AC-STU-09 — API surface contract (static review).
+# Spec: docs/features/studio.md §5
+
+require "pathname"
+
+REPO_ROOT = Pathname.new(__dir__).join("..", "..").expand_path
+
+def check!(condition, message = "condition was false")
+  raise "Assertion failed: #{message}" unless condition
+end
+
+puts "Testing Studio API contract..."
+
+api = REPO_ROOT.join("functions/api/studio/[[path]].js")
+auth = REPO_ROOT.join("functions/api/studio/_lib/auth.js")
+github = REPO_ROOT.join("functions/api/studio/_lib/paths.js")
+gh = REPO_ROOT.join("functions/api/studio/_lib/github.js")
+
+[api, auth, github, gh].each do |path|
+  check!(path.file?, "missing #{path.relative_path_from(REPO_ROOT)}")
+end
+
+api_src = api.read
+auth_src = auth.read
+paths_src = github.read
+gh_src = gh.read
+
+%w[session tree file media search rewrite].each do |route|
+  check!(api_src.include?(route), "API router missing #{route.inspect} route")
+end
+
+check!(api_src.include?("media/folder") || api_src.include?('"folder"'),
+       "API router should expose media folder create")
+check!(api_src.include?("content/media"),
+       "media routes must be scoped under content/media")
+check!(gh_src.include?("putBinaryFile") || api_src.include?("content_base64"),
+       "media upload must accept base64 binary content")
+check!(auth_src.include?("STUDIO_ALLOWLIST"), "auth must read STUDIO_ALLOWLIST")
+check!(auth_src.include?("Bearer"), "auth must expect Bearer JWT")
+check!(gh_src.include?("GITHUB_TOKEN"), "github helper must use GITHUB_TOKEN")
+check!(gh_src.include?("GITHUB_REPO is required") || gh_src.include?("GITHUB_REPO"),
+       "github helper must require GITHUB_REPO")
+owner_repo = %w[alexandre lheinen].join + "/website"
+check!(!gh_src.include?(owner_repo),
+       "github helper must not default GITHUB_REPO to a personal repo")
+check!(api_src.include?("STUDIO_ALLOWED_ORIGINS"),
+       "API CORS must read STUDIO_ALLOWED_ORIGINS")
+owner_slug = %w[alexandre lheinen].join
+check!(!api_src.include?("origin.includes(\"#{owner_slug}\")"),
+       "API CORS must not allow any origin containing the owner slug")
+check!(!api_src.include?('origin.includes("pages.dev")'),
+       "API CORS must not allow any pages.dev project")
+check!(gh_src.include?("api.github.com"), "github helper must call Contents API")
+check!(gh_src.include?('err.code = conflict ? "conflict" : "github_error"') ||
+         gh_src.include?("conflict"),
+       "GitHub 409 must be a conflict, not a bare server_error")
+check!(api_src.include?("err.code || \"server_error\""),
+       "API catch-all must keep a specific error code when the throw set one")
+check!(REPO_ROOT.join("studio-app/src/api/client.js").read.include?("data?.message || data?.error"),
+       "SPA must show the error sentence, not only the error code")
+check!(REPO_ROOT.join("studio-app/src/main.js").read.include?("state.saving"),
+       "Save must ignore a second tap while a save is in flight")
+check!(REPO_ROOT.join("studio-app/src/main.js").read.include?("studio-error-banner"),
+       "Editor must show the failure sentence outside the truncated toolbar pill")
+
+bundles = Dir[REPO_ROOT.join("studio/assets/index-*.js").to_s]
+check!(!bundles.empty?, "committed Studio bundle missing")
+keyed = bundles.any? { |path| File.read(path).match?(/pk_(?:test|live)_[A-Za-z0-9_-]{20,}/) }
+check!(keyed,
+       "committed Studio bundle must include a Clerk publishable key; rebuild with VITE_CLERK_PUBLISHABLE_KEY")
+html = REPO_ROOT.join("studio/index.html").read
+check!(html.match?(%r{/studio/assets/index-[A-Za-z0-9_-]+\.js}),
+       "studio/index.html must point at the built bundle")
+referenced = html[/\/studio\/assets\/(index-[A-Za-z0-9_-]+\.js)/, 1]
+check!(referenced && File.exist?(REPO_ROOT.join("studio/assets", referenced)),
+       "studio/index.html references a missing bundle")
+check!(File.read(REPO_ROOT.join("studio/assets", referenced)).match?(/pk_(?:test|live)_[A-Za-z0-9_-]{20,}/),
+       "the bundle studio/index.html loads must contain the Clerk publishable key")
+check!(paths_src.include?("content/"), "path allowlist must require content/")
+check!(paths_src.include?(".."), "path allowlist must reject ..")
+check!(!api_src.match?(/ghp_[A-Za-z0-9]+/), "no hardcoded PAT in API")
+check!(!gh_src.match?(/ghp_[A-Za-z0-9]+/), "no hardcoded PAT in github helper")
+
+# Rate limit on mutating surface only. GETs (tree prefetch, open, cite
+# search) used to share the Save bucket and the commit returned rate_limited.
+check!(api_src.include?("isMutatingMethod"),
+       "rate limit must apply only to mutating methods")
+check!(api_src.include?("Too many changes in a short time"),
+       "rate_limited must include a sentence, not only the code")
+check!(api_src.include?('error: "rate_limited"'),
+       "API should rate-limit requests")
+check!(!api_src.include?("if (!rateLimit(request, auth.userId))"),
+       "do not rate-limit every authenticated request")
+check!(gh_src.include?("github_rate_limited"),
+       "GitHub 403/429 rate limits need their own sentence")
+
+puts "All Studio API contract checks passed."

data/scripts/test/test-studio-content-files.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# AC-STU: schema file coverage for site-copy paths.
+# Spec: docs/features/studio.md
+
+require "date"
+require "pathname"
+require "yaml"
+
+REPO_ROOT = Pathname.new(__dir__).join("..", "..").expand_path
+CONFIG_PATH = REPO_ROOT.join("studio/schema.yml")
+CONTENT_ROOT = REPO_ROOT.join("content")
+
+def check!(condition, message = "condition was false")
+  raise "Assertion failed: #{message}" unless condition
+end
+
+def each_content_entry(nodes, &block)
+  Array(nodes).each do |entry|
+    next unless entry.is_a?(Hash)
+
+    type = entry["type"].to_s
+    if type == "group"
+      each_content_entry(entry["items"], &block)
+    else
+      yield entry
+    end
+  end
+end
+
+def schema_file_paths(config)
+  paths = []
+  each_content_entry(config["content"]) do |entry|
+    next unless entry["type"].to_s == "file"
+
+    path = entry["path"].to_s
+    paths << path unless path.empty?
+  end
+  paths.sort
+end
+
+def required_cms_paths
+  paths = []
+  pages_root = CONTENT_ROOT.join("pages")
+  if pages_root.directory?
+    pages_root.glob("**/*.{yml,yaml}").sort.each do |data_file|
+      paths << data_file.relative_path_from(REPO_ROOT).to_s.tr("\\", "/")
+    end
+    pages_root.glob("**/*.{md,markdown}").sort.each do |fragment|
+      paths << fragment.relative_path_from(REPO_ROOT).to_s.tr("\\", "/")
+    end
+  end
+
+  data_root = CONTENT_ROOT.join("collections/data")
+  %w[contacts.yml education.yml languages.yml skills.yml].each do |name|
+    path = data_root.join(name)
+    paths << path.relative_path_from(REPO_ROOT).to_s.tr("\\", "/") if path.file?
+  end
+
+  paths.sort.uniq
+end
+
+puts "Testing Studio content file coverage..."
+
+check!(CONFIG_PATH.file?, "missing studio/schema.yml")
+
+config = YAML.safe_load(CONFIG_PATH.read, permitted_classes: [Date, Time], aliases: true) || {}
+registered = schema_file_paths(config)
+required = required_cms_paths
+
+missing = required - registered
+extra = registered - required
+
+check!(missing.empty?,
+       "studio/schema.yml is missing file entries for:\n  #{missing.join("\n  ")}")
+check!(extra.empty?,
+       "studio/schema.yml points at files that are not editorial CMS paths:\n  #{extra.join("\n  ")}")
+
+puts "All Studio content file checks passed (#{required.length} paths)."

data/scripts/test/test-studio-liquid-roundtrip.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * AC-STU-03, AC-STU-04 — Liquid include round-trip without TipTap URL mangling.
+ * Spec: docs/features/studio.md
+ */
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, "../..");
+
+// Import from studio-app source (Node-friendly pure helpers).
+const liquidPath = path.join(root, "studio-app/src/editor/liquid-core.js");
+const { attrsToInclude, parseIncludes, INCLUDE_DEFS, roundTripMarkdown } =
+  await import(liquidPath);
+const { splitDocument, rebuildDocument } = await import(
+  path.join(root, "studio-app/src/lib/document.js")
+);
+
+const remote =
+  'https://vejasp.abril.com.br/wp-content/uploads/2016/11/12209_drone-zangao.jpeg';
+
+const figureDef = INCLUDE_DEFS.find((d) => d.name === "figure");
+const serialized = attrsToInclude(figureDef, {
+  src: remote,
+  caption: "Skydrones Zangão V",
+  width: "100",
+});
+
+assert.match(serialized, /include figure\.html/);
+assert.equal(serialized.includes(`src="${remote}"`), true);
+assert.equal(serialized.includes(`src="[${remote}](${remote})"`), false);
+
+const roundTrip = parseIncludes(serialized);
+assert.equal(roundTrip.length, 1);
+assert.equal(roundTrip[0].type, "include");
+assert.equal(roundTrip[0].attrs.src, remote);
+
+const markdown = [
+  "Intro paragraph.",
+  "",
+  serialized,
+  "",
+  "After.",
+].join("\n");
+
+const segments = parseIncludes(markdown);
+assert.equal(segments.filter((s) => s.type === "include").length, 1);
+assert.equal(segments.find((s) => s.type === "include").attrs.src, remote);
+
+const yt = attrsToInclude(
+  INCLUDE_DEFS.find((d) => d.name === "youtube"),
+  { id: "dQw4w9WgXcQ", caption: "demo", width: "80%" }
+);
+assert.match(yt, /youtube\.html/);
+assert.match(yt, /id="dQw4w9WgXcQ"/);
+assert.match(yt, /width="80%"/);
+
+const ytParsed = parseIncludes(yt);
+assert.equal(ytParsed.length, 1);
+assert.equal(ytParsed[0].type, "include");
+assert.equal(ytParsed[0].attrs.id, "dQw4w9WgXcQ");
+assert.equal(ytParsed[0].attrs.width, "80%");
+
+// Published form: percent width inside quoted attrs must still parse.
+const ytPublished = `{% include youtube.html id="zeJD6dqJ5lo" width="80%" %}`;
+const ytPubSeg = parseIncludes(ytPublished);
+assert.equal(ytPubSeg.length, 1);
+assert.equal(ytPubSeg[0].attrs.id, "zeJD6dqJ5lo");
+assert.equal(ytPubSeg[0].attrs.width, "80%");
+
+// Percent-encoded URLs in attrs must not truncate at `%`.
+const encodedSrc =
+  "https://upload.wikimedia.org/wikipedia/commons/thumb/f/fe/foo%2C_bar.jpg/1280px-foo.jpg";
+const figEncoded = attrsToInclude(figureDef, {
+  src: encodedSrc,
+  caption: "encoded",
+  width: "85",
+});
+const figSeg = parseIncludes(figEncoded);
+assert.equal(figSeg[0].attrs.src, encodedSrc);
+
+const xc = attrsToInclude(INCLUDE_DEFS.find((d) => d.name === "xcite"), {
+  key: "studio-cms",
+});
+assert.match(xc, /xcite\.html/);
+assert.match(xc, /key="studio-cms"/);
+assert.equal(xc.includes("\n"), false);
+
+const figureMany = attrsToInclude(figureDef, {
+  src: "/media/images/website/studio-editor-light.png",
+  alt: "Studio with a sample draft",
+  caption: "A draft open beside its preview.",
+  source: "Author",
+  width: "100",
+});
+assert.equal(
+  figureMany,
+  '{% include figure.html src="/media/images/website/studio-editor-light.png" alt="Studio with a sample draft" caption="A draft open beside its preview." source="Author" width="100" %}'
+);
+
+const inline =
+  'The earlier account, {% include xcite.html key="studio-cms" %}, records that room, and {% include xcite.html key="headless-architecture" %} records how a save reaches the visitor.\n';
+assert.equal(roundTripMarkdown(inline), inline);
+
+const figures = [
+  '{% include figure.html src="/media/images/website/studio-articles-light.png" alt="List" caption="Articles in Studio." source="Author" width="100" %}',
+  "",
+  '{% include figure.html src="/media/images/website/studio-editor-light.png" alt="Editor" caption="A draft open beside its preview." source="Author" width="100" %}',
+  "",
+  "## Beauty in the writing room",
+  "",
+  "I am happy with it again.",
+  "",
+].join("\n");
+assert.equal(roundTripMarkdown(figures), figures);
+
+const keptFigure = `{% include figure.html src="https://decapcms.org/img/screenshot-editor.png" caption="Decap was a proof of concept." source="decapcms.org" width="100" %}`;
+assert.equal(roundTripMarkdown(`${keptFigure}\n`), `${keptFigure}\n`);
+
+const multilineVideo = `{% include video.html
+  src="https://example.com/demo.mp4"
+  caption="A demo."
+  width="80"
+%}`;
+assert.equal(roundTripMarkdown(`${multilineVideo}\n`), `${multilineVideo}\n`);
+
+for (const name of ["youtube", "youtube-short", "video", "plotly", "cut-in", "cite"]) {
+  const def = INCLUDE_DEFS.find((d) => d.include === `${name}.html` || d.include === name);
+  assert.ok(def, name);
+  const attrs = {};
+  for (const field of def.fields) {
+    if (field === "body") continue;
+    attrs[field] = field === "width" ? "80%" : `${field}-value`;
+  }
+  const line = attrsToInclude(def, attrs);
+  assert.equal(line.includes("\n"), false, name);
+  const again = roundTripMarkdown(`${line}\n`);
+  assert.equal(again, `${line}\n`, name);
+}
+
+const original = `---
+layout: article
+title: If you want it done well, do it yourself
+date: 2026-10-02
+description: How the writing room on this site became an editor I built, measured to the includes the pages already use.
+thumbnail: /media/images/website/studio-editor-light.png
+tags:
+  - AI
+  - Aesthetics
+  - DevOps
+language: enus
+mermaid: true
+published: false
+key: if-you-want-it-done-well
+---
+The earlier account, {% include xcite.html key="studio-cms" %}, records that room.
+
+`;
+const split = splitDocument(original);
+assert.deepEqual(split.fm.tags, ["AI", "Aesthetics", "DevOps"]);
+assert.equal(split.fm.title, "If you want it done well, do it yourself");
+const rebuilt = rebuildDocument(original, {
+  fields: { ...split.fm, thumbnail: "" },
+  body: split.body,
+  format: "yaml-frontmatter",
+});
+assert.equal(rebuilt.includes("thumbnail:"), false);
+assert.match(rebuilt, /^title: If you want it done well, do it yourself$/m);
+assert.match(rebuilt, /tags:\n  - AI\n  - Aesthetics\n  - DevOps\n/);
+assert.match(
+  rebuilt,
+  /The earlier account, \{% include xcite\.html key="studio-cms" %\}, records that room\./
+);
+assert.equal(rebuilt.includes('title: "'), false);
+
+console.log("All Studio liquid round-trip checks passed.");

data/scripts/test/test-studio-rate-limit.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Studio save must not share a request budget with reads.
+ * Spec: docs/features/studio.md §4 (mutating-route throttle).
+ */
+import assert from "node:assert/strict";
+import {
+  classifyGithubFailure,
+  isGithubRateLimit,
+} from "../../functions/api/studio/_lib/github.js";
+import {
+  isMutatingMethod,
+  takeToken,
+} from "../../functions/api/studio/_lib/rate-limit.js";
+
+const windowMs = 60_000;
+const max = 3;
+const now = 1_700_000_000_000;
+
+{
+  const store = new Map();
+  for (let i = 0; i < max; i += 1) {
+    const decision = takeToken(store, "user:1.2.3.4", now, { windowMs, max });
+    assert.equal(decision.allowed, true, `write ${i + 1} should be allowed`);
+  }
+  const blocked = takeToken(store, "user:1.2.3.4", now, { windowMs, max });
+  assert.equal(blocked.allowed, false);
+  assert.ok(blocked.retryAfterSec >= 1 && blocked.retryAfterSec <= 60);
+
+  const otherUser = takeToken(store, "other:1.2.3.4", now, { windowMs, max });
+  assert.equal(otherUser.allowed, true, "a different key has its own budget");
+
+  const reset = takeToken(store, "user:1.2.3.4", now + windowMs, { windowMs, max });
+  assert.equal(reset.allowed, true, "the window resets on the boundary");
+}
+
+{
+  assert.equal(isMutatingMethod("PUT"), true);
+  assert.equal(isMutatingMethod("POST"), true);
+  assert.equal(isMutatingMethod("GET"), false);
+  assert.equal(isMutatingMethod("OPTIONS"), false);
+}
+
+{
+  assert.equal(isGithubRateLimit(429, ""), true);
+  assert.equal(
+    isGithubRateLimit(403, "You have exceeded a secondary rate limit."),
+    true
+  );
+  assert.equal(isGithubRateLimit(403, "Resource not accessible by integration"), false);
+  assert.equal(isGithubRateLimit(404, "Not Found"), false);
+
+  const limited = classifyGithubFailure(
+    "put",
+    403,
+    '{"message":"You have exceeded a secondary rate limit."}'
+  );
+  assert.equal(limited.code, "github_rate_limited");
+  assert.equal(limited.status, 429);
+  assert.match(limited.message, /Wait a minute/);
+
+  const conflict = classifyGithubFailure("put", 409, "sha mismatch");
+  assert.equal(conflict.code, "conflict");
+
+  const missing = classifyGithubFailure("get", 404, "Not Found");
+  assert.equal(missing.code, "github_error");
+  assert.match(missing.message, /GitHub get failed \(404\)/);
+}
+
+console.log("All Studio rate-limit checks passed.");

data/scripts/test/test-studio-rewrite-api-contract.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# AC-PRF-01, AC-PRF-02, AC-PRF-04, AC-PRF-12 — rewrite API surface (static).
+# Spec: docs/features/studio-proof.md §11
+
+require "pathname"
+
+REPO_ROOT = Pathname.new(__dir__).join("..", "..").expand_path
+
+def check!(condition, message = "condition was false")
+  raise "Assertion failed: #{message}" unless condition
+end
+
+puts "Testing Studio rewrite API contract..."
+
+api = REPO_ROOT.join("functions/api/studio/[[path]].js")
+rewrite = REPO_ROOT.join("functions/api/studio/_lib/rewrite.js")
+sanitize = REPO_ROOT.join("functions/api/studio/_lib/sanitize.js")
+prompts = REPO_ROOT.join("functions/api/studio/_lib/prompts.js")
+gemini = REPO_ROOT.join("functions/api/studio/_lib/gemini.js")
+guidelines = REPO_ROOT.join("functions/api/studio/_lib/guidelines.js")
+client = REPO_ROOT.join("studio-app/src/api/client.js")
+
+[api, rewrite, sanitize, prompts, gemini, guidelines, client].each do |path|
+  check!(path.file?, "missing #{path.relative_path_from(REPO_ROOT)}")
+end
+
+api_src = api.read
+rewrite_src = rewrite.read
+prompts_src = prompts.read
+client_src = client.read
+
+check!(api_src.include?('"rewrite"') || api_src.include?("head === \"rewrite\""),
+       "API router must expose rewrite")
+check!(api_src.include?("runRewrite"), "API must call runRewrite")
+check!(api_src.include?("rewriteRateLimit"), "dedicated rewrite rate limit")
+check!(!rewrite_src.include?("putFile"), "rewrite must not write GitHub")
+check!(prompts_src.include?("CORRECT_SYSTEM") || prompts_src.include?("mechanical corrector"),
+       "correct prompt present")
+check!(prompts_src.include?("Writing guidelines") || prompts_src.include?("guidelines pack"),
+       "refine prompt embeds guidelines")
+check!(prompts_src.include?("tone consistency") || prompts_src.include?("Preserve tone"),
+       "AC-PRF-17 tone instruction")
+check!(prompts_src.include?("REFINE_SCHEMA") || prompts_src.include?("block"),
+       "refine schema uses block-indexed patches")
+blocks = REPO_ROOT.join("functions/api/studio/_lib/blocks.js")
+check!(blocks.file?, "missing blocks.js chunker")
+check!(rewrite_src.include?("splitIntoBlocks") || rewrite_src.include?("flattenBlockPatches"),
+       "rewrite orchestrates block flatten")
+check!(client_src.include?("rewrite:"), "SPA client exposes rewrite")
+check!(!client_src.match?(/AIza[0-9A-Za-z_-]{10,}/), "no Gemini key in client")
+check!(!api_src.match?(/AIza[0-9A-Za-z_-]{10,}/), "no Gemini key in API router")
+main_spa = REPO_ROOT.join("studio-app/src/main.js")
+check!(main_spa.file?, "missing studio-app main")
+main_src = main_spa.read
+check!(main_src.include?("resolveAiProofTarget") || main_src.include?("wholeBody"),
+       "SPA falls back to full body when selection is empty")
+
+puts "All Studio rewrite API contract checks passed."