@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/spreadsheet-ops/references/python-excel.md

@@ -0,0 +1,87 @@
+# Python → Excel: openpyxl vs xlsxwriter vs pandas
+
+Versions seen on PyPI 2026-06-02: openpyxl 3.1.5, pandas on the 3.x line, plus xlsxwriter (a separate
+install — pandas does not bundle it). Re-check PyPI before pinning.
+
+## Choosing the engine
+
+| Need | Library | Notes |
+| --- | --- | --- |
+| Open + modify an existing `.xlsx` | openpyxl | Only one that round-trips an existing file. |
+| New file, charts + conditional formats | xlsxwriter | Write-only. Richest formatting. |
+| New file, very large, low memory | xlsxwriter `constant_memory` or openpyxl `write_only` | Stream row-by-row; cannot revisit written cells. |
+| Quick DataFrame dump | pandas `to_excel` | Wraps an engine — pass `engine=` explicitly (see below). |
+| Append a sheet to an existing file | pandas `ExcelWriter(engine="openpyxl", mode="a")` | xlsxwriter cannot append — it is write-only. |
+
+For `.xlsx`, pandas `ExcelWriter`/`to_excel` resolves its engine from the `io.excel.xlsx.writer`
+option: **xlsxwriter when it is installed, otherwise openpyxl**. That makes the effective default
+environment-dependent — the same script writes through different engines on two machines, and append
+mode silently needs openpyxl regardless. Do not rely on the implicit pick: always pass `engine=`
+(`"xlsxwriter"` for a new formatted file, `"openpyxl"` for read/modify/append). Being explicit is the
+whole fix for the long-standing default-engine confusion.
+
+## The no-compute trap (full)
+
+openpyxl stores the formula string; it never evaluates it. Excel/LibreOffice computes on open and
+caches the result.
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("book.xlsx")
+ws = wb.active
+ws["C2"] = "=A2*B2"
+wb.save("book.xlsx")
+
+# default load: cell holds the formula text
+print(load_workbook("book.xlsx").active["C2"].value)            # "=A2*B2"
+# data_only: cell holds the LAST CACHED value — None if never opened in Excel
+print(load_workbook("book.xlsx", data_only=True).active["C2"].value)  # None
+```
+
+If a downstream consumer needs the number, either compute it in Python and write the literal value, or
+open the file once headless (e.g. `libreoffice --headless --convert-to xlsx`) so the cache is populated.
+
+Array and data-table formulae are preserved on read/write but, likewise, not evaluated.
+
+## Chart + conditional format (xlsxwriter, new file)
+
+```python
+import pandas as pd
+
+df = pd.DataFrame({"month": ["Jan", "Feb", "Mar"], "revenue": [100, 140, 90]})
+with pd.ExcelWriter("report.xlsx", engine="xlsxwriter") as xl:
+    df.to_excel(xl, sheet_name="data", index=False)
+    wb, ws = xl.book, xl.sheets["data"]
+
+    # conditional format: highlight revenue < 100
+    ws.conditional_format("B2:B4", {
+        "type": "cell", "criteria": "<", "value": 100,
+        "format": wb.add_format({"bg_color": "#fde0e0"}),
+    })
+
+    # column chart bound to the data range
+    chart = wb.add_chart({"type": "column"})
+    chart.add_series({
+        "categories": "=data!$A$2:$A$4",
+        "values":     "=data!$B$2:$B$4",
+        "name":       "Revenue",
+    })
+    ws.insert_chart("D2", chart)
+```
+
+Conditional formats on an **existing** file go through openpyxl's `openpyxl.formatting.rule` instead
+(xlsxwriter cannot reopen the file).
+
+## Large files
+
+- xlsxwriter: `Workbook(path, {"constant_memory": True})` — flushes each row, near-flat memory; you
+  cannot go back and rewrite an already-written cell.
+- openpyxl: `Workbook(write_only=True)` then `ws.append([...])` per row. Same constraint.
+
+## Append-mode gotchas
+
+- `df.to_excel("f.xlsx")` with the default mode **truncates** the whole workbook. To keep existing
+  sheets use `ExcelWriter(..., engine="openpyxl", mode="a")`.
+- `if_sheet_exists` must be set in append mode: `"error"` (default), `"replace"`, `"overlay"`, `"new"`.
+- xlsxwriter ignores `mode="a"` — it has no read path. Use openpyxl to append.

package/skills/shared/spreadsheet-ops/references/sheets-api-appsscript.md

@@ -0,0 +1,118 @@
+# Google Sheets API v4 + Apps Script V8
+
+Versions seen on PyPI 2026-06-02: gspread 6.2.1, gspread-formatting 1.2.1; Sheets API v4; Apps Script
+on the V8 runtime. Re-check before pinning.
+
+## Credentials (handoff)
+
+Creating the OAuth client / service account is `../google-workspace/SKILL.md`. This skill assumes a
+credential exists. gspread auth modes:
+
+| Mode | Call | Use for |
+| --- | --- | --- |
+| Service account | `gspread.service_account(filename="key.json")` | Bots, cron, servers |
+| End-user OAuth | `gspread.oauth()` | Acting as a human |
+| Public read | `gspread.api_key("API_KEY")` | Read-only public sheets |
+
+**Service account access requirement:** a service account sees nothing until the sheet is shared with
+its `client_email` (read it from the key JSON). A `PermissionError`/`SpreadsheetNotFound` is almost
+always an unshared sheet. Share with Editor for writes.
+
+## Quota math
+
+- 300 read req/min/project, 60 read req/min/user (writes mirror these), as published 2026-06-02.
+- Refilled each minute; no daily cap when under the per-minute ceiling.
+- A `batchUpdate` counts as **one** request no matter how many sub-requests it carries.
+- These numbers move — confirm against Google's current "Usage limits" page before sizing a job.
+
+Implication: collapse N writes into one `batchUpdate`, and back off on 429.
+
+## batchUpdate request shape
+
+```python
+service.spreadsheets().batchUpdate(
+    spreadsheetId=SID,
+    body={"requests": [
+        {"updateCells": {  # write a block of values
+            "range": {"sheetId": 0, "startRowIndex": 0, "startColumnIndex": 0},
+            "rows": [{"values": [{"userEnteredValue": {"stringValue": "order_id"}}]}],
+            "fields": "userEnteredValue",
+        }},
+        {"repeatCell": {  # conditional-style formatting on a range
+            "range": {"sheetId": 0, "startRowIndex": 1, "endRowIndex": 100},
+            "cell": {"userEnteredFormat": {"backgroundColor": {"red": 0.99, "green": 0.88, "blue": 0.88}}},
+            "fields": "userEnteredFormat.backgroundColor",
+        }},
+    ]},
+).execute()
+```
+
+## Exponential backoff on 429
+
+```python
+import time, random
+from googleapiclient.errors import HttpError
+
+def with_backoff(call, tries=5):
+    for n in range(tries):
+        try:
+            return call()
+        except HttpError as e:
+            if e.resp.status != 429 or n == tries - 1:
+                raise
+            time.sleep((2 ** n) + random.random())  # 1s, 2s, 4s... + jitter
+```
+
+A1 (`Sheet1!A1:C10`) vs R1C1 indices: gspread uses A1 strings; the raw API `GridRange` uses
+zero-based `startRowIndex`/`endRowIndex` (end-exclusive). Mixing them off-by-one is a common bug.
+
+## Apps Script V8
+
+Target **V8**: Google deprecated the legacy Rhino runtime (Feb 2025) with retirement set for on or
+after 2026-01-31, so never author new code against it. V8 has no `fetch`, no timers, no streams; no ES6
+`import/export`; no private `#fields`.
+
+HTTP — use UrlFetchApp:
+
+```javascript
+function pull() {
+  const res = UrlFetchApp.fetch("https://api.example.com/data", {
+    method: "get", muteHttpExceptions: true,
+  });
+  if (res.getResponseCode() !== 200) throw new Error(res.getContentText());
+  return JSON.parse(res.getContentText());
+}
+// Parallel requests: UrlFetchApp.fetchAll([{url: ...}, {url: ...}]);
+```
+
+Batch reads/writes — never per-cell:
+
+```javascript
+function fillTotals() {
+  const sh = SpreadsheetApp.getActiveSheet();
+  const rows = sh.getDataRange().getValues();          // ONE read
+  const totals = rows.slice(1).map(r => [r[1] * r[2]]); // qty * price
+  sh.getRange(2, 4, totals.length, 1).setValues(totals); // ONE write
+}
+```
+
+Time-driven trigger (run nightly at 02:00):
+
+```javascript
+function install() {
+  ScriptApp.newTrigger("fillTotals").timeBased().everyDays(1).atHour(2).create();
+}
+```
+
+Custom menu (`onOpen` simple trigger):
+
+```javascript
+function onOpen() {
+  SpreadsheetApp.getUi().createMenu("Ops")
+    .addItem("Fill totals", "fillTotals").addToUi();
+}
+```
+
+For cross-sheet formulas, `SHEET()` (sheet index) and `SHEETS()` (sheet count) have shipped for years
+(Excel since 2013; present in Google Sheets) — safe to emit. For richer integrations, check Apps
+Script's current advanced-services list rather than assuming a given service exists.

package/skills/shared/spreadsheet-ops/scripts/verify.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — spreadsheet-ops artifact check. Read-only by default.
+#
+# What it proves about the artifacts this skill emits:
+#   1. Every generated *.py compiles (python -m py_compile) — valid syntax, real imports.
+#   2. Every generated *.xlsx opens with openpyxl and has at least one sheet with a
+#      non-empty first (header) row.
+#   3. Formula strings (anything matching a leading '=' inside the .py/.xlsx) are linted
+#      for the semicolon-as-argument-separator bug — the #1 locale formula failure.
+#
+# Targets, in order of precedence:
+#   - explicit paths passed as arguments (files or directories), OR
+#   - the current working directory (scanned for *.py and *.xlsx).
+#
+# It NEVER modifies your files and makes NO network/Google calls — cloud paths in this
+# skill are validated by structure, not live API requests.
+#
+# Exit code: 0 on pass OR on a clean/empty target (nothing to check is not a failure).
+# Non-zero ONLY when a found artifact is genuinely broken (won't compile, won't open,
+# missing header, or a semicolon-separated formula).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+PY="$(command -v python3 || command -v python || true)"
+
+# Collect candidate files from args (files/dirs) or the cwd.
+PYFILES=(); XLSXFILES=()
+collect() {
+  local t="$1"
+  if [ -d "$t" ]; then
+    while IFS= read -r f; do PYFILES+=("$f"); done   < <(find "$t" -type f -name '*.py'   2>/dev/null)
+    while IFS= read -r f; do XLSXFILES+=("$f"); done < <(find "$t" -type f -name '*.xlsx' 2>/dev/null)
+  elif [ -f "$t" ]; then
+    case "$t" in
+      *.py)   PYFILES+=("$t") ;;
+      *.xlsx) XLSXFILES+=("$t") ;;
+    esac
+  fi
+}
+
+if [ "$#" -gt 0 ]; then
+  for t in "$@"; do collect "$t"; done
+else
+  collect "$PWD"
+fi
+
+if [ "${#PYFILES[@]}" -eq 0 ] && [ "${#XLSXFILES[@]}" -eq 0 ]; then
+  skip "no .py or .xlsx artifacts found to verify — nothing to check"
+  exit 0
+fi
+
+fail=0
+
+# 1. py_compile each Python file.
+if [ "${#PYFILES[@]}" -gt 0 ]; then
+  if [ -z "$PY" ]; then
+    skip "python not on PATH — skipping .py compile checks"
+  else
+    for f in "${PYFILES[@]}"; do
+      if "$PY" -m py_compile "$f" >/dev/null 2>&1; then
+        ok "compiles: $f"
+      else
+        err "does not compile: $f"; fail=1
+      fi
+    done
+  fi
+fi
+
+# 2. open each workbook, assert a sheet + non-empty header row (needs openpyxl).
+if [ "${#XLSXFILES[@]}" -gt 0 ]; then
+  if [ -z "$PY" ] || ! "$PY" -c "import openpyxl" >/dev/null 2>&1; then
+    skip "openpyxl not installed — skipping .xlsx structural checks"
+  else
+    for f in "${XLSXFILES[@]}"; do
+      if "$PY" - "$f" <<'PYEOF'
+import sys
+from openpyxl import load_workbook
+wb = load_workbook(sys.argv[1], read_only=True, data_only=False)
+if not wb.sheetnames:
+    sys.exit(1)
+ws = wb[wb.sheetnames[0]]
+row = next(ws.iter_rows(min_row=1, max_row=1, values_only=True), None)
+sys.exit(0 if row is not None and any(c is not None and str(c) != "" for c in row) else 1)
+PYEOF
+      then
+        ok "opens with header row: $f"
+      else
+        err "missing/unreadable or empty header row: $f"; fail=1
+      fi
+    done
+  fi
+fi
+
+# 3. lint formula strings for semicolon argument separators inside .py/.xlsx-as-text.
+# A formula is a token starting with '=' that contains '(' and a ';'. Commas are correct;
+# semicolons inside the parens are the locale bug this skill warns about.
+# The lint script reads stdin; pass it via -c so the piped file flows through as stdin
+# (a heredoc on `$PY -` would itself become stdin and shadow the file).
+LINT_PY='import sys, re
+bad = []
+pat = re.compile(r"=[A-Za-z_][A-Za-z0-9_.]*\([^)]*;[^)]*\)")
+for i, line in enumerate(sys.stdin, 1):
+    if pat.search(line):
+        bad.append((i, line.rstrip()))
+for i, l in bad:
+    print(f"  line {i}: {l}")
+sys.exit(1 if bad else 0)'
+lint_text() {
+  # reads stdin; prints offending lines; returns 1 if any found
+  "$PY" -c "$LINT_PY"
+}
+
+if [ -n "$PY" ]; then
+  for f in "${PYFILES[@]}"; do
+    if out="$(lint_text < "$f")"; then :; else
+      err "semicolon-separated formula in $f"; printf '%s\n' "$out"; fail=1
+    fi
+  done
+  # For .xlsx, extract embedded formula strings from the workbook XML via openpyxl text.
+  if [ -n "$PY" ] && "$PY" -c "import openpyxl" >/dev/null 2>&1; then
+    for f in "${XLSXFILES[@]}"; do
+      formulas="$("$PY" - "$f" <<'PYEOF'
+import sys
+from openpyxl import load_workbook
+wb = load_workbook(sys.argv[1], data_only=False)
+for ws in wb.worksheets:
+    for row in ws.iter_rows():
+        for c in row:
+            v = c.value
+            if isinstance(v, str) and v.startswith("="):
+                print(v)
+PYEOF
+)"
+      if [ -n "$formulas" ]; then
+        if out="$(printf '%s\n' "$formulas" | lint_text)"; then :; else
+          err "semicolon-separated formula in workbook $f"; printf '%s\n' "$out"; fail=1
+        fi
+      fi
+    done
+  fi
+fi
+
+if [ "$fail" -eq 0 ]; then
+  ok "all found artifacts pass"
+  exit 0
+fi
+exit 1