@amaster.ai/pi-lark 0.1.6 → 0.1.8

package/skills/lark-sheets/scripts/lark_sheet_range.py

@@ -0,0 +1,176 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+"""Range and coordinate helpers for Lark Sheet scripts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+CELL_RE = re.compile(r"^\$?([A-Za-z]+)\$?([1-9][0-9]*)$")
+ROW_RE = re.compile(r"^\$?([1-9][0-9]*)$")
+COLUMN_RE = re.compile(r"^\$?([A-Za-z]+)$")
+
+
+@dataclass(frozen=True)
+class RangeBounds:
+    start_row: int
+    start_col: int
+    end_row: int
+    end_col: int
+
+    @property
+    def row_count(self) -> int:
+        return self.end_row - self.start_row + 1
+
+    @property
+    def col_count(self) -> int:
+        return self.end_col - self.start_col + 1
+
+
+def col_to_index(col: str) -> int:
+    value = 0
+    for char in col.strip().upper():
+        if not ("A" <= char <= "Z"):
+            raise ValueError(f"Invalid column: {col}")
+        value = value * 26 + (ord(char) - ord("A") + 1)
+    if value <= 0:
+        raise ValueError(f"Invalid column: {col}")
+    return value
+
+
+def index_to_col(index: int) -> str:
+    if index < 1:
+        raise ValueError(f"Column index must be >= 1: {index}")
+    chars = []
+    n = index
+    while n:
+        n, rem = divmod(n - 1, 26)
+        chars.append(chr(ord("A") + rem))
+    return "".join(reversed(chars))
+
+
+def parse_cell(cell_ref: str) -> tuple[int, int]:
+    match = CELL_RE.match(cell_ref.strip())
+    if not match:
+        raise ValueError(f"Invalid cell reference: {cell_ref}")
+    col, row = match.groups()
+    return int(row), col_to_index(col)
+
+
+def _parse_endpoint(endpoint: str) -> tuple[str, int, int] | tuple[str, int]:
+    cell = CELL_RE.match(endpoint)
+    if cell:
+        col, row = cell.groups()
+        return "cell", int(row), col_to_index(col)
+    row = ROW_RE.match(endpoint)
+    if row:
+        return "row", int(row.group(1))
+    column = COLUMN_RE.match(endpoint)
+    if column:
+        return "column", col_to_index(column.group(1))
+    raise ValueError(f"Invalid A1 range endpoint: {endpoint}")
+
+
+def parse_range(
+    range_ref: str,
+    *,
+    max_row: int | None = None,
+    max_col: int | None = None,
+) -> RangeBounds:
+    """Parse the A1 range forms accepted by ``+csv-get``.
+
+    Open-ended forms need the caller's actual returned grid dimensions. This
+    keeps generated ranges finite without guessing a spreadsheet-wide limit.
+    """
+    ref = range_ref.strip()
+    if "!" in ref:
+        _, ref = ref.rsplit("!", 1)
+    if not ref:
+        raise ValueError(f"Invalid A1 range: {range_ref}")
+    parts = ref.split(":")
+    if len(parts) > 2:
+        raise ValueError(f"Invalid A1 range: {range_ref}")
+    start = _parse_endpoint(parts[0])
+    end = _parse_endpoint(parts[-1])
+
+    if len(parts) == 1:
+        if start[0] != "cell":
+            raise ValueError(f"A1 range must include a cell or ':' separator: {range_ref}")
+        _, row, col = start
+        return RangeBounds(row, col, row, col)
+
+    if start[0] == end[0] == "cell":
+        _, start_row, start_col = start
+        _, end_row, end_col = end
+    elif start[0] == end[0] == "row":
+        _, start_row = start
+        _, end_row = end
+        start_col = 1
+        if max_col is None:
+            raise ValueError(f"Range needs a maximum column: {range_ref}")
+        end_col = max_col
+    elif start[0] == end[0] == "column":
+        _, start_col = start
+        _, end_col = end
+        start_row = 1
+        if max_row is None:
+            raise ValueError(f"Range needs a maximum row: {range_ref}")
+        end_row = max_row
+    elif start[0] == "cell" and end[0] == "column":
+        _, start_row, start_col = start
+        _, end_col = end
+        if max_row is None:
+            raise ValueError(f"Range needs a maximum row: {range_ref}")
+        end_row = max(start_row, max_row)
+    elif start[0] == "cell" and end[0] == "row":
+        _, start_row, start_col = start
+        _, end_row = end
+        if max_col is None:
+            raise ValueError(f"Range needs a maximum column: {range_ref}")
+        end_col = max(start_col, max_col)
+    else:
+        raise ValueError(f"Invalid A1 range: {range_ref}")
+    return RangeBounds(min(start_row, end_row), min(start_col, end_col), max(start_row, end_row), max(start_col, end_col))
+
+
+def format_cell(row: int, col: int) -> str:
+    if row < 1:
+        raise ValueError(f"Row must be >= 1: {row}")
+    return f"{index_to_col(col)}{row}"
+
+
+def format_range(start_row: int, start_col: int, end_row: int, end_col: int) -> str:
+    bounds = RangeBounds(
+        min(start_row, end_row),
+        min(start_col, end_col),
+        max(start_row, end_row),
+        max(start_col, end_col),
+    )
+    start = format_cell(bounds.start_row, bounds.start_col)
+    end = format_cell(bounds.end_row, bounds.end_col)
+    return start if start == end else f"{start}:{end}"
+
+
+def iter_cells(bounds: RangeBounds):
+    for row in range(bounds.start_row, bounds.end_row + 1):
+        for col in range(bounds.start_col, bounds.end_col + 1):
+            yield row, col
+
+
+def ranges_intersect(a: RangeBounds, b: RangeBounds) -> bool:
+    return not (
+        a.end_row < b.start_row
+        or b.end_row < a.start_row
+        or a.end_col < b.start_col
+        or b.end_col < a.start_col
+    )
+
+
+def range_union(a: RangeBounds, b: RangeBounds) -> RangeBounds:
+    return RangeBounds(
+        min(a.start_row, b.start_row),
+        min(a.start_col, b.start_col),
+        max(a.end_row, b.end_row),
+        max(a.end_col, b.end_col),
+    )

package/skills/lark-sheets/scripts/lark_sheet_read_cli.py

@@ -0,0 +1,184 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+"""Read-only Lark Sheet subset wrapper for the helper scripts."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import Any
+
+
+class LarkCliError(RuntimeError):
+    def __init__(self, message: str, *, cmd: list[str] | None = None):
+        super().__init__(message)
+        self.cmd = cmd or []
+
+
+def add_spreadsheet_args(
+    parser,
+    *,
+    require_sheet: bool = False,
+    allow_sheet: bool = True,
+) -> None:
+    spreadsheet = parser.add_mutually_exclusive_group(required=True)
+    spreadsheet.add_argument("--url")
+    spreadsheet.add_argument("--spreadsheet-token")
+    if allow_sheet:
+        sheet = parser.add_mutually_exclusive_group(required=require_sheet)
+        sheet.add_argument("--sheet-id")
+        sheet.add_argument("--sheet-name")
+
+
+def _append_flag(cmd: list[str], name: str, value: Any) -> None:
+    flag = f"--{name.replace('_', '-')}"
+    if value is None:
+        return
+    if isinstance(value, bool):
+        cmd.append(flag if value else f"{flag}=false")
+        return
+    cmd.extend([flag, str(value)])
+
+
+def run_sheets(
+    shortcut: str,
+    *,
+    url: str | None = None,
+    spreadsheet_token: str | None = None,
+    sheet_id: str | None = None,
+    sheet_name: str | None = None,
+    flags: dict[str, Any] | None = None,
+    timeout: int = 60,
+) -> dict[str, Any]:
+    if bool(url) == bool(spreadsheet_token):
+        raise LarkCliError("Pass exactly one of --url or --spreadsheet-token")
+    if sheet_id and sheet_name:
+        raise LarkCliError("Pass only one of --sheet-id or --sheet-name")
+
+    cmd = ["lark-cli", "sheets", shortcut]
+    _append_flag(cmd, "url", url)
+    _append_flag(cmd, "spreadsheet_token", spreadsheet_token)
+    _append_flag(cmd, "sheet_id", sheet_id)
+    _append_flag(cmd, "sheet_name", sheet_name)
+    for key, value in (flags or {}).items():
+        _append_flag(cmd, key, value)
+
+    try:
+        completed = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise LarkCliError("lark-cli not found", cmd=cmd) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise LarkCliError(f"lark-cli timed out after {timeout}s", cmd=cmd) from exc
+
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or "").strip()
+        raise LarkCliError(detail or f"lark-cli exited with {completed.returncode}", cmd=cmd)
+
+    try:
+        envelope = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        snippet = completed.stdout[:500].replace("\n", "\\n")
+        raise LarkCliError(f"lark-cli stdout was not JSON: {snippet}", cmd=cmd) from exc
+
+    if isinstance(envelope, dict) and envelope.get("ok") is False:
+        raise LarkCliError(json.dumps(envelope, ensure_ascii=False), cmd=cmd)
+    if not isinstance(envelope, dict):
+        raise LarkCliError("lark-cli returned a non-object JSON payload", cmd=cmd)
+    return envelope
+
+
+def envelope_data(envelope: dict[str, Any]) -> dict[str, Any]:
+    data = envelope.get("data")
+    return data if isinstance(data, dict) else envelope
+
+
+def emit_success(action: str, data: dict[str, Any], warnings: list[str] | None = None) -> None:
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "engine": "lark",
+                "action": action,
+                "data": data,
+                "warnings": warnings or [],
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+
+
+def emit_error(action: str, message: str, warnings: list[str] | None = None) -> None:
+    print(
+        json.dumps(
+            {
+                "ok": False,
+                "engine": "lark",
+                "action": action,
+                "error": message,
+                "warnings": warnings or [],
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    sys.exit(1)
+
+
+def sheet_title(sheet: dict[str, Any]) -> str:
+    return str(sheet.get("title") or sheet.get("sheet_name") or sheet.get("name") or "")
+
+
+def sheet_identifier(sheet: dict[str, Any]) -> str:
+    return str(sheet.get("sheet_id") or sheet.get("id") or "")
+
+
+def sheet_locator(sheet: dict[str, Any]) -> dict[str, str]:
+    sid = sheet_identifier(sheet)
+    if sid:
+        return {"sheet_id": sid}
+    title = sheet_title(sheet)
+    if title:
+        return {"sheet_name": title}
+    return {}
+
+
+def extract_sheets(workbook_data: dict[str, Any]) -> list[dict[str, Any]]:
+    sheets = workbook_data.get("sheets")
+    if isinstance(sheets, list):
+        return [sheet for sheet in sheets if isinstance(sheet, dict)]
+    workbook = workbook_data.get("workbook")
+    if isinstance(workbook, dict) and isinstance(workbook.get("sheets"), list):
+        return [sheet for sheet in workbook["sheets"] if isinstance(sheet, dict)]
+    return []
+
+
+def resolve_target_sheets(
+    workbook_data: dict[str, Any],
+    *,
+    sheet_id: str | None = None,
+    sheet_name: str | None = None,
+    require_one: bool = False,
+) -> list[dict[str, Any]]:
+    sheets = extract_sheets(workbook_data)
+    if sheet_id:
+        matches = [sheet for sheet in sheets if sheet_identifier(sheet) == sheet_id]
+    elif sheet_name:
+        matches = [sheet for sheet in sheets if sheet_title(sheet) == sheet_name]
+    else:
+        matches = sheets
+
+    if require_one:
+        if len(matches) == 1:
+            return matches
+        if not matches:
+            raise LarkCliError("No matching sheet found")
+        raise LarkCliError("Multiple sheets matched; pass --sheet-id or --sheet-name")
+    return matches

package/skills/lark-sheets/scripts/sheets_df.py

@@ -19,11 +19,29 @@ import pandas as pd
 
 def df_to_sheet(df, name, formats=None):
     """Pack one DataFrame into one entry of a `+table-put --sheets` payload."""
+    packed = json.loads(df.to_json(orient="split", date_format="iso"))
+    # The protocol requires string column names. pandas keeps integer labels
+    # (e.g. the default RangeIndex columns 0/1/2) as JSON numbers, while the
+    # dtypes dict keys get stringified during JSON serialization — the CLI
+    # then rejects `columns` ("cannot unmarshal number into … type string")
+    # and the dtype lookup would miss anyway. Stringify every key once, and
+    # refuse to continue when that conversion silently merges two columns.
+    normalized_labels = [str(c) for c in df.columns]
+    columns = [str(c) for c in packed["columns"]]
+    if normalized_labels != columns:
+        columns = normalized_labels
+    if len(set(columns)) != len(columns):
+        raise ValueError(
+            "column labels collide after str() conversion; "
+            "rename the DataFrame columns before packing"
+        )
+    packed["columns"] = columns
+    dtype_values = list(df.dtypes)
     return {
         "name": name,
-        **json.loads(df.to_json(orient="split", date_format="iso")),
-        "dtypes": df.dtypes.astype(str).to_dict(),
-        **({"formats": formats} if formats else {}),
+        **packed,
+        "dtypes": {key: str(dtype) for key, dtype in zip(columns, dtype_values)},
+        **({"formats": {str(k): v for k, v in formats.items()}} if formats else {}),
     }