move stats to top-level command

Author: Vlad Velici

docs/Product-Requirements.md

@@ -34,7 +34,6 @@ The CLI uses topics (space-separated) to group related commands logically.
 - `$ ably accounts list`: Lists locally configured accounts (aliases, token details, user info, account details).
 - `$ ably accounts logout [ALIAS]`: Removes the access token and associated data for the specified (or default) account after warning.
 - `$ ably accounts current`: Shows the currently selected account (alias or `default`) and verifies the token against the Control API `/me` endpoint.
-- `$ ably accounts stats`: Views account stats. Supports `--live` for polling key metrics (peak connections, channels, message throughput, etc.).
 - `$ ably accounts switch [ALIAS]`: Switches the active account configuration to the specified alias or prompts for selection.
 
 **App Management (`ably apps`)**
@@ -45,7 +44,6 @@ The CLI uses topics (space-separated) to group related commands logically.
 - `$ ably apps update ID`: Updates the app specified by `ID`. Supports `--name`, `--tls-only`.
 - `$ ably apps delete [ID]`: Deletes the specified (or current) app after confirmation. Supports `--force`.
 - `$ ably apps set-apns-p12 ID`: Uploads an APNS P12 certificate for the specified app `ID`. Requires `--certificate`. Supports `--password`, `--use-for-sandbox`.
-- `$ ably apps stats [ID]`: Views app stats for the specified (or current) app. Supports `--live` polling, `--unit`, `--start`, `--end`, `--limit`.
 - `$ ably apps switch [APPID]`: Switches the active app configuration to the specified App ID or prompts for selection.
 - `$ ably apps current`: Shows the currently selected app configuration.
 - `$ ably apps logs subscribe`: Alias for `ably logs app subscribe`.
@@ -158,6 +156,12 @@ The CLI uses topics (space-separated) to group related commands logically.
 - `$ ably queues create`: Creates a queue. Requires various flags.
 - `$ ably queues delete QUEUENAME`: Deletes a queue after confirmation. Supports `--force`.
 
+**Statistics (`ably stats`)**
+*(View usage statistics for accounts and apps)*
+
+- `$ ably stats account`: Views account stats. Supports `--live` for polling key metrics (peak connections, channels, message throughput, etc.), `--unit`, `--start`, `--end`, `--limit`.
+- `$ ably stats app [ID]`: Views app stats for the specified (or current) app. Supports `--live` polling, `--unit`, `--start`, `--end`, `--limit`.
+
 **Benchmarking (`ably bench`)**
 *(Run benchmark tests)*
 
@@ -316,7 +320,7 @@ The `AblyCliTerminal` React component can optionally support a split-screen mode
     - Uses a distinct client ID prefix (`ably-mcp-`).
 - **Available MCP Commands (Subset of CLI)**:
     - `ably apps list`
-    - `ably apps stats`
+    - `ably stats app`
     - `ably auth keys list`
     - `ably channels history`
     - `ably channels publish`

docs/TODO.md

@@ -72,7 +72,11 @@
     - [ ] Test app update with partial data
     - [ ] Test P12 certificate file upload handling
     - [ ] Test failure scenarios: duplicate app names, API error mapping
-  - [ ] `apps stats`: Mock Control API calls, flag handling, output formats.
+- [ ] **Stats:**
+  - [ ] `stats account`: Mock Control API calls, flag handling, output formats.
+    - [ ] Test stats parsing and formatting for different time ranges
+    - [ ] Test --live polling functionality with mocked responses
+  - [ ] `stats app`: Mock Control API calls, flag handling, output formats.
     - [ ] Test stats parsing and formatting for different time ranges
     - [ ] Test --live polling functionality with mocked responses
   - [ ] `apps logs history/subscribe`: Mock Control API/SDK, flag handling, output formats, SIGINT handling.

src/commands/accounts/index.ts

@@ -12,6 +12,5 @@ export default class AccountsCommand extends BaseTopicCommand {
     "$ ably accounts current",
     "$ ably accounts logout",
     "$ ably accounts switch my-account",
-    "$ ably accounts stats",
   ];
 }

src/commands/accounts/stats/README.md

@@ -12,7 +12,6 @@ export default class AppsCommand extends BaseTopicCommand {
     "$ ably apps update",
     "$ ably apps delete",
     "$ ably apps set-apns-p12",
-    "$ ably apps stats",
     "$ ably apps channel-rules list",
     "$ ably apps switch my-app",
   ];

src/commands/apps/index.ts

@@ -1,23 +1,23 @@
 import { Flags } from "@oclif/core";
 import chalk from "chalk";
 
-import { ControlBaseCommand } from "../../../control-base-command.js";
-import { StatsDisplay } from "../../../services/stats-display.js";
-import type { BaseFlags } from "../../../types/cli.js";
-import type { ControlApi } from "../../../services/control-api.js";
+import { ControlBaseCommand } from "../../control-base-command.js";
+import { StatsDisplay } from "../../services/stats-display.js";
+import type { BaseFlags } from "../../types/cli.js";
+import type { ControlApi } from "../../services/control-api.js";
 
-export default class AccountsStatsCommand extends ControlBaseCommand {
+export default class StatsAccountCommand extends ControlBaseCommand {
   static description = "Get account stats with optional live updates";
 
   static examples = [
-    "$ ably accounts stats",
-    "$ ably accounts stats --unit hour",
-    "$ ably accounts stats --start 1618005600000 --end 1618091999999",
-    "$ ably accounts stats --limit 10",
-    "$ ably accounts stats --json",
-    "$ ably accounts stats --pretty-json",
-    "$ ably accounts stats --live",
-    "$ ably accounts stats --live --interval 15",
+    "$ ably stats account",
+    "$ ably stats account --unit hour",
+    "$ ably stats account --start 1618005600000 --end 1618091999999",
+    "$ ably stats account --limit 10",
+    "$ ably stats account --json",
+    "$ ably stats account --pretty-json",
+    "$ ably stats account --live",
+    "$ ably stats account --live --interval 15",
   ];
 
   static flags = {
@@ -57,7 +57,7 @@ export default class AccountsStatsCommand extends ControlBaseCommand {
   private statsDisplay: StatsDisplay | null = null; // Track when we're already fetching stats
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(AccountsStatsCommand);
+    const { flags } = await this.parse(StatsAccountCommand);
 
     // For live stats, enforce minute interval
     if (flags.live && flags.unit !== "minute") {

src/commands/accounts/stats/index.ts src/commands/stats/account.tssrc/commands/accounts/stats/index.ts renamed to src/commands/stats/account.ts

@@ -1,11 +1,12 @@
 import { Args, Flags } from "@oclif/core";
 import chalk from "chalk";
-import { StatsDisplay } from "../../../services/stats-display.js";
-import { ControlBaseCommand } from "../../../control-base-command.js";
-import type { BaseFlags } from "../../../types/cli.js";
-import type { ControlApi } from "../../../services/control-api.js";
 
-export default class AppsStatsCommand extends ControlBaseCommand {
+import { ControlBaseCommand } from "../../control-base-command.js";
+import { StatsDisplay } from "../../services/stats-display.js";
+import type { BaseFlags } from "../../types/cli.js";
+import type { ControlApi } from "../../services/control-api.js";
+
+export default class StatsAppCommand extends ControlBaseCommand {
   static args = {
     id: Args.string({
       description: "App ID to get stats for (uses default app if not provided)",
@@ -16,17 +17,17 @@ export default class AppsStatsCommand extends ControlBaseCommand {
   static description = "Get app stats with optional live updates";
 
   static examples = [
-    "$ ably apps stats",
-    "$ ably apps stats app-id",
-    "$ ably apps stats --unit hour",
-    "$ ably apps stats app-id --unit hour",
-    "$ ably apps stats app-id --start 1618005600000 --end 1618091999999",
-    "$ ably apps stats app-id --limit 10",
-    "$ ably apps stats app-id --json",
-    "$ ably apps stats app-id --pretty-json",
-    "$ ably apps stats --live",
-    "$ ably apps stats app-id --live",
-    "$ ably apps stats --live --interval 15",
+    "$ ably stats app",
+    "$ ably stats app app-id",
+    "$ ably stats app --unit hour",
+    "$ ably stats app app-id --unit hour",
+    "$ ably stats app app-id --start 1618005600000 --end 1618091999999",
+    "$ ably stats app app-id --limit 10",
+    "$ ably stats app app-id --json",
+    "$ ably stats app app-id --pretty-json",
+    "$ ably stats app --live",
+    "$ ably stats app app-id --live",
+    "$ ably stats app --live --interval 15",
   ];
 
   static flags = {
@@ -66,7 +67,7 @@ export default class AppsStatsCommand extends ControlBaseCommand {
   private statsDisplay: StatsDisplay | null = null; // Track when we're already fetching stats
 
   async run(): Promise<void> {
-    const { args, flags } = await this.parse(AppsStatsCommand);
+    const { args, flags } = await this.parse(StatsAppCommand);
 
     // Use provided app ID or fall back to default app ID
     const appId = args.id || this.configManager.getCurrentAppId();

src/commands/apps/stats/index.ts src/commands/stats/app.tssrc/commands/apps/stats/index.ts renamed to src/commands/stats/app.ts

@@ -0,0 +1,17 @@
+import { BaseTopicCommand } from "../../base-topic-command.js";
+
+export default class StatsCommand extends BaseTopicCommand {
+  protected topicName = "stats";
+  protected commandGroup = "stats";
+
+  static description = "View statistics for your Ably account or apps";
+
+  static examples = [
+    "$ ably stats account",
+    "$ ably stats account --unit hour",
+    "$ ably stats account --live",
+    "$ ably stats app",
+    "$ ably stats app my-app-id",
+    "$ ably stats app --live",
+  ];
+}

src/commands/stats/index.ts

@@ -141,14 +141,7 @@ describe("Help Output Consistency", () => {
         });
 
         // Both should list the same commands (ignoring the ably prefix)
-        const commands = [
-          "current",
-          "list",
-          "login",
-          "logout",
-          "stats",
-          "switch",
-        ];
+        const commands = ["current", "list", "login", "logout", "switch"];
 
         commands.forEach((cmd) => {
           expect(nonInteractive).toContain(`accounts ${cmd}`);