procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/web/tests/test_steps.py

@@ -0,0 +1,210 @@
+"""The declarative step interpreter: each step type dispatches to the right
+driver call with the right args, and bad steps fail fast as UsageError."""
+from __future__ import annotations
+
+import pytest
+
+from tools.web.errors import UsageError
+from tools.web.steps import KNOWN_STEPS, run_steps, validate_steps
+
+
+def test_goto_click_fill_press_wait_dispatch(fake_driver):
+    steps = [
+        {"do": "goto", "url": "https://x.test"},
+        {"do": "wait_for", "selector": "#ready"},
+        {"do": "fill", "selector": "#q", "text": "hello"},
+        {"do": "click", "selector": "#go"},
+        {"do": "press", "key": "Enter"},
+    ]
+    run_steps(fake_driver, steps)
+    assert fake_driver.methods() == [
+        "goto", "wait_for", "fill", "click", "press", "current_url",
+    ]
+    # args carried through correctly
+    calls = {m: kw for m, kw in fake_driver.calls}
+    assert calls["goto"]["url"] == "https://x.test"
+    assert calls["fill"]["selector"] == "#q"
+    assert calls["fill"]["text"] == "hello"
+    assert calls["press"]["key"] == "Enter"
+
+
+def test_press_with_selector(fake_driver):
+    run_steps(fake_driver, [{"do": "press", "key": "Tab", "selector": "#name"}])
+    press = [kw for m, kw in fake_driver.calls if m == "press"][0]
+    assert press == {"key": "Tab", "selector": "#name"}
+
+
+def test_type_step_dispatches_keyboard(fake_driver):
+    # No selector -> types into whatever is focused (e.g. a canvas grid cell).
+    # With selector -> the element is focused first, then typed into.
+    run_steps(fake_driver, [
+        {"do": "type", "text": "hello world"},
+        {"do": "type", "text": "x", "selector": "#t-name-box", "timeout": 3000},
+    ])
+    types = [kw for m, kw in fake_driver.calls if m == "type_text"]
+    assert types[0] == {"text": "hello world", "selector": None, "timeout": None}
+    assert types[1] == {"text": "x", "selector": "#t-name-box", "timeout": 3000}
+
+
+def test_wait_step_dispatches_fixed_delay(fake_driver):
+    run_steps(fake_driver, [{"do": "wait", "ms": 1500}])
+    waits = [kw for m, kw in fake_driver.calls if m == "wait"]
+    assert waits == [{"ms": 1500}]
+
+
+def test_type_requires_text():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "type", "selector": "#x"}])
+    assert "missing required key" in str(e.value)
+
+
+def test_wait_requires_ms():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "wait"}])
+    assert "missing required key" in str(e.value)
+
+
+def test_extract_text_named_and_default_name(fake_driver):
+    fake_driver.texts = {"h1": "Big Title", None: "whole body"}
+    out = run_steps(fake_driver, [
+        {"do": "extract_text", "selector": "h1", "name": "headline"},
+        {"do": "extract_text"},  # no selector -> reads body; name falls back to "text"
+    ])
+    assert out["results"]["headline"] == "Big Title"
+    assert out["results"]["text"] == "whole body"
+
+
+def test_extract_attr_named_and_fallback_name(fake_driver):
+    fake_driver.attrs = {("a.cta", "href"): "https://dest"}
+    out = run_steps(fake_driver, [
+        {"do": "extract_attr", "selector": "a.cta", "attr": "href", "name": "link"},
+        {"do": "extract_attr", "selector": "img", "attr": "src"},
+    ])
+    assert out["results"]["link"] == "https://dest"
+    # fallback name is "<selector>@<attr>"
+    assert out["results"]["img@src"] == "attr:img:src"
+
+
+def test_screenshot_collected(fake_driver):
+    out = run_steps(fake_driver, [
+        {"do": "screenshot", "path": "a.png"},
+        {"do": "screenshot", "path": "b.png", "full_page": False},
+    ])
+    assert out["screenshots"] == ["a.png", "b.png"]
+    shots = [kw for m, kw in fake_driver.calls if m == "screenshot"]
+    assert shots[1]["full_page"] is False
+
+
+def test_timeout_passed_through(fake_driver):
+    run_steps(fake_driver, [{"do": "wait_for", "selector": "#x", "timeout": 5000}])
+    wait = [kw for m, kw in fake_driver.calls if m == "wait_for"][0]
+    assert wait["timeout"] == 5000
+
+
+def test_final_url_included(fake_driver):
+    fake_driver.url = "https://x.test/final"
+    out = run_steps(fake_driver, [{"do": "goto", "url": "https://x.test"}])
+    assert out["final_url"] == "https://x.test/final"
+
+
+# --- validation / error cases (no driver interaction needed) --------------
+
+def test_steps_must_be_list():
+    with pytest.raises(UsageError):
+        validate_steps({"do": "goto", "url": "x"})
+
+
+def test_unknown_step_rejected():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "teleport", "url": "x"}])
+    assert "unknown action" in str(e.value)
+
+
+def test_missing_required_key_rejected():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "fill", "selector": "#q"}])  # missing text
+    assert "missing required key" in str(e.value)
+
+
+def test_unknown_key_rejected():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "goto", "url": "x", "bogus": 1}])
+    assert "unknown key" in str(e.value)
+
+
+def test_missing_do_rejected():
+    with pytest.raises(UsageError):
+        validate_steps([{"url": "x"}])
+
+
+def test_non_object_step_rejected():
+    with pytest.raises(UsageError):
+        validate_steps(["just a string"])
+
+
+def test_validation_happens_before_any_driver_call(fake_driver):
+    # A later bad step must abort the whole run before the good first step runs.
+    with pytest.raises(UsageError):
+        run_steps(fake_driver, [
+            {"do": "goto", "url": "https://x.test"},
+            {"do": "nope"},
+        ])
+    assert fake_driver.calls == []  # nothing executed
+
+
+def test_known_steps_constant_matches_schema():
+    assert KNOWN_STEPS == {
+        "goto", "click", "fill", "press", "type", "wait", "wait_for",
+        "extract_text", "extract_attr", "eval", "viewport", "screenshot",
+        "upload", "upload_via_chooser",
+    }
+
+
+def test_upload_dispatches_set_input_files(fake_driver):
+    run_steps(fake_driver, [
+        {"do": "upload", "selector": "#avatar", "path": "C:/pics/me.jpg"},
+        {"do": "upload", "selector": "#docs", "path": ["a.pdf", "b.pdf"], "timeout": 9000},
+    ])
+    calls = [kw for m, kw in fake_driver.calls if m == "set_input_files"]
+    assert calls[0] == {"selector": "#avatar", "files": "C:/pics/me.jpg", "timeout": None}
+    assert calls[1] == {"selector": "#docs", "files": ["a.pdf", "b.pdf"], "timeout": 9000}
+
+
+def test_upload_via_chooser_dispatches(fake_driver):
+    run_steps(fake_driver, [
+        {"do": "upload_via_chooser", "selector": "button.attach", "path": "note.png"},
+    ])
+    call = [kw for m, kw in fake_driver.calls if m == "set_files_via_chooser"][0]
+    assert call == {"selector": "button.attach", "files": "note.png", "timeout": None}
+
+
+def test_upload_requires_selector_and_path():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "upload", "selector": "#f"}])  # missing path
+    assert "missing required key" in str(e.value)
+
+
+def test_click_defaults_to_the_actionability_check(fake_driver):
+    run_steps(fake_driver, [{"do": "click", "selector": "button.save"}])
+    assert ("click", {"selector": "button.save", "timeout": None,
+                      "force": False}) in fake_driver.calls
+
+
+def test_click_can_be_forced_through_an_overlay(fake_driver):
+    """Some frameworks paint a container over their own controls; without this
+    the click is refused even though a person can press the control."""
+    run_steps(fake_driver, [{"do": "click", "selector": "button.save", "force": True}])
+    assert ("click", {"selector": "button.save", "timeout": None,
+                      "force": True}) in fake_driver.calls
+
+
+def test_viewport_step_dispatches_resize(fake_driver):
+    run_steps(fake_driver, [{"do": "viewport", "width": 1920, "height": 1080}])
+    sizes = [kw for m, kw in fake_driver.calls if m == "set_viewport"]
+    assert sizes == [{"width": 1920, "height": 1080}]
+
+
+def test_viewport_requires_width_and_height():
+    with pytest.raises(UsageError) as e:
+        validate_steps([{"do": "viewport", "width": 1920}])
+    assert "missing required key" in str(e.value)

procesio_cli/tools/web/tool.yaml

@@ -0,0 +1,184 @@
+name: web
+description: >
+  Drive web apps that have NO API via Playwright, reusing SAVED login sessions
+  so we authenticate once and reuse. Sessions are Playwright storageState
+  (cookies + localStorage) per named site, stored gitignored under
+  tools/web/sessions/<name>.json - they hold live auth and are SENSITIVE
+  (never committed, never printed). Other tools and the outreach agent call
+  this whenever they need to connect to a site or do deeper web research.
+  Action-dispatched. No HTTP API; a BrowserDriver abstraction wraps Playwright
+  (imported lazily) so the tool loads even before browsers are installed.
+  BROKER-OWNED SESSIONS: run/get-text/screenshot against a session owned by a
+  serializing broker (whatsapp/ryver/fgo/mirro - tools/_lib/webserialize) are
+  executed INSIDE that broker, serialized with the owning tool's commands, so
+  ad-hoc web commands can't race the profile. --direct bypasses (backup).
+  save-session/delete-session auto-stop the owning broker first.
+version: 0.2.0
+runtime: python
+entrypoint: main.py
+
+# No credentials in Credential Manager: auth lives in saved session files
+# (storageState) under tools/web/sessions/, which are gitignored.
+secrets: []
+
+routing:
+  triggers:
+    - "drive/scrape a website that has no API, using a saved login session; deeper web research"
+  primary_action: run
+  example: "web run --session <name> ...   (read text: web get-text; one-time login: web save-session)"
+
+actions:
+  - name: save-session
+    description: >
+      Interactively capture a login session. Launches a HEADED browser at --url,
+      lets the human log in, then captures storageState to
+      tools/web/sessions/<name>.json. Run once per site. By default it BLOCKS
+      until ENTER is pressed on stdin; an AGENT must instead pass --wait-seconds,
+      because agent stdin is EOF and the ENTER wait would return instantly and
+      save a half-authenticated profile.
+    args:
+      - {name: name, type: string, required: true, description: "Session name (letters/digits/._-); how you reference it later"}
+      - {name: url, type: string, required: true, description: Login URL to open in the headed browser}
+      - {name: channel, type: string, description: "Optional Chromium channel: 'chrome' or 'msedge' (use a real installed browser)"}
+      - {name: persistent, type: boolean, description: "Save a PERSISTENT browser profile (user-data-dir) instead of a storageState snapshot; required for IndexedDB-auth sites like WhatsApp Web"}
+      - {name: wait-seconds, type: integer, description: "Wait this long for the login instead of blocking on ENTER; required when an agent launches the flow"}
+      - {name: wait-until-url-excludes, type: string, description: "With --wait-seconds, finish as soon as the address bar leaves this host (e.g. accounts.google.com)"}
+    output_schema: '{ "session": "...", "path": "tools/web/sessions/<name>.json", "url": "...", "waited_for": "enter|timer|url", "login_detected": true }'
+
+  - name: list-sessions
+    description: List saved sessions (names + metadata only, never contents).
+    output_schema: '{ "sessions": [ {name, bytes, modified, persistent} ], "count": 0, "dir": "..." }'
+
+  - name: delete-session
+    description: >
+      Delete ALL of a saved session's artifacts - the storageState file, the
+      persistent <name>.profile/ directory, and the <name>.cookies.json sidecar.
+      Deleting a session destroys a login that only a human at a browser can
+      re-establish, so this PREVIEWS by default and removes nothing unless
+      --confirm is passed (the unconfirmed call is the dry run).
+    args:
+      - {name: name, type: string, required: true, description: Session name to delete}
+      - {name: confirm, type: boolean, description: "Actually delete; without it the call only previews would_remove"}
+    output_schema: '{ "session": "...", "deleted": true, "existed": true, "removed": ["state","profile","cookies"], "would_remove": ["..."], "confirmation_required": true, "failed": {}, "broker_stopped": "..." }'
+
+  - name: run
+    description: >
+      Load a saved session, optionally navigate to --url, then execute a
+      declarative step list (--actions JSON array or --actions-file). Returns
+      collected outputs. Step schema (each step has a "do"):
+      goto{url,timeout?} | click{selector,timeout?,force?} | fill{selector,text,timeout?} |
+      press{key,selector?} | type{text,selector?,timeout?} | wait{ms} |
+      wait_for{selector,timeout?} | extract_text{selector?,name,timeout?} |
+      extract_attr{selector,attr,name,timeout?} | viewport{width,height} |
+      screenshot{path,full_page?}.
+      'type' drives real keyboard events (canvas grids like Google Sheets where
+      cells aren't DOM); 'wait' is a fixed ms delay (autosave settle).
+      Headless by default; --headed to watch. --hold-seconds keeps a headed
+      browser open after the steps so a HUMAN can review what was staged and
+      click the irreversible control (Submit/Confirm/Send) themselves; an
+      expired hold is still a successful run.
+    args:
+      - {name: session, type: string, required: true, description: Saved session name to load}
+      - {name: url, type: string, description: Optional URL to visit before running the steps}
+      - {name: actions, type: string, description: "Inline JSON array of steps"}
+      - {name: actions-file, type: string, description: "Path to a JSON file containing the steps array"}
+      - {name: headed, type: boolean, default: false, description: "Show the browser window (default headless)"}
+      - {name: channel, type: string, description: "Chromium channel: 'chrome' or 'msedge'"}
+      - {name: hold-seconds, type: integer, description: "After the last step keep the headed browser open up to N seconds for a human to finish the action; requires headed"}
+      - {name: hold-until-selector, type: string, description: "End the hold early once this selector appears; requires hold-seconds"}
+      - {name: hold-until-url-excludes, type: string, description: "End the hold early once the address bar leaves this host; requires hold-seconds"}
+      - {name: direct, type: boolean, default: false, description: "Bypass the owning tool serializing broker and drive the browser in-process (backup; only safe when that broker is stopped)"}
+    output_schema: '{ "session": "...", "results": {"name": "value"}, "screenshots": ["..."], "final_url": "...", "hold": {"held_seconds": 0, "completed": false, "reason": "selector|url|timeout"} }'
+
+  - name: get-text
+    description: "Convenience: load a session, open --url, return visible text (whole page or --selector). For lead/topic research."
+    args:
+      - {name: session, type: string, required: true, description: Saved session name to load}
+      - {name: url, type: string, required: true, description: URL to navigate to}
+      - {name: selector, type: string, description: Optional CSS selector; default reads the whole page body}
+      - {name: wait, type: string, description: Optional selector to await before reading (for SPAs)}
+      - {name: headed, type: boolean, default: false, description: Show the browser window}
+      - {name: channel, type: string, description: "Chromium channel: 'chrome' or 'msedge'"}
+      - {name: direct, type: boolean, default: false, description: "Bypass the owning tool serializing broker and drive the browser in-process (backup; only safe when that broker is stopped)"}
+    output_schema: '{ "session": "...", "url": "...", "selector": null, "text": "...", "final_url": "..." }'
+
+  - name: screenshot
+    description: "Load a session, open --url, save a screenshot to --out."
+    args:
+      - {name: session, type: string, required: true, description: Saved session name to load}
+      - {name: url, type: string, required: true, description: URL to capture}
+      - {name: out, type: string, required: true, description: "Output image path (.png)"}
+      - {name: viewport-only, type: boolean, default: false, description: "Capture only the viewport (default: full page)"}
+      - {name: wait, type: string, description: Optional selector to await first}
+      - {name: headed, type: boolean, default: false, description: Show the browser window}
+      - {name: channel, type: string, description: "Chromium channel: 'chrome' or 'msedge'"}
+      - {name: direct, type: boolean, default: false, description: "Bypass the owning tool serializing broker and drive the browser in-process (backup; only safe when that broker is stopped)"}
+    output_schema: '{ "session": "...", "url": "...", "path": "...", "final_url": "..." }'
+
+  - name: archive-document
+    description: >
+      Capture a published document (web page or PDF) as a reviewable evidence set:
+      the ORIGINAL response bytes untouched, a self-contained HTML rendering with
+      stylesheets inlined so it opens offline with its layout, and a text
+      extraction for searching and quoting. Every readable artefact carries a
+      provenance header (title, the date the document states about itself, source
+      URL, fetch timestamp, sha256 of the original) so a later capture can be
+      compared against it. Unauthenticated fetch only - a login-gated document is
+      recorded as unreachable, never substituted with a summary.
+    args:
+      - {name: url, type: string, description: "URL of the document to capture (exactly one of --url/--file)"}
+      - {name: file, type: string, description: "Local file to archive instead of fetching (an already-downloaded original)"}
+      - {name: source-url, type: string, description: "With --file: the URL the file came from, recorded in the header"}
+      - {name: out-dir, type: string, required: true, description: "Base directory; a subfolder named --name is created inside it"}
+      - {name: name, type: string, required: true, description: "Folder and file basename for the document (a slug, not a URL)"}
+      - {name: title, type: string, description: "Published title override; default reads <title>/<h1>"}
+      - {name: timeout, type: integer, default: 60, description: "Per-request timeout in seconds"}
+      - {name: no-self-contained, type: boolean, default: false, description: "Skip the stylesheet-inlined copy (original + extraction only)"}
+    output_schema: '{ "name": "...", "dir": "...", "url": "...", "final_url": "...", "status": 200, "kind": "html|pdf", "title": "...", "fetched_at": "...", "bytes": 0, "stylesheets_inlined": 0, "chars_extracted": 0, "document_date_candidates": [{"date": "...", "context": "..."}], "files": {"original": "...", "self_contained": "...", "extraction": "..."}, "sha256": {"original": "...", "self_contained": "...", "extraction": "..."} }'
+
+  - name: page-contacts
+    description: >
+      The contact details a PUBLIC page publishes, read with one plain HTTP GET (no
+      browser, no session, nothing clicked): emails from mailto links and visible
+      text (including "name [at] domain [dot] com"), profile links grouped by
+      platform (linkedin, x, youtube, instagram, ...), link-in-bio pages, and
+      affiliate-shaped links. Meant for link-in-bio pages and personal sites. A
+      4xx/5xx page returns reachable=false instead of an error.
+    args:
+      - {name: url, type: string, required: true, description: "Public page to read (link-in-bio, personal site)"}
+      - {name: timeout, type: integer, default: 20, description: "Request timeout in seconds"}
+    output_schema: '{ "url": "...", "final_url": "...", "status": 200, "content_type": "...", "reachable": true, "title": "...", "emails": ["..."], "links": {"linkedin": [], "x": [], "website": [], "link_in_bio": [], "...": []}, "affiliate_links": [ {url, host, network, program, param} ] }'
+
+  - name: render-pdf
+    description: "Render an HTML string/file to a PDF (session-less, headless Chromium page.pdf)."
+    args:
+      - {name: html, type: string, description: "Inline HTML string to render (exactly one of --html / --html-file)"}
+      - {name: html-file, type: string, description: "Path to an HTML file to render"}
+      - {name: out, type: string, required: true, description: "Output PDF path (.pdf)"}
+      - {name: format, type: string, default: A4, description: "Paper size: A4 (default) / Letter / Legal"}
+      - {name: width, type: string, description: "Custom page width as a CSS length, e.g. 1000mm (needs --height; overrides --format) - large-format print such as a roll-up or poster"}
+      - {name: height, type: string, description: "Custom page height as a CSS length, e.g. 2000mm (needs --width)"}
+      - {name: margin, type: string, description: "One CSS length for all four margins; 0 for full-bleed artwork. Default keeps the document margins (12/14/12/12 mm)"}
+    output_schema: '{ "out": "...", "bytes": 12345 }'
+
+examples:
+  - cmd: python scripts/run-tool.py web save-session --name linkedin --url https://www.linkedin.com/login
+    output: '{"session": "linkedin", "path": ".../tools/web/sessions/linkedin.json", "url": "https://www.linkedin.com/login"}'
+  - cmd: 'python scripts/run-tool.py web archive-document --url https://example.com/terms --out-dir documentation/legal/existing --name terms'
+    output: '{"name": "terms", "dir": "...", "kind": "html", "title": "Terms", "sha256": {"original": "..."}, "files": {"original": "...", "self_contained": "...", "extraction": "..."}}'
+  - cmd: python scripts/run-tool.py web list-sessions
+    output: '{"sessions": [{"name": "linkedin", "bytes": 4096, "modified": "2026-06-22T09:00:00"}], "count": 1, "dir": "..."}'
+  - cmd: 'python scripts/run-tool.py web get-text --session linkedin --url https://www.linkedin.com/in/someone --selector main'
+    output: '{"session": "linkedin", "url": "...", "selector": "main", "text": "...", "final_url": "..."}'
+  - cmd: 'python scripts/run-tool.py web run --session linkedin --actions "[{\"do\":\"goto\",\"url\":\"https://www.linkedin.com/feed\"},{\"do\":\"extract_text\",\"selector\":\"h1\",\"name\":\"headline\"}]"'
+    output: '{"session": "linkedin", "results": {"headline": "..."}, "screenshots": [], "final_url": "..."}'
+
+requires:
+  - name: playwright-chromium
+    kind: browser
+    why: >
+      every action that opens a browser. `uv sync` installs the Playwright PACKAGE,
+      not the browser binary - and Playwright is imported lazily, so the tool loads
+      and the tests pass while the first real action fails with browser_error.
+    check: '{python} -c "from playwright.sync_api import sync_playwright; p=sync_playwright().start(); p.chromium.executable_path; p.stop()"'
+    install: uv run playwright install chromium

procesio_cli/tools/xlsx/README.md

@@ -0,0 +1,34 @@
+# xlsx
+
+Read local Excel (`.xlsx` / `.xlsm`) workbooks. No credentials — operates on
+local files. Built from a one-off script per the "scripts become tools"
+directive, so reading Excel files is now a reusable, registered capability.
+
+Native Google Sheets are read with the **google-sheets** tool; this tool is for
+`.xlsx` blobs (e.g. files downloaded from Drive with `google-drive download-file`).
+
+## Actions
+
+```powershell
+# List sheets + dimensions
+python scripts/run-tool.py xlsx list-sheets --path "C:\path\book.xlsx"
+
+# Read one sheet as a JSON 2D array (empty rows skipped, trailing blanks trimmed)
+python scripts/run-tool.py xlsx read-sheet --path "C:\path\book.xlsx" --sheet "Data" --max-results 100
+
+# Dump the whole workbook to readable text
+python scripts/run-tool.py xlsx dump --path "C:\path\book.xlsx" --save out.txt
+```
+
+## Typical pipeline (Drive .xlsx -> read)
+
+```powershell
+python scripts/run-tool.py google-drive download-file --file-id <ID> --save book.xlsx
+python scripts/run-tool.py xlsx dump --path book.xlsx --save book.txt
+```
+
+## Notes
+- Cell values are JSON-safe; dates/times come back as ISO strings.
+- UTF-8 throughout (Romanian diacritics etc. are preserved).
+- `read-sheet` returns `{sheet, rows, truncated}`; `truncated` is true when
+  `--max-results` capped the output.

procesio_cli/tools/xlsx/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: xlsx
+description: Read local Excel (.xlsx/.xlsm) workbooks - list sheets, read a sheet as JSON, or dump the whole file to text. No credentials.
+---
+
+# xlsx
+
+Read local Excel (.xlsx/.xlsm) workbooks - list sheets, read a sheet as JSON, or dump the whole file to text. No credentials.
+
+## How to call it
+
+```bash
+python scripts/run-tool.py xlsx <action> [--args]
+```
+
+One JSON object on stdout for success; `{"error": {"code", "message", "details"}}` and a non-zero exit on failure. Progress and logs go to stderr only.
+
+## Actions
+
+| action | required args | what it does |
+|---|---|---|
+| `dump` | `--path` | Dump the whole workbook to readable pipe-delimited text. |
+| `list-sheets` | `--path` | List a workbook's sheets with row/column counts. |
+| `read-sheet` | `--path` | Read one sheet's rows as a JSON 2D array (trailing-empty cells trimmed, empty rows skipped). |
+
+---
+
+Generated from `tools/xlsx/tool.yaml` by `scripts/build-tool-skill.py`. Do not edit by hand — change the manifest and regenerate.

procesio_cli/tools/xlsx/main.py

@@ -0,0 +1,129 @@
+"""xlsx tool entrypoint - read local Excel (.xlsx/.xlsm) files. Action-dispatched.
+
+No credentials (local files only). Built from the original ad-hoc dump_xlsx.py,
+per the "scripts become tools" directive.
+
+Actions:
+  list-sheets --path <f>
+  read-sheet  --path <f> [--sheet NAME] [--max-rows N] [--raw]
+  dump        --path <f> [--save OUT.txt] [--max-rows N]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+TOOL_ROOT = Path(__file__).resolve().parent
+FRAMEWORK_ROOT = TOOL_ROOT.parents[1]
+_VENV_PY = FRAMEWORK_ROOT / ".venv" / "Scripts" / "python.exe"
+if _VENV_PY.exists() and Path(sys.executable).resolve() != _VENV_PY.resolve():
+    import subprocess
+    sys.exit(subprocess.run([str(_VENV_PY), __file__, *sys.argv[1:]]).returncode)
+
+if str(FRAMEWORK_ROOT) not in sys.path:
+    sys.path.insert(0, str(FRAMEWORK_ROOT))
+
+from tools._lib.io import emit, fail  # noqa: E402
+from tools.xlsx import reader  # noqa: E402
+
+
+class UsageError(Exception):
+    """Bad/invalid arguments -> invalid_argument, exit 2."""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):
+        raise UsageError(message)
+
+
+@dataclass
+class ActionDef:
+    func: Callable
+    add_args: Callable[[argparse.ArgumentParser], None]
+    description: str = ""
+
+
+def _list_sheets(args) -> dict:
+    return {"path": args.path, "sheets": reader.list_sheets(args.path)}
+
+
+def _read_sheet(args) -> dict:
+    return reader.read_sheet(args.path, args.sheet, max_rows=args.max_results)
+
+
+def _dump(args) -> dict:
+    text = reader.dump_text(args.path, max_rows=args.max_results)
+    if args.save:
+        out = Path(args.save).resolve()
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text, encoding="utf-8")
+        return {"savedTo": str(out), "characters": len(text)}
+    return {"text": text, "characters": len(text)}
+
+
+def _path_arg(p):
+    p.add_argument("--path", required=True, help="Local .xlsx/.xlsm file")
+
+
+def _read_args(p):
+    _path_arg(p)
+    p.add_argument("--sheet", help="Sheet name (default: first/active)")
+    p.add_argument("--max-results", type=int, help="Cap rows returned")
+
+
+def _dump_args(p):
+    _path_arg(p)
+    p.add_argument("--save", help="Write text dump here instead of inline")
+    p.add_argument("--max-results", type=int, help="Cap rows per sheet")
+
+
+ACTIONS = {
+    "list-sheets": ActionDef(_list_sheets, _path_arg,
+                             "List a workbook's sheets with row/column counts."),
+    "read-sheet": ActionDef(_read_sheet, _read_args,
+                            "Read one sheet's rows as a JSON 2D array."),
+    "dump": ActionDef(_dump, _dump_args,
+                      "Dump the whole workbook to readable text (--save or inline)."),
+}
+
+
+def dispatch(action: str, argv: list[str]) -> dict:
+    if action not in ACTIONS:
+        raise UsageError(f"unknown action: {action}. Known: {', '.join(sorted(ACTIONS))}")
+    defn = ACTIONS[action]
+    parser = _Parser(prog=f"xlsx {action}", description=defn.description)
+    defn.add_args(parser)
+    return defn.func(parser.parse_args(argv))
+
+
+def _classify(exc: Exception):
+    if isinstance(exc, UsageError):
+        return "invalid_argument", str(exc), 2
+    if isinstance(exc, FileNotFoundError):
+        return "not_found", str(exc), 1
+    if isinstance(exc, ValueError):
+        return "invalid_argument", str(exc), 2
+    return "error", str(exc) or exc.__class__.__name__, 1
+
+
+def main(argv=None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Actions:", file=sys.stderr)
+        for name in sorted(ACTIONS):
+            print(f"  {name:<14} {ACTIONS[name].description}", file=sys.stderr)
+        sys.exit(0)
+    action, rest = argv[0], argv[1:]
+    try:
+        result = dispatch(action, rest)
+    except Exception as exc:  # noqa: BLE001
+        code, message, exit_code = _classify(exc)
+        fail(code, message, {}, exit_code)
+    emit(result)
+
+
+if __name__ == "__main__":
+    main()