@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/xlsx/scripts/recalc.py

@@ -0,0 +1,184 @@
+"""
+Excel Formula Recalculation Script
+Recalculates all formulas in an Excel file using LibreOffice
+"""
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+
+from office.soffice import get_soffice_env
+
+from openpyxl import load_workbook
+
+MACRO_DIR_MACOS = "~/Library/Application Support/LibreOffice/4/user/basic/Standard"
+MACRO_DIR_LINUX = "~/.config/libreoffice/4/user/basic/Standard"
+MACRO_FILENAME = "Module1.xba"
+
+RECALCULATE_MACRO = """<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">
+<script:module xmlns:script="http://openoffice.org/2000/script" script:name="Module1" script:language="StarBasic">
+    Sub RecalculateAndSave()
+      ThisComponent.calculateAll()
+      ThisComponent.store()
+      ThisComponent.close(True)
+    End Sub
+</script:module>"""
+
+
+def has_gtimeout():
+    try:
+        subprocess.run(
+            ["gtimeout", "--version"], capture_output=True, timeout=1, check=False
+        )
+        return True
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def setup_libreoffice_macro():
+    macro_dir = os.path.expanduser(
+        MACRO_DIR_MACOS if platform.system() == "Darwin" else MACRO_DIR_LINUX
+    )
+    macro_file = os.path.join(macro_dir, MACRO_FILENAME)
+
+    if (
+        os.path.exists(macro_file)
+        and "RecalculateAndSave" in Path(macro_file).read_text()
+    ):
+        return True
+
+    if not os.path.exists(macro_dir):
+        subprocess.run(
+            ["soffice", "--headless", "--terminate_after_init"],
+            capture_output=True,
+            timeout=10,
+            env=get_soffice_env(),
+        )
+        os.makedirs(macro_dir, exist_ok=True)
+
+    try:
+        Path(macro_file).write_text(RECALCULATE_MACRO)
+        return True
+    except Exception:
+        return False
+
+
+def recalc(filename, timeout=30):
+    if not Path(filename).exists():
+        return {"error": f"File {filename} does not exist"}
+
+    abs_path = str(Path(filename).absolute())
+
+    if not setup_libreoffice_macro():
+        return {"error": "Failed to setup LibreOffice macro"}
+
+    cmd = [
+        "soffice",
+        "--headless",
+        "--norestore",
+        "vnd.sun.star.script:Standard.Module1.RecalculateAndSave?language=Basic&location=application",
+        abs_path,
+    ]
+
+    if platform.system() == "Linux":
+        cmd = ["timeout", str(timeout)] + cmd
+    elif platform.system() == "Darwin" and has_gtimeout():
+        cmd = ["gtimeout", str(timeout)] + cmd
+
+    result = subprocess.run(cmd, capture_output=True, text=True, env=get_soffice_env())
+
+    if result.returncode != 0 and result.returncode != 124:  
+        error_msg = result.stderr or "Unknown error during recalculation"
+        if "Module1" in error_msg or "RecalculateAndSave" not in error_msg:
+            return {"error": "LibreOffice macro not configured properly"}
+        return {"error": error_msg}
+
+    try:
+        wb = load_workbook(filename, data_only=True)
+
+        excel_errors = [
+            "#VALUE!",
+            "#DIV/0!",
+            "#REF!",
+            "#NAME?",
+            "#NULL!",
+            "#NUM!",
+            "#N/A",
+        ]
+        error_details = {err: [] for err in excel_errors}
+        total_errors = 0
+
+        for sheet_name in wb.sheetnames:
+            ws = wb[sheet_name]
+            for row in ws.iter_rows():
+                for cell in row:
+                    if cell.value is not None and isinstance(cell.value, str):
+                        for err in excel_errors:
+                            if err in cell.value:
+                                location = f"{sheet_name}!{cell.coordinate}"
+                                error_details[err].append(location)
+                                total_errors += 1
+                                break
+
+        wb.close()
+
+        result = {
+            "status": "success" if total_errors == 0 else "errors_found",
+            "total_errors": total_errors,
+            "error_summary": {},
+        }
+
+        for err_type, locations in error_details.items():
+            if locations:
+                result["error_summary"][err_type] = {
+                    "count": len(locations),
+                    "locations": locations[:20],  
+                }
+
+        wb_formulas = load_workbook(filename, data_only=False)
+        formula_count = 0
+        for sheet_name in wb_formulas.sheetnames:
+            ws = wb_formulas[sheet_name]
+            for row in ws.iter_rows():
+                for cell in row:
+                    if (
+                        cell.value
+                        and isinstance(cell.value, str)
+                        and cell.value.startswith("=")
+                    ):
+                        formula_count += 1
+        wb_formulas.close()
+
+        result["total_formulas"] = formula_count
+
+        return result
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python recalc.py <excel_file> [timeout_seconds]")
+        print("\nRecalculates all formulas in an Excel file using LibreOffice")
+        print("\nReturns JSON with error details:")
+        print("  - status: 'success' or 'errors_found'")
+        print("  - total_errors: Total number of Excel errors found")
+        print("  - total_formulas: Number of formulas in the file")
+        print("  - error_summary: Breakdown by error type with locations")
+        print("    - #VALUE!, #DIV/0!, #REF!, #NAME?, #NULL!, #NUM!, #N/A")
+        sys.exit(1)
+
+    filename = sys.argv[1]
+    timeout = int(sys.argv[2]) if len(sys.argv) > 2 else 30
+
+    result = recalc(filename, timeout)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/.merlin-core/skills/general/xlsx/scripts/styled-report.js

@@ -0,0 +1,130 @@
+/**
+ * styled-report.js — reusable helpers for Node/SheetJS styled operational reports.
+ *
+ * Requires `xlsx-js-style` (the community `xlsx` build CANNOT write cell styles).
+ *   npm install xlsx-js-style
+ *
+ * See ../references/nodejs-sheetjs-styled-reports.md for the full guide.
+ *
+ * Usage:
+ *   const XLSX = require('xlsx-js-style');
+ *   const R = require('<skill>/scripts/styled-report');
+ *   const data = [], painter = R.makePainter(data);
+ *   painter.title('CONCLUÍDAS (12)', R.PALETTE.greenTitle);
+ *   painter.headerRow(['#', 'Título', 'Data'], R.PALETTE.green);
+ *   data.push(['#1', 'Foo', '01/05/2026']);
+ *   const ws = XLSX.utils.aoa_to_sheet(data);
+ *   R.applyPaints(XLSX, ws, painter.paints);
+ *   // ... book_append_sheet + writeFile ...
+ *   R.toCsvWithBom('out.csv', ['A','B'], rows);   // CSV with BOM + quoting
+ */
+
+/** Build a style object (write shape). rgb is 'RRGGBB' with no '#'. */
+function mkStyle(
+  rgb,
+  { sz = 11, color = "FFFFFF", bold = true, align = "center" } = {},
+) {
+  return {
+    fill: { patternType: "solid", fgColor: { rgb } },
+    font: { bold, color: { rgb: color }, sz },
+    alignment: { vertical: align, wrapText: false },
+  };
+}
+
+/** Conventional palette: green=done, blue=open, gray=cancelled/neutral, slate=sub-headers. */
+const PALETTE = {
+  greenTitle: mkStyle("1B5E20", { sz: 12 }),
+  green: mkStyle("2E7D32"),
+  blueTitle: mkStyle("0D47A1", { sz: 12 }),
+  blue: mkStyle("1565C0"),
+  grayTitle: mkStyle("455A64", { sz: 12 }),
+  gray: mkStyle("78909C"),
+  slate: mkStyle("37474F"),
+  info: { font: { bold: true, sz: 12 } },
+};
+
+/**
+ * A painter bound to a `data` array (array-of-arrays). Record cells to style as you
+ * push rows; the recorded (row,col,style) entries are applied later via applyPaints.
+ */
+function makePainter(data) {
+  const paints = [];
+  return {
+    paints,
+    /** Push a single-cell title row and paint cell (row, col 0). */
+    title(text, style) {
+      data.push([text]);
+      paints.push({ r: data.length - 1, c: 0, style });
+      return this;
+    },
+    /** Push a header row and paint all its columns. */
+    headerRow(cols, style) {
+      data.push(cols);
+      for (let c = 0; c < cols.length; c++)
+        paints.push({ r: data.length - 1, c, style });
+      return this;
+    },
+    /** Paint an arbitrary already-pushed row range. */
+    paintRow(rowIdx, nCols, style) {
+      for (let c = 0; c < nCols; c++) paints.push({ r: rowIdx, c, style });
+      return this;
+    },
+  };
+}
+
+/** Apply recorded paints to a worksheet (creates empty cells so fills render). */
+function applyPaints(XLSX, ws, paints) {
+  for (const p of paints) {
+    const ref = XLSX.utils.encode_cell({ r: p.r, c: p.c });
+    if (!ws[ref]) ws[ref] = { t: "s", v: "" };
+    ws[ref].s = p.style;
+  }
+  return ws;
+}
+
+/** Serialize rows to a CSV string with UTF-8 BOM + RFC-4180 quoting (opens cleanly in Excel). */
+function csvString(headers, rows) {
+  const esc = (c) => `"${String(c).replace(/"/g, '""')}"`;
+  return (
+    "" +
+    [headers.join(","), ...rows.map((r) => r.map(esc).join(","))].join("\n")
+  );
+}
+
+/** Write a CSV file with BOM + quoting. */
+function toCsvWithBom(filePath, headers, rows) {
+  require("fs").writeFileSync(filePath, csvString(headers, rows), "utf8");
+  return filePath;
+}
+
+/** Coerce a Firestore/admin Timestamp (or Date / {_seconds}) to a JS Date, else null. */
+function toDate(field) {
+  if (!field) return null;
+  if (field instanceof Date) return field;
+  if (typeof field.toDate === "function") return field.toDate();
+  if (field._seconds !== undefined) return new Date(field._seconds * 1000);
+  return null;
+}
+
+/** Timezone-correct {year,month,day} in a given IANA zone (default America/Sao_Paulo). */
+function spParts(date, timeZone = "America/Sao_Paulo") {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(date);
+  const get = (t) => parts.find((p) => p.type === t).value;
+  return { year: +get("year"), month: +get("month"), day: +get("day") };
+}
+
+module.exports = {
+  mkStyle,
+  PALETTE,
+  makePainter,
+  applyPaints,
+  csvString,
+  toCsvWithBom,
+  toDate,
+  spParts,
+};

package/.merlin-core/skills/general/yolo-mode/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: yolo-mode
+description: Autonomous execution mode that auto-approves LOW and MEDIUM actions
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [yolo, autonomous, auto-approve, unattended, batch-mode]
+---
+
+# YOLO Mode
+
+Autonomous execution mode that auto-approves LOW and MEDIUM stake actions, enabling unattended batch processing. HIGH stake actions always require human approval per Constitution Article VII.
+
+## What YOLO Enables
+
+When YOLO mode is ON:
+
+- **LOW actions** (commit, file changes, tests): Auto-approved (same as normal)
+- **MEDIUM actions** (push, PR, package install): Auto-approved instead of waiting for confirmation
+- **HIGH actions** (production deploy, force push): Still require explicit human approval
+
+## What YOLO Does NOT Change
+
+- HIGH stake actions are NEVER auto-approved — this is a constitutional invariant
+- Quality gates still run — YOLO doesn't skip tests or reviews
+- Audit logging continues — all auto-approved actions are logged
+
+## How to Toggle
+
+```bash
+# Check current state
+node .merlin-core/tools/merlin-tools.js yolo
+
+# Enable
+node .merlin-core/tools/merlin-tools.js yolo on
+
+# Disable
+node .merlin-core/tools/merlin-tools.js yolo off
+```
+
+Or via slash command: `/yolo on` | `/yolo off`
+
+## State Storage
+
+YOLO mode state is stored in `.merlin/context-bridge.json` as `yolo_mode: true|false`. This persists across sessions but is gitignored.
+
+## When to Use
+
+- Batch processing multiple tasks unattended
+- CI/CD pipeline integration
+- Rapid prototyping sessions where interruptions slow flow
+- Overnight batch builds
+
+## Risks
+
+- MEDIUM actions (push, PR creation) happen without confirmation
+- Package installs happen without review
+- Config changes to project settings happen without confirmation
+- Always disable YOLO mode when working on production-facing changes

package/.merlin-core/skills/general/youtube-transcript/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: youtube-transcript
+description: >
+  Extract the full timestamped transcript of ANY YouTube video — including unlisted videos and
+  videos with captions disabled. Use this skill WHENEVER you need the spoken content of a YouTube
+  video: to study/summarize it, build chapters, search it, or feed it to an LLM. Handles the
+  three things that break naïve yt-dlp attempts: the "This video is not available" anti-bot block
+  (fixed with player_client=android), the unlisted-vs-private confusion, and videos with NO captions
+  at all (fixed by downloading the audio and transcribing via Gladia). Returns clean
+  {text, start, duration} segments.
+license: MIT (Merlin)
+compatibility: claude-code
+metadata:
+  author: Merlin (from a real course-transcription build, 2026-06-01)
+  version: "1.0"
+  auto_activate:
+    [youtube, youtube-transcript, transcript, legenda, yt-dlp, gladia]
+  allowed_tools: [Bash, Read, Write]
+---
+
+# YouTube Transcript — Extracting Spoken Content from Any Video
+
+A naïve `yt-dlp <url>` or `youtube_transcript_api.get_transcript(id)` fails on real-world videos in
+three predictable ways. This skill encodes the working escalation so you never re-discover them.
+
+> Born from a real build: a 12-video sales course (unlisted). 11/12 came through
+> `youtube-transcript-api` instantly; the 12th had captions fully disabled
+> and was recovered by downloading the audio and sending it to Gladia (2796 segments in 115s).
+
+---
+
+## STEP 0 — Decide the goal & check prerequisites
+
+You need the **spoken content with timestamps**. Confirm:
+
+1. **Dependencies present?** `yt-dlp` (CLI or `python -m yt_dlp`) + `youtube-transcript-api`
+   (`pip install yt-dlp youtube-transcript-api`). For the Gladia fallback: Node + a `GLADIA_API_KEY`.
+2. **Where are you running?**
+   - **Residential/local IP** (a dev's machine) → `youtube-transcript-api` works **without a proxy**.
+   - **Datacenter IP** (Cloud Function, VPS, CI) → YouTube blocks it; you need a **residential proxy**
+     (a residential proxy provider: `http://USER:PASS@<proxy-host>:<port>`).
+3. **Is the video unlisted or private?** Ask if unsure.
+   - **Unlisted** ("não listado") = anyone with the link, **no login** → this skill works as-is.
+   - **Private / members-only** → you need the owner's **session cookies** (see Gotcha 6). Without
+     them, no tool can read it.
+
+---
+
+## STEP 1 — Get the transcript (cascade — stop at the first that returns segments)
+
+### Level 0 — `youtube-transcript-api` (free, fastest, usually wins)
+
+The library has TWO incompatible APIs — detect with `hasattr(YouTubeTranscriptApi, 'list_transcripts')`:
+
+```python
+from youtube_transcript_api import YouTubeTranscriptApi as Y
+proxies = {"http": PROXY, "https": PROXY} if PROXY else None  # only on datacenter IPs
+
+if hasattr(Y, "list_transcripts"):                      # v0.6.x — static API
+    tl = Y.list_transcripts(video_id, proxies=proxies)
+    t = tl.find_transcript(["pt", "en", "es"])
+    segs = [{"text": s["text"], "start": s["start"], "duration": s["duration"]} for s in t.fetch()]
+else:                                                    # v1.x — instance API
+    from youtube_transcript_api.proxies import GenericProxyConfig
+    cfg = GenericProxyConfig(http_url=PROXY, https_url=PROXY) if PROXY else None
+    api = Y(proxy_config=cfg) if cfg else Y()
+    t = api.list(video_id).find_transcript(["pt", "en", "es"])
+    segs = [{"text": s.text, "start": s.start, "duration": s.duration} for s in t.fetch()]
+```
+
+### Level 1 — yt-dlp auto-subs (when the API raises `TranscriptsDisabled`)
+
+The video may still have auto-generated captions:
+
+```bash
+yt-dlp --extractor-args "youtube:player_client=android" \
+       --write-auto-sub --sub-lang "pt,en" --sub-format json3 \
+       --skip-download -o "%(id)s" <url>
+```
+
+Parse the `.json3`: each `events[].segs[].utf8` is the text; `tStartMs`/`dDurationMs` are in **ms**
+(divide by 1000).
+
+### Level 2 — Gladia (when there are NO captions at all) → see STEP 2
+
+### Metadata (title, duration, channel, thumbnail)
+
+`yt-dlp`'s default `web` client returns **"This video is not available"** even on unlisted videos —
+that's the anti-bot, NOT missing access. Always pass `player_client=android`:
+
+```bash
+yt-dlp --extractor-args "youtube:player_client=android" --dump-json --no-download <url>
+```
+
+If metadata still fails, derive: **title** from your own list, **thumbnail** =
+`https://i.ytimg.com/vi/<id>/hqdefault.jpg`, **duration** = last segment `start + duration`.
+
+### Bundled helper (does Levels 0+1 + metadata + fallbacks in one call):
+
+```bash
+python .merlin-core/skills/general/youtube-transcript/scripts/fetch_transcript.py <url> \
+       [--lang pt] [--out path.json] [--proxy http://user:pass@host:port]
+```
+
+---
+
+## STEP 2 — Gladia fallback (audio → transcript) for caption-less videos
+
+When Levels 0 and 1 both return empty, download the audio and transcribe it. Works on any video.
+
+```bash
+node .merlin-core/skills/general/youtube-transcript/scripts/gladia_transcribe.mjs <url|videoId> \
+     [--out path.json] [--keep-audio]
+```
+
+What it does:
+
+1. `yt-dlp --extractor-args youtube:player_client=android -f "bestaudio/18" -o <id>.mp4 <url>`
+   (format 18 = 360p mp4 **with** audio; Gladia extracts the audio itself — no ffmpeg needed).
+2. `POST /v2/upload` (header `x-gladia-key`, FormData field `audio`) → `audio_url`.
+3. `POST /v2/pre-recorded` `{ audio_url, language_config:{languages:["pt"]}, punctuation_enhanced:true }` → job id.
+4. Poll `GET /v2/pre-recorded/<id>` every 10s until `status==="done"`.
+5. `result.transcription.utterances` → `{ text, start, duration: end - start }` (Gladia times are in **seconds**).
+
+The `GLADIA_API_KEY` is read from env, or from `.secrets-vault/<project>/transcription.env`
+(`GLADIA_API_KEY=`). Never hardcode or echo it. Gladia is **paid per audio-minute** — use it ONLY
+when Levels 0/1 (free) fail.
+
+---
+
+## GOTCHAS
+
+1. **`This video is not available` ≠ no access.** It's the anti-bot on the `web` client. Fix:
+   `--extractor-args "youtube:player_client=android"`. (Clients tested 2026-06: `android` OK;
+   `web_safari`/`ios`/`mweb` = format errors; `tv` = DRM.)
+2. **Unlisted ≠ private.** Unlisted needs no login. Don't waste time hunting cookies for unlisted videos.
+3. **`youtube-transcript-api` v0.6.x vs v1.x** have different APIs — branch on `hasattr(...,'list_transcripts')`.
+4. **Proxy only on datacenter IPs.** From a laptop it's unnecessary; from a VPS/Cloud Function it's mandatory.
+5. **Throttle batches.** `time.sleep(5)` between videos (12+) to avoid a temporary IP rate-limit.
+6. **Windows cookies are hard.** Edge/Chrome use App-Bound Encryption (yt-dlp DPAPI error); Firefox
+   works if installed. For private videos, the reliable path is a manually-exported Netscape
+   `cookies.txt` → `--cookies cookies.txt`. (Unlisted videos need none of this.)
+7. **`.mjs` ESM:** no `require()` — import at the top. And `*/` inside a path in a JSDoc comment
+   (e.g. `some-dir-*/x`) closes the comment block and breaks parsing.
+8. **Windows + Python emojis:** run with `PYTHONIOENCODING=utf-8` if `print` crashes under cp1252.
+
+---
+
+## When NOT to use this skill
+
+- The content is a **web article/blog** (not a video) → use Iris/WebFetch.
+- You need the **video file** itself, not the words → plain `yt-dlp` download.
+- The video is **private/members-only** and you don't have the owner's cookies → you can't read it; ask the user.
+
+## Example flow
+
+```
+Goal: transcript of an unlisted training video → study notes.
+1. STEP 0: unlisted, running locally → no proxy, no cookies needed.
+2. python fetch_transcript.py "https://youtu.be/XXXX" --out t.json
+   → Level 0 returns 2300 segments. Done.
+   (If it had raised TranscriptsDisabled and auto-sub was empty:)
+3. node gladia_transcribe.mjs XXXX --out t.json   → 2796 segments via Gladia.
+4. Feed t.json["transcript"] to an LLM for chapters/summary/key-terms.
+```
+
+## Output contract (both scripts emit the same shape)
+
+```jsonc
+{
+  "video": { "id", "title", "duration", "channel", "thumbnail", "upload_date" },
+  "sourceUrl": "https://...",
+  "lang": "pt",
+  "transcript": [ { "text": "...", "start": 0.0, "duration": 4.2 }, ... ],
+  "transcriptSource": "youtube-transcript-api" | "yt-dlp-autosub" | "gladia"
+}
+```