maybeai-sheet-cli 0.3.2__tar.gz → 0.4.0__tar.gz

{maybeai_sheet_cli-0.3.2 → maybeai_sheet_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maybeai-sheet-cli
-Version: 0.3.2
+Version: 0.4.0
 Summary: CLI for common MaybeAI spreadsheet operations
 Project-URL: Homepage, https://github.com/OmniMCP-AI/maybeai-sheet-cli
 Project-URL: Repository, https://github.com/OmniMCP-AI/maybeai-sheet-cli
@@ -138,11 +138,29 @@ Make a workbook public for viewers:
 mbs share visibility --doc-id abc123 --visibility public --public-permission viewer
 ```
 
+Rename a worksheet and inspect a destructive row delete before sending it:
+
+```bash
+mbs worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes
+```
+
+Search, style, inspect history, and export:
+
+```bash
+mbs range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
+mbs style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
+mbs formula calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
+mbs history list --doc-id abc123 --limit 10
+mbs file export --doc-id abc123 --out workbook.xlsx
+```
+
 ## Commands
 
 The preferred command groups are `workbook`, `worksheet`, `range`, `table`,
-`formula`, `share`, and `raw`. The older `sheet ...` commands remain available
-as compatibility aliases.
+`row`, `column`, `formula`, `style`, `history`, `file`, `share`, and `raw`.
+The older `sheet ...` commands remain available as compatibility aliases.
 
 ```text
 mbs
@@ -158,23 +176,57 @@ mbs
 │
 ├── worksheet
 │   ├── list               List worksheets in a workbook.
-│   └── create             Create a worksheet, optionally with starter values.
+│   ├── create             Create a worksheet, optionally with starter values.
+│   ├── rename             Rename a worksheet.
+│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
+│   ├── copy               Copy a worksheet.
+│   └── move               Move a worksheet to a zero-based index.
 │
 ├── range
 │   ├── read               Read a bounded A1 range.
 │   ├── write              Write a JSON matrix into an A1 range.
-│   └── clear              Clear an A1 range.
+│   ├── clear              Clear an A1 range.
+│   └── search             Search a worksheet with bounded results.
 │
 ├── table
 │   ├── headers            Read header row metadata.
 │   ├── append-rows        Append JSON row objects.
 │   └── upsert-rows        Upsert JSON row objects by key.
 │
+├── row
+│   ├── insert             Insert rows.
+│   ├── delete             Delete rows; requires --yes unless --dry-run.
+│   └── move               Move rows.
+│
+├── column
+│   ├── insert             Insert columns.
+│   ├── delete             Delete columns; requires --yes unless --dry-run.
+│   ├── move               Move columns.
+│   └── width              Set column width.
+│
 ├── formula
 │   ├── read               Read formulas with FORMULA render mode.
 │   ├── set                Set one formula cell.
 │   ├── batch-set          Set formula ranges from a JSON operations file.
-│   └── recalculate        Recalculate formulas for a worksheet/workbook.
+│   ├── recalculate        Recalculate formulas for a worksheet/workbook.
+│   ├── calculate          Calculate one formula cell.
+│   └── lineage            Trace formula lineage for one cell.
+│
+├── style
+│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
+│   ├── auto-filter set    Set worksheet auto-filter range.
+│   ├── auto-filter remove Remove worksheet auto-filter.
+│   ├── columns-width      Set column widths.
+│   └── rows-height        Set row heights.
+│
+├── history
+│   ├── list               List workbook versions with bounded output.
+│   └── read               Read a workbook version.
+│
+├── file
+│   ├── export             Export workbook bytes to --out.
+│   ├── list               List files with bounded output.
+│   └── search             Search files with bounded output.
 │
 ├── share
 │   ├── visibility         Set workbook visibility.
@@ -210,7 +262,11 @@ Relationship guide:
 - Use `worksheet` for tab lifecycle operations.
 - Use `range` for coordinate-based reads and writes.
 - Use `table` when data is row-object shaped and keyed by headers.
+- Use `row` and `column` for structural row/column changes.
 - Use `formula` when preserving or changing formulas matters.
+- Use `style` for layout operations like freeze panes, filter ranges, widths, and heights.
+- Use `history` for read-only version inspection.
+- Use `file` for export/list/search file operations.
 - Use `share` for visibility and collaborator access.
 - Use `raw post` only when a first-class command does not exist yet.
 

{maybeai_sheet_cli-0.3.2 → maybeai_sheet_cli-0.4.0}/README.md

@@ -114,11 +114,29 @@ Make a workbook public for viewers:
 mbs share visibility --doc-id abc123 --visibility public --public-permission viewer
 ```
 
+Rename a worksheet and inspect a destructive row delete before sending it:
+
+```bash
+mbs worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
+mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes
+```
+
+Search, style, inspect history, and export:
+
+```bash
+mbs range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
+mbs style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
+mbs formula calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
+mbs history list --doc-id abc123 --limit 10
+mbs file export --doc-id abc123 --out workbook.xlsx
+```
+
 ## Commands
 
 The preferred command groups are `workbook`, `worksheet`, `range`, `table`,
-`formula`, `share`, and `raw`. The older `sheet ...` commands remain available
-as compatibility aliases.
+`row`, `column`, `formula`, `style`, `history`, `file`, `share`, and `raw`.
+The older `sheet ...` commands remain available as compatibility aliases.
 
 ```text
 mbs
@@ -134,23 +152,57 @@ mbs
 │
 ├── worksheet
 │   ├── list               List worksheets in a workbook.
-│   └── create             Create a worksheet, optionally with starter values.
+│   ├── create             Create a worksheet, optionally with starter values.
+│   ├── rename             Rename a worksheet.
+│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
+│   ├── copy               Copy a worksheet.
+│   └── move               Move a worksheet to a zero-based index.
 │
 ├── range
 │   ├── read               Read a bounded A1 range.
 │   ├── write              Write a JSON matrix into an A1 range.
-│   └── clear              Clear an A1 range.
+│   ├── clear              Clear an A1 range.
+│   └── search             Search a worksheet with bounded results.
 │
 ├── table
 │   ├── headers            Read header row metadata.
 │   ├── append-rows        Append JSON row objects.
 │   └── upsert-rows        Upsert JSON row objects by key.
 │
+├── row
+│   ├── insert             Insert rows.
+│   ├── delete             Delete rows; requires --yes unless --dry-run.
+│   └── move               Move rows.
+│
+├── column
+│   ├── insert             Insert columns.
+│   ├── delete             Delete columns; requires --yes unless --dry-run.
+│   ├── move               Move columns.
+│   └── width              Set column width.
+│
 ├── formula
 │   ├── read               Read formulas with FORMULA render mode.
 │   ├── set                Set one formula cell.
 │   ├── batch-set          Set formula ranges from a JSON operations file.
-│   └── recalculate        Recalculate formulas for a worksheet/workbook.
+│   ├── recalculate        Recalculate formulas for a worksheet/workbook.
+│   ├── calculate          Calculate one formula cell.
+│   └── lineage            Trace formula lineage for one cell.
+│
+├── style
+│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
+│   ├── auto-filter set    Set worksheet auto-filter range.
+│   ├── auto-filter remove Remove worksheet auto-filter.
+│   ├── columns-width      Set column widths.
+│   └── rows-height        Set row heights.
+│
+├── history
+│   ├── list               List workbook versions with bounded output.
+│   └── read               Read a workbook version.
+│
+├── file
+│   ├── export             Export workbook bytes to --out.
+│   ├── list               List files with bounded output.
+│   └── search             Search files with bounded output.
 │
 ├── share
 │   ├── visibility         Set workbook visibility.
@@ -186,7 +238,11 @@ Relationship guide:
 - Use `worksheet` for tab lifecycle operations.
 - Use `range` for coordinate-based reads and writes.
 - Use `table` when data is row-object shaped and keyed by headers.
+- Use `row` and `column` for structural row/column changes.
 - Use `formula` when preserving or changing formulas matters.
+- Use `style` for layout operations like freeze panes, filter ranges, widths, and heights.
+- Use `history` for read-only version inspection.
+- Use `file` for export/list/search file operations.
 - Use `share` for visibility and collaborator access.
 - Use `raw post` only when a first-class command does not exist yet.
 

{maybeai_sheet_cli-0.3.2 → maybeai_sheet_cli-0.4.0}/docs/agent-friendly-command-tree.md

@@ -10,6 +10,10 @@ give agents a predictable object model:
 workbook -> worksheet -> range/table/formula/style/chart/image/history
 ```
 
+For source-oriented inspection, use a separate `source` surface. A source can be
+an Excel worksheet range, a multidimensional worksheet view, or a native table;
+that is broader than `table headers`.
+
 The CLI should call the routed MaybeAI Sheet API through `fastestai-playground`
 by default, not engine servers directly. `excelize-mcp` and `SheetTable` remain
 execution engines behind the routing layer.
@@ -78,6 +82,12 @@ Why these first:
 - They support a manifest-first workflow, which reduces wrong-sheet and wrong-gid
   mistakes.
 
+Recommended next API after the manifest/read/write path is stable:
+
+```text
+mbs source schema -> POST /api/v1/excel/source_schema
+```
+
 ## Typical Command Examples
 
 These are representative examples only. The CLI does not need a bespoke example
@@ -91,6 +101,19 @@ mbs workbook manifest --doc-id "$DOC_ID"
 mbs worksheet list --doc-id "$DOC_ID"
 ```
 
+Inspect a source schema before reading or transforming it:
+
+```bash
+mbs source schema \
+  --doc-id "$DOC_ID" \
+  --mode excel_worksheet \
+  --worksheet-name "Actuals" \
+  --range "A1:Z5000" \
+  --header-row 1 \
+  --sample-rows 50 \
+  --infer-types
+```
+
 Create workbook or worksheet:
 
 ```bash
@@ -177,6 +200,12 @@ mbs formula recalculate \
   --doc-id "$DOC_ID" \
   --worksheet-name "Model"
 
+mbs formula calculate \
+  --doc-id "$DOC_ID" \
+  --worksheet-name "Model" \
+  --cell "E2" \
+  --formula "=SUM(B2:D2)"
+
 mbs formula lineage \
   --doc-id "$DOC_ID" \
   --worksheet-name "Model" \
@@ -222,15 +251,15 @@ mbs worksheet copy \
 mbs row insert \
   --doc-id "$DOC_ID" \
   --worksheet-name "Sheet1" \
-  --start 5 \
+  --row 5 \
   --count 3 \
   --dry-run
 
 mbs column width \
   --doc-id "$DOC_ID" \
   --worksheet-name "Sheet1" \
-  --start "A" \
-  --end "D" \
+  --start-column "A" \
+  --end-column "D" \
   --width 18
 
 # Search and worksheet bounds
@@ -387,6 +416,7 @@ power-pivot
 ```text
 mbs
 ├── workbook
+├── source
 ├── worksheet
 ├── range
 ├── table
@@ -436,11 +466,126 @@ workbook import
 Notes:
 
 - `manifest` should be the default first step for agents.
+- Current CLI route: `POST /api/v1/excel/workbook_profile`.
+- Request shape should include the resolved workbook identity:
+
+  ```json
+  {
+    "document_id": "wb_rev",
+    "uri": "https://www.maybe.ai/docs/spreadsheets/d/wb_rev"
+  }
+  ```
+
+- `manifest` is for workbook-level structure: worksheets, gids, dimensions,
+  engine/profile metadata, and routeability hints.
 - `capabilities` should eventually return routeable capabilities by engine:
   read/write/style/sql/formula/export.
 - Current local CLI maps both `manifest` and `capabilities` to
   `/api/v1/excel/workbook_profile`; this should be normalized later.
 
+## Source Commands
+
+Source commands inspect a data source before an agent reads, maps, joins, or
+transforms it. The source may be an Excel worksheet range, a multidimensional
+worksheet, or a native table.
+
+```text
+mbs source schema                     PLAN
+mbs source sample                     PLAN
+mbs source profile                    PLAN
+```
+
+Suggested MVP:
+
+```text
+source schema
+```
+
+Recommended routed API:
+
+```text
+POST /api/v1/excel/source_schema
+```
+
+Recommended CLI:
+
+```bash
+mbs source schema \
+  --doc-id "$DOC_ID" \
+  --mode excel_worksheet \
+  --worksheet-name "Actuals" \
+  --range "A1:Z5000" \
+  --header-row 1 \
+  --sample-rows 50 \
+  --infer-types
+```
+
+Equivalent tool contract:
+
+```json
+{
+  "workbook_id": "wb_rev",
+  "source": {
+    "mode": "excel_worksheet",
+    "worksheet": {
+      "name": "Actuals",
+      "range": "A1:Z5000",
+      "header_row": 1
+    }
+  },
+  "infer_types": true,
+  "sample_rows": 50
+}
+```
+
+Expected output:
+
+```json
+{
+  "source_id": "src_actuals",
+  "grain_hint": "one row per transaction",
+  "columns": [
+    {
+      "name": "date",
+      "type": "date",
+      "nullable": false,
+      "examples": ["2026-05-01"]
+    },
+    {
+      "name": "amount",
+      "type": "currency",
+      "nullable": false,
+      "summary": {
+        "min": 0,
+        "max": 102320.5
+      }
+    }
+  ],
+  "warnings": [
+    {
+      "code": "merged_header_detected",
+      "message": "Rows 1-2 look like multi-row headers"
+    }
+  ]
+}
+```
+
+API fit:
+
+- `workbook manifest` / `POST /api/v1/excel/workbook_profile` is the right API
+  for workbook manifest discovery.
+- `table headers`, `range read`, and `workbook manifest` can approximate source
+  schema for simple Excel worksheets, but they do not represent native tables or
+  multidimensional worksheet semantics as one contract.
+- Add `POST /api/v1/excel/source_schema` in play-be when the backend can infer
+  types, examples, nullability, warnings, and grain hints consistently.
+- The CLI should expose this as `mbs source schema`, not `mbs workbook manifest`
+  and not `mbs table headers`, because the source abstraction crosses workbook,
+  worksheet, and native table boundaries.
+- Until the routed endpoint exists, keep this command in `PLAN` status or build
+  an Excel-worksheet-only fallback that calls `workbook_profile`, `read_headers`,
+  and a bounded `read_sheet` sample.
+
 ## Worksheet Commands
 
 Worksheet commands manage sheet tabs and worksheet-level metadata.
@@ -625,7 +770,7 @@ mbs formula read                       NOW
 mbs formula set                        NOW
 mbs formula batch-set                  NOW
 mbs formula recalculate                NOW
-mbs formula compile                    API
+mbs formula compile                    PLAN
 mbs formula calculate                  API
 mbs formula fill                       API
 mbs formula lineage                    API
@@ -646,7 +791,6 @@ formula recalculate
 Suggested phase 2:
 
 ```text
-formula compile
 formula calculate
 formula lineage
 ```
@@ -664,6 +808,9 @@ Agent-friendly requirements:
   value after write.
 - `formula batch-set` should support a JSON operations file.
 - `formula recalculate` should allow workbook or worksheet scope.
+- `formula calculate` maps to `POST /api/v1/excel/calc-formula`; live play-be
+  verification requires both `cellAddress` and `formula`, exposed as CLI
+  `--cell` and `--formula`.
 - `formula lineage` should be SheetTable-aware and return dependencies in a
   stable JSON shape.
 - `formula lineage` maps to confirmed routed Playground API
@@ -1128,6 +1275,7 @@ Implement only after confirming the command has a routed public API in
 `fastestai-playground`:
 
 ```text
+source schema, if POST /api/v1/excel/source_schema is added
 worksheet rename/delete/copy/move
 row insert/delete/move
 column insert/delete/move/width