@pitcher/cli-scripts 2.12.0 → 2.13.0

package/README.md

@@ -12,7 +12,7 @@ p command --help
 
 ## MCP server
 
-Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 113 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 114 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
 
 ```bash
 p mcp
@@ -55,7 +55,7 @@ yarn mcpb:pack        # → pitcher.mcpb (validated + packed)
 
 Install by double-clicking `pitcher.mcpb` (or Settings → Extensions → Install Extension). Claude Desktop prompts for the API key (stored in the OS keychain) and organization; both are editable afterward, so switching orgs needs no reinstall.
 
-The bundle reuses the same server as `p mcp` but registers a **content-tool subset (110)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
+The bundle reuses the same server as `p mcp` but registers a **content-tool subset (111)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
 
 This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
 
@@ -360,6 +360,14 @@ p analytics org --api-key myapikey
 
 # Instance rollups (instance-admin or org-admin key required)
 p analytics instance --instance-id 01... --api-key myapikey
+
+# KPI metrics from the clickhouse analytics service (PIT-7647).
+# Access follows the key user's real role on the instance; --org/--url pick the
+# env exactly as for other commands (they route via x-original-domain).
+# Activity metrics need a date window; inventory counts (total-members, ...) do not.
+p analytics kpi --instance-id 01... --type total-members --api-key myapikey
+p analytics kpi --instance-id 01... --type total-active-users \
+  --start-date 2026-01-01 --end-date 2026-01-31 --api-key myapikey
 ```
 
 ## To run the `users` command:

package/dist/src/commands/analytics.d.ts

@@ -9,4 +9,20 @@ export declare function runAnalyticsOrg(opts: CommonOpts, deps?: AnalyticsDeps):
 export declare function runAnalyticsInstance(opts: CommonOpts & {
     instanceId?: string;
 }, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsKpiOpts extends CommonOpts {
+    instanceId?: string;
+    type?: string;
+    startDate?: string;
+    endDate?: string;
+    groupIds?: string;
+    userEmails?: string;
+}
+/**
+ * KPI metrics from the clickhouse-api analytics service (PIT-7647). Unlike
+ * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
+ * org api-key; the caller inherits the key user's real role. Dates are required
+ * by the server for activity-metric types (inventory counts like
+ * `total-members` need none) — that validation stays server-side.
+ */
+export declare function runAnalyticsKpi(opts: AnalyticsKpiOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export declare function createAnalyticsCommand(): Command;

package/dist/src/commands/analytics.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { clientFor, toCliError } from '../core/http.js';
+import { clickhouseClientFor, clientFor, toCliError } from '../core/http.js';
 import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
@@ -26,6 +26,37 @@ export async function runAnalyticsInstance(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+/**
+ * KPI metrics from the clickhouse-api analytics service (PIT-7647). Unlike
+ * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
+ * org api-key; the caller inherits the key user's real role. Dates are required
+ * by the server for activity-metric types (inventory counts like
+ * `total-members` need none) — that validation stays server-side.
+ */
+export async function runAnalyticsKpi(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics kpi');
+        const client = clickhouseClientFor(opts, deps);
+        const params = {
+            instance_id: opts.instanceId,
+            type: opts.type || 'all',
+        };
+        if (opts.startDate)
+            params.start_date = opts.startDate;
+        if (opts.endDate)
+            params.end_date = opts.endDate;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.userEmails)
+            params.user_emails = opts.userEmails;
+        const res = await client.get('/analytics/kpi', { params });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
 export function createAnalyticsCommand() {
     const cmd = new Command('analytics').description('read rollup analytics totals (requires an org-admin API key)');
     withAuthFlags(cmd.command('org'))
@@ -41,5 +72,17 @@ export function createAnalyticsCommand() {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runAnalyticsInstance({ ...options, quiet: globals.quiet }), globals);
     });
+    withAuthFlags(cmd.command('kpi'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--type <type>', "KPI type, e.g. total-members, total-active-users (default 'all')")
+        .option('--start-date <iso>', 'Window start (ISO date; required by the server for activity metrics)')
+        .option('--end-date <iso>', 'Window end (ISO date; required by the server for activity metrics)')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs to scope by')
+        .option('--user-emails <csv>', 'Comma-separated user emails to scope by')
+        .description('KPI metrics from the clickhouse analytics service (role follows the key user)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsKpi({ ...options, quiet: globals.quiet }), globals);
+    });
     return cmd;
 }

package/dist/src/core/http.d.ts

@@ -11,6 +11,16 @@ export interface CommonOpts {
 export declare function clientFor(opts: CommonOpts, deps?: {
     client?: AxiosInstance;
 }): AxiosInstance;
+export declare const CLICKHOUSE_API_BASE_URL = "https://clickhouse.pitcher.com";
+/**
+ * Client for the clickhouse-api analytics service (PIT-7647). The service lives
+ * on ONE host for every env/region; `x-original-domain` (the same `--org`/`--url`
+ * resolution as Django calls) is what routes the request to the right core for
+ * key validation + tenant scoping, so the usual flags select test vs prod.
+ */
+export declare function clickhouseClientFor(opts: CommonOpts, deps?: {
+    client?: AxiosInstance;
+}): AxiosInstance;
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays

package/dist/src/core/http.js

@@ -15,6 +15,26 @@ export function makeClient(baseUrl, apiKey) {
 export function clientFor(opts, deps = {}) {
     return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), resolveApiKey(opts));
 }
+export const CLICKHOUSE_API_BASE_URL = 'https://clickhouse.pitcher.com';
+/**
+ * Client for the clickhouse-api analytics service (PIT-7647). The service lives
+ * on ONE host for every env/region; `x-original-domain` (the same `--org`/`--url`
+ * resolution as Django calls) is what routes the request to the right core for
+ * key validation + tenant scoping, so the usual flags select test vs prod.
+ */
+export function clickhouseClientFor(opts, deps = {}) {
+    if (deps.client)
+        return deps.client;
+    const originalDomain = new URL(resolveBaseUrl({ org: opts.org, url: opts.url })).hostname;
+    return axios.create({
+        baseURL: CLICKHOUSE_API_BASE_URL,
+        headers: {
+            accept: 'application/json',
+            'x-api-key': resolveApiKey(opts),
+            'x-original-domain': originalDomain,
+        },
+    });
+}
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays

package/dist/src/mcp/bundled.js

@@ -1,7 +1,7 @@
 import { allTools } from './registry.js';
 // Developer-only tools excluded from the consumer .mcpb bundle. `publish_app` is alwaysDestructive
 // (creates a live, org-visible app release); `dev_sync`/`dev_sync_revert` mutate remote S3 dev state.
-// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 113.
+// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 114.
 export const BUNDLE_EXCLUDED_TOOLS = new Set(['pitcher_publish_app', 'pitcher_dev_sync', 'pitcher_dev_sync_revert']);
 // The tool set the .mcpb bundle registers.
 export const bundledTools = allTools.filter((t) => !BUNDLE_EXCLUDED_TOOLS.has(t.name));

package/dist/src/mcp/tools/analytics.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { runAnalyticsOrg, runAnalyticsInstance } from '../../commands/analytics.js';
+import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi } from '../../commands/analytics.js';
 export const analyticsTools = [
     {
         name: 'pitcher_analytics_org',
@@ -17,4 +17,21 @@ export const analyticsTools = [
         run: runAnalyticsInstance,
         readOnly: true,
     },
+    {
+        name: 'pitcher_analytics_kpi',
+        title: 'Instance KPI metrics',
+        description: 'Read KPI metrics for an instance from the clickhouse analytics service (PIT-7647). ' +
+            'Access follows the API key user’s real role; activity-metric types need start/end dates ' +
+            '(inventory counts like total-members do not).',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            type: z.string().optional().describe("KPI type, e.g. total-members, total-active-users (default 'all')"),
+            startDate: z.string().optional().describe('Window start, ISO date (required by the server for activity metrics)'),
+            endDate: z.string().optional().describe('Window end, ISO date (required by the server for activity metrics)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs to scope by'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by'),
+        },
+        run: runAnalyticsKpi,
+        readOnly: true,
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",