gws-axi 0.15.0 → 0.16.0

package/README.md

@@ -1,12 +1,12 @@
 # gws-axi
 
-Agent-ergonomic CLI for Google Workspace — Gmail, Calendar, Docs, Drive, and Slides behind a single command, built to the [AXI standard](https://axi.md): [TOON](https://toonformat.dev/)-formatted output, contextual next-step suggestions, idempotent mutations, and multi-account safety by default.
+Agent-ergonomic CLI for Google Workspace — Gmail, Calendar, Docs, Drive, Slides, and Sheets behind a single command, built to the [AXI standard](https://axi.md): [TOON](https://toonformat.dev/)-formatted output, contextual next-step suggestions, idempotent mutations, and multi-account safety by default.
 
 Designed for use by AI agents. Every response is structured, every error names a specific fix, and write operations lock to the explicit account when multiple are authenticated — so two agents in parallel sessions can't silently touch the wrong mailbox.
 
 ## Status
 
-Read coverage is complete across all five services; write coverage is rolling out service by service.
+Read coverage is complete across all six services; write coverage is rolling out service by service.
 
 | Service | Reads | Writes |
 | --- | --- | --- |
@@ -14,7 +14,8 @@ Read coverage is complete across all five services; write coverage is rolling ou
 | **Gmail** | ✅ search · read · labels · download | ✅ triage · draft · labels · filters  ·  ✋ `send` out of scope |
 | **Docs** | ✅ read · find · comments · download · revisions · diff | 🚧 append · insert-text · delete-range |
 | **Drive** | ✅ ls · get · search · permissions · download · revisions · activity | 🟡 upload · mkdir  ·  🚧 create · copy · move · rename · delete |
-| **Slides** | ✅ get · page · summarize | 🚧 create · update |
+| **Slides** | ✅ get · page · summarize · comments | 🚧 create · update |
+| **Sheets** | ✅ read · comments | 🚧 update · append · clear · create · add-tab |
 
 <sub>✅ shipped · 🟡 partial · 🚧 planned · ✋ out of scope by design</sub>
 
@@ -87,7 +88,7 @@ To make sure agents reach for `gws-axi` instead of stale alternatives, also cons
   ```markdown
   ## Google Workspace
 
-  Use `gws-axi` for ALL Google Calendar, Gmail, Docs, Drive, and Slides
+  Use `gws-axi` for ALL Google Calendar, Gmail, Docs, Drive, Slides, and Sheets
   interactions. Check the SessionStart `gws-axi` line for current auth
   state; run `gws-axi --help` for the command surface. Prefer this over
   any other Google integrations.
@@ -241,8 +242,26 @@ gws-axi drive upload ./edited.md --convert --update <docId> --account you@exampl
 gws-axi slides get <presentationId>               # deck metadata + slide list
 gws-axi slides page <presentationId> <slideId>    # one slide's content
 gws-axi slides summarize <presentationId>         # all slides condensed to text per slide
+gws-axi slides comments <presentationId>          # review comments (Drive comments)
 ```
 
+<sub>Embedded hyperlinks in slide text resolve inline as markdown `[text](url)` (with `links_resolved: N` in the header); images/videos are counted, not inlined.</sub>
+
+### Sheets
+
+A spreadsheet's tabs are its sheets, so `sheets read` mirrors `docs read`: it lists the tabs, and renders one tab's grid into context. Embedded links resolve inline as markdown `[text](url)`; cell notes come back in a `notes[]` block.
+
+```bash
+gws-axi sheets read <spreadsheetId>                       # single tab renders; multi-tab lists tabs to pick
+gws-axi sheets read <spreadsheetId> --tab Costs           # by tab title (or numeric gid)
+gws-axi sheets read <spreadsheetId> --tab Costs --range A1:D50   # scope to an A1 range
+gws-axi sheets read <spreadsheetId> --header-row          # promote row 1 to column names (auto for a frozen top row; --raw to force letters)
+gws-axi sheets read <spreadsheetId> --tab Costs --full    # don't cap at 50 rows
+gws-axi sheets comments <spreadsheetId>                   # review comments (Drive comments)
+```
+
+<sub>Cell values are the displayed strings (not formulas). The new `spreadsheets` scope means existing accounts must `gws-axi auth login` once.</sub>
+
 ### Multi-account with write protection
 
 gws-axi supports multiple Google accounts under one OAuth client. When two or more are authenticated, write operations require `--account <email>` explicitly — silent wrong-account mutations are impossible:
@@ -279,6 +298,7 @@ help[2]:
 - **Docs writes** (`append`, `insert-text`, `delete-range`, etc.): scaffolded as `NOT_IMPLEMENTED`. The next frontier.
 - **Drive writes**: `upload` and `mkdir` are shipped; `create` / `copy` / `move` / `rename` / `delete` are still scaffolded as `NOT_IMPLEMENTED`.
 - **Slides writes**: still scaffolded as `NOT_IMPLEMENTED` (reads are complete).
+- **Sheets writes** (`update`, `append`, `clear`, `create`, `add-tab`): scaffolded as `NOT_IMPLEMENTED`; `read` (with inline-markdown links + cell notes) and `comments` are shipped.
 - **Testing-mode tokens** still expire every 7 days *if* you haven't published your OAuth app yet. Run `gws-axi auth publish` for the walkthrough — it covers the single-developer Production flow and removes the expiry once you've re-auth'd each account.
 
 ## Contributing

package/dist/src/auth/scopes.d.ts

@@ -5,6 +5,7 @@ export declare const SERVICE_SCOPES: {
     readonly docs: "https://www.googleapis.com/auth/documents";
     readonly drive: "https://www.googleapis.com/auth/drive";
     readonly slides: "https://www.googleapis.com/auth/presentations";
+    readonly sheets: "https://www.googleapis.com/auth/spreadsheets";
 };
 export type ServiceName = keyof typeof SERVICE_SCOPES;
 export interface AdditionalScope {

package/dist/src/auth/scopes.js

@@ -5,6 +5,7 @@ export const SERVICE_SCOPES = {
     docs: "https://www.googleapis.com/auth/documents",
     drive: "https://www.googleapis.com/auth/drive",
     slides: "https://www.googleapis.com/auth/presentations",
+    sheets: "https://www.googleapis.com/auth/spreadsheets",
 };
 export const ADDITIONAL_SCOPE_INFO = [
     {
@@ -21,13 +22,14 @@ export const ADDITIONAL_SCOPE_INFO = [
     },
 ];
 export const ADDITIONAL_SCOPES = ADDITIONAL_SCOPE_INFO.map((s) => s.scope);
-export const SERVICES = ["gmail", "calendar", "docs", "drive", "slides"];
+export const SERVICES = ["gmail", "calendar", "docs", "drive", "slides", "sheets"];
 export const REQUIRED_APIS = {
     gmail: "gmail.googleapis.com",
     calendar: "calendar-json.googleapis.com",
     docs: "docs.googleapis.com",
     drive: "drive.googleapis.com",
     slides: "slides.googleapis.com",
+    sheets: "sheets.googleapis.com",
 };
 // APIs required beyond the per-service REQUIRED_APIS map. The Drive Activity
 // API is a distinct service backing the `drive activity` command — it must be

package/dist/src/auth/scopes.js.map

@@ -1 +1 @@
-{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK,EAAE,8CAA8C;IACrD,QAAQ,EAAE,0CAA0C;IACpD,IAAI,EAAE,2CAA2C;IACjD,KAAK,EAAE,uCAAuC;IAC9C,MAAM,EAAE,+CAA+C;CAC/C,CAAC;AAoBX,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD;QACE,KAAK,EAAE,sDAAsD;QAC7D,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,yBAAyB;KACtC;IACD;QACE,6EAA6E;QAC7E,mFAAmF;QACnF,KAAK,EAAE,yDAAyD;QAChE,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,yBAAyB;KACtC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE3E,MAAM,CAAC,MAAM,QAAQ,GAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAExF,MAAM,CAAC,MAAM,aAAa,GAAgC;IACxD,KAAK,EAAE,sBAAsB;IAC7B,QAAQ,EAAE,8BAA8B;IACxC,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,sBAAsB;IAC7B,MAAM,EAAE,uBAAuB;CAChC,CAAC;AAEF,6EAA6E;AAC7E,8EAA8E;AAC9E,yCAAyC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,8BAA8B,CAAU,CAAC;AAEzE,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,GAAG,iBAAiB,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,GAAG,eAAe,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../../src/auth/scopes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAU,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK,EAAE,8CAA8C;IACrD,QAAQ,EAAE,0CAA0C;IACpD,IAAI,EAAE,2CAA2C;IACjD,KAAK,EAAE,uCAAuC;IAC9C,MAAM,EAAE,+CAA+C;IACvD,MAAM,EAAE,8CAA8C;CAC9C,CAAC;AAoBX,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD;QACE,KAAK,EAAE,sDAAsD;QAC7D,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,yBAAyB;KACtC;IACD;QACE,6EAA6E;QAC7E,mFAAmF;QACnF,KAAK,EAAE,yDAAyD;QAChE,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,yBAAyB;KACtC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE3E,MAAM,CAAC,MAAM,QAAQ,GAAkB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,aAAa,GAAgC;IACxD,KAAK,EAAE,sBAAsB;IAC7B,QAAQ,EAAE,8BAA8B;IACxC,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,sBAAsB;IAC7B,MAAM,EAAE,uBAAuB;IAC/B,MAAM,EAAE,uBAAuB;CAChC,CAAC;AAEF,6EAA6E;AAC7E,8EAA8E;AAC9E,yCAAyC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,8BAA8B,CAAU,CAAC;AAEzE,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,GAAG,iBAAiB,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,GAAG,eAAe,CAAC,CAAC;AAC/D,CAAC"}

package/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
-export declare const TOP_HELP = "usage: gws-axi [command] [args] [flags]\ncommands[9]:\n  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides, setup\nflags[2]:\n  --help, -v/-V/--version\nexamples:\n  gws-axi\n  gws-axi auth setup\n  gws-axi doctor\n  gws-axi calendar events\n  gws-axi setup hooks\n";
+export declare const TOP_HELP = "usage: gws-axi [command] [args] [flags]\ncommands[10]:\n  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides, sheets, setup\nflags[2]:\n  --help, -v/-V/--version\nexamples:\n  gws-axi\n  gws-axi auth setup\n  gws-axi doctor\n  gws-axi calendar events\n  gws-axi setup hooks\n";
 export declare function main(): Promise<void>;

package/dist/src/cli.js

@@ -10,12 +10,13 @@ import { gmailCommand } from "./commands/gmail.js";
 import { docsCommand } from "./commands/docs.js";
 import { driveCommand } from "./commands/drive.js";
 import { slidesCommand } from "./commands/slides.js";
+import { sheetsCommand } from "./commands/sheets.js";
 import { setupCommand, SETUP_HELP } from "./commands/setup.js";
-const DESCRIPTION = "Agent ergonomic CLI for Google Workspace. Unified interface for Gmail, Calendar, Docs, Drive, and Slides with agent-guided OAuth setup.";
+const DESCRIPTION = "Agent ergonomic CLI for Google Workspace. Unified interface for Gmail, Calendar, Docs, Drive, Slides, and Sheets with agent-guided OAuth setup.";
 const VERSION = readPackageVersion();
 export const TOP_HELP = `usage: gws-axi [command] [args] [flags]
-commands[9]:
-  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides, setup
+commands[10]:
+  (none)=home, auth, doctor, calendar, gmail, docs, drive, slides, sheets, setup
 flags[2]:
   --help, -v/-V/--version
 examples:
@@ -47,6 +48,7 @@ export async function main() {
             docs: docsCommand,
             drive: driveCommand,
             slides: slidesCommand,
+            sheets: sheetsCommand,
             setup: setupCommand,
         },
         getCommandHelp: (command) => COMMAND_HELP[command],

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,WAAW,GACf,yIAAyI,CAAC;AAE5I,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;CAWvB,CAAC;AAEF,0EAA0E;AAC1E,0EAA0E;AAC1E,iEAAiE;AACjE,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,SAAS,CAAC;QACd,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,QAAQ;QACtB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW,EAAE;QAC/B,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE,eAAe;YACzB,KAAK,EAAE,YAAY;YACnB,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,aAAa;YACrB,KAAK,EAAE,YAAY;SACpB;QACD,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;KACnD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,SAAS,IAAI;QACtB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACvC,EAAE,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAEzD,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,WAAW,GACf,iJAAiJ,CAAC;AAEpJ,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;CAWvB,CAAC;AAEF,0EAA0E;AAC1E,0EAA0E;AAC1E,iEAAiE;AACjE,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,SAAS,CAAC;QACd,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,QAAQ;QACtB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW,EAAE;QAC/B,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE,eAAe;YACzB,KAAK,EAAE,YAAY;YACnB,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,aAAa;YACrB,KAAK,EAAE,YAAY;SACpB;QACD,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;KACnD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,SAAS,IAAI;QACtB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACvC,EAAE,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAEzD,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC"}

package/dist/src/commands/docs/comments.d.ts

@@ -1,2 +1,13 @@
 export declare const COMMENTS_HELP = "usage: gws-axi docs comments <documentId> [flags]\nargs[1]:\n  <documentId>         The Google Doc ID (from the URL after /d/)\nflags[4]:\n  --include-resolved   Also show comments that have been resolved\n  --full               Don't truncate comment/reply bodies (default cap: 500 chars)\n  --limit <n>          Max comments to return (default: 50)\n  --account <email>    Account override when 2+ are configured\nexamples:\n  gws-axi docs comments 1BxAbc...\n  gws-axi docs comments 1BxAbc... --include-resolved --full\noutput:\n  A `comments[N]{id,author,created,resolved,quoted_content,body,reply_count}`\n  list and (when any comment has replies) a sibling `replies[N]{comment,author,created,body}`\n  table keyed by parent comment id. Bodies and quoted_content are truncated\n  at 500 chars unless --full is passed.\nnotes:\n  `quoted_content` is the exact text in the doc that the comment is anchored\n  to \u2014 important for agents to know what the comment is *about*. Comments\n  without an anchor (overall-document comments) will have an empty value.\n";
-export declare function docsCommentsCommand(account: string, args: string[]): Promise<string>;
+/**
+ * Options for aliasing this Drive-comments handler onto another resource type
+ * (e.g. `sheets comments`). Drive comments are file-type-agnostic, so the only
+ * per-service differences are cosmetic: the header label and the not-found code.
+ */
+export interface CommentsOptions {
+    /** Header/message noun, e.g. "document" (default) or "spreadsheet". */
+    resource?: string;
+    /** Domain error code for a 404, e.g. "DOCUMENT_NOT_FOUND" (default). */
+    notFoundCode?: string;
+}
+export declare function docsCommentsCommand(account: string, args: string[], opts?: CommentsOptions): Promise<string>;

package/dist/src/commands/docs/comments.js

@@ -91,7 +91,10 @@ function replySchema(truncateAt) {
         },
     ];
 }
-export async function docsCommentsCommand(account, args) {
+export async function docsCommentsCommand(account, args, opts = {}) {
+    const resource = opts.resource ?? "document";
+    const Resource = resource.charAt(0).toUpperCase() + resource.slice(1);
+    const notFoundCode = opts.notFoundCode ?? "DOCUMENT_NOT_FOUND";
     const flags = parseFlags(args);
     const api = await driveClient(account);
     let data;
@@ -112,9 +115,9 @@ export async function docsCommentsCommand(account, args) {
             operation: "drive.comments.list",
         });
         if (translated.code === "NOT_FOUND") {
-            throw new AxiError(`Document '${flags.documentId}' not found (or ${account} doesn't have access)`, "DOCUMENT_NOT_FOUND", [
-                `Verify the document ID is correct (the portion of the URL after /d/)`,
-                `Confirm ${account} has at least view access to the document`,
+            throw new AxiError(`${Resource} '${flags.documentId}' not found (or ${account} doesn't have access)`, notFoundCode, [
+                `Verify the ${resource} ID is correct (the portion of the URL after /d/)`,
+                `Confirm ${account} has at least view access to the ${resource}`,
             ]);
         }
         throw translated;
@@ -138,13 +141,13 @@ export async function docsCommentsCommand(account, args) {
         body: r.content ?? "",
     })));
     const blocks = [];
-    blocks.push(renderObject({ account, document: flags.documentId }));
+    blocks.push(renderObject({ account, [resource]: flags.documentId }));
     if (commentRows.length === 0) {
         // AXI canonical empty-list: collapse to a scalar message under the
         // same field name (rather than `comments[0]:` + `message:` sibling).
         blocks.push(renderObject({
             comments: flags.includeResolved
-                ? "no comments on this document"
+                ? `no comments on this ${resource}`
                 : "no open comments (pass --include-resolved to include resolved)",
         }));
     }

package/dist/src/commands/docs/comments.js.map

@@ -1 +1 @@
-{"version":3,"file":"comments.js","sourceRoot":"","sources":["../../../../src/commands/docs/comments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../../../../src/commands/docs/comments.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/sheets/read.d.ts

@@ -0,0 +1,108 @@
+import { type FieldDef } from "../../output/index.js";
+export declare const READ_HELP = "usage: gws-axi sheets read <spreadsheetId> [flags]\nargs[1]:\n  <spreadsheetId>      The spreadsheet ID (the portion of the URL after /d/)\nflags[7]:\n  --tab <name|gid>     Tab to render (by title or numeric sheetId). Omit for a\n                       single-tab file; required to pick one in a multi-tab file\n  --range <A1>         Restrict to an A1 range within the tab (e.g. A1:D50). A\n                       tab-qualified range (Costs!A1:D50) makes --tab optional\n  --header-row         Force-promote the first fetched row to column names\n                       (rows[N]{\u2026}) instead of the A1 column-letter grid\n  --raw                Force the A1 column-letter grid, overriding header\n                       auto-detection\n  --full               Don't cap rendered rows (default cap: 50)\n  --max-rows <n>       Override the 50-row render cap (ignored with --full)\n  --account <email>    Account override when 2+ are configured\nexamples:\n  gws-axi sheets read 1AbC...\n  gws-axi sheets read 1AbC... --tab Costs\n  gws-axi sheets read 1AbC... --tab Costs --range A1:D50\n  gws-axi sheets read 1AbC... --tab Costs --header-row\noutput:\n  A `spreadsheet{id,title,tab?,tab_count?}` header, a `sheets[N]{gid,title,\n  index,rows,cols}` tabs listing (always shown), and \u2014 when a tab is selected \u2014\n  a `cells[N]{row,A,B,\u2026}` grid (real sheet row numbers + A1 column letters).\n  Embedded links are resolved inline as markdown `[text](url)` in the cells;\n  cell notes come back in a `notes[N]{cell,note}` block. Multi-tab files\n  without --tab return only the tabs listing so you can pick one.\nnotes:\n  A single frozen top row is auto-promoted to column names (header_source:\n  frozen-row in the output); pass --raw to override, or --header-row to force\n  promotion when no row is frozen.\n  Cell values are FORMATTED_VALUE (displayed strings), not formulas/raw numbers.\n  For review comments use `gws-axi sheets comments <id>` (Drive comments).\n  Operates on native Google Sheets only; uploaded .xlsx/.csv route to Drive.\n";
+/**
+ * Decide whether to promote the first fetched row to column names. Explicit
+ * flags win; otherwise a single frozen top row (a user-declared header) inside
+ * the fetched window auto-promotes. Multi-row frozen headers are left as-is —
+ * promoting only the first of several would misrepresent the data.
+ */
+export declare function resolveHeaderMode(opts: {
+    explicitHeader: boolean;
+    explicitRaw: boolean;
+    frozenRows: number;
+    originRow1: number;
+}): {
+    headerRow: boolean;
+    auto: boolean;
+};
+/** 0-based column index → A1 column letter (0→A, 25→Z, 26→AA). */
+export declare function columnLetter(index0: number): string;
+/** A1 column letters → 0-based column index (A→0, Z→25, AA→26). */
+export declare function columnIndex(letters: string): number;
+export interface RangeOrigin {
+    col0: number;
+    row1: number;
+}
+/**
+ * Parse the top-left origin of a `values.get` range echo. Handles a bare range
+ * (`C5:E9`), a tab-qualified range (`Costs!C5:E9`), quoted titles that may
+ * contain `!` (`'My Sheet!x'!A1:B2`), absolute refs (`$C$5`), and open-ended
+ * ranges (`Costs!A:D` → row 1; `Costs!5:9` → col A). Falls back to A1 when the
+ * origin can't be determined, so a parse miss degrades to a safe default rather
+ * than mis-addressing.
+ */
+export declare function parseRangeOrigin(range: string | undefined | null): RangeOrigin;
+export interface GridRender {
+    /** Row objects ready for renderList. */
+    rows: Array<Record<string, unknown>>;
+    /** Column schema for renderList. */
+    schema: FieldDef[];
+    /** Field name for the rendered list (`cells` or `rows`). */
+    listName: string;
+    /** Total data rows available (before the render cap). */
+    totalRows: number;
+    /** Whether the render was capped below totalRows. */
+    truncated: boolean;
+}
+/**
+ * Turn a `values.get` 2D array into row objects + a matching TOON schema.
+ *
+ * Default: `cells[N]{row,A,B,…}` — real sheet row numbers, A1 column letters
+ * from `origin`, ragged rows padded to the widest row.
+ * With `headerRow`: the first fetched row becomes the column names (`rows[N]{…}`),
+ * the `row` column is dropped, and duplicate/empty headers fall back to letters.
+ */
+export declare function buildGrid(values: unknown[][], origin: RangeOrigin, opts: {
+    headerRow: boolean;
+    maxRows: number;
+    full: boolean;
+}): GridRender;
+export interface GridCellLike {
+    formattedValue?: string | null;
+    hyperlink?: string | null;
+    note?: string | null;
+    textFormatRuns?: Array<{
+        startIndex?: number | null;
+        format?: {
+            link?: {
+                uri?: string | null;
+            } | null;
+        } | null;
+    }> | null;
+}
+export interface GridRowLike {
+    values?: GridCellLike[] | null;
+}
+export interface NoteEntry {
+    cell: string;
+    note: string;
+    [key: string]: unknown;
+}
+export interface ExtractedGrid {
+    /** Cell values with links rendered inline as markdown `[text](url)`. */
+    values: string[][];
+    /** Cell notes (distinct from Drive comments), keyed by A1 cell. */
+    notes: NoteEntry[];
+    /** Total number of resolved links inlined into the grid. */
+    linkCount: number;
+}
+/**
+ * Render one cell's display value, inlining any embedded links as markdown.
+ * - A whole-cell `hyperlink` wraps the entire value: `[value](url)`.
+ * - Rich-text links (`textFormatRuns` with a `format.link.uri`) wrap only the
+ *   linked span, reconstructed from the run boundaries, so a cell with several
+ *   links (`…here and here`) becomes `…[here](u1) and [here](u2)`.
+ * Returns `{ text, links }` where `links` counts resolved links in the cell.
+ */
+export declare function cellToMarkdown(cell: GridCellLike): {
+    text: string;
+    links: number;
+};
+/**
+ * Extract a values grid (with markdown-inlined links) + notes from
+ * includeGridData rowData. `origin` supplies the A1 coordinate of the top-left
+ * cell so notes are addressed correctly. Trailing fully-empty rows are trimmed
+ * to mirror the used-range behavior of a plain values fetch.
+ */
+export declare function extractGrid(rows: GridRowLike[], origin: RangeOrigin): ExtractedGrid;
+export declare function sheetsReadCommand(account: string, args: string[]): Promise<string>;