@pmate/cli 0.33.1 → 0.34.0

package/README.md

@@ -236,18 +236,36 @@ Notes:
 - `pmate vercel deploys` requires `--project <name>`.
 # Service logs
 
-Service logs use the same authenticated API as `dev.pmate.chat`. Each registered Service has `app` (application/deployment) and `runtime` (PM2/Nginx) Table topics on the dedicated `log` chain.
+Service logs use the same authenticated API as `dev.pmate.chat`. Sources are registered Service/topic pairs on the dedicated `log` chain.
 
 ```sh
 pmate service log pmate:issues-api --topic application --page 0 --json
-pmate service log pmate:issues-api --topic nginx --field status=500 --env prod
-pmate service log pmate:issues-api --field requestId=<id> --follow
+pmate service log pmate:issues-api --topic nginx --field status=500
+pmate service log pmate:issues-api --field requestId=<id>
 ```
 
 Pages are zero-based. Lists and `--search` cover the chain's configured retention window (30 days in production). `--since-ms` adds an epoch-millisecond lower bound. `--field name=value` (repeatable, scalar JSON values) and `--env` filter on the server. Topics are independent sources such as `application`, `nginx`, `pm2`, `deployment`, `pv`, and `vitals`; custom fields live in `data`. Old `--type`, `--level`, `--source`, and `--request-id` flags are removed. The legacy `--app` argument is optional and does not select a different source.
 
 A current CLI session is exchanged in memory for `pmate:developers`; the active App and session file are unchanged. If needed, run `pmate login --app pmate:developers`. Permission denial never falls back to anonymous Indexer reads. Credentials are never printed.
 
+### Log analysis tools
+
+`pmate logs` exposes the same read-only tools used by Meili. The server calculates results over a bounded retained window, with query IDs and coverage metadata; the model does not count sampled pages.
+
+```sh
+pmate logs schema --json
+pmate logs query pmate:apps-api --topic application --field level=error --json
+pmate logs aggregate pmate:hello --topic pv --from 2026-10-08T00:00:00+08:00 --to 2026-10-08T10:00:00+08:00 --group-by path --interval hour --timezone Asia/Shanghai --json
+pmate logs trace pmate:developers-api --request-id REQUEST_ID --json
+pmate logs compare pmate:hello --topic pv --from 2026-10-08T00:00:00+08:00 --to 2026-10-08T10:00:00+08:00 --compare-from 2026-10-07T00:00:00+08:00 --compare-to 2026-10-07T10:00:00+08:00 --json
+```
+
+PV counts page-view events; sessions deduplicate appId/accessId; Profile UV deduplicates appId/profileId. Missing IDs and anonymous events remain separate. Query/trace default to application; aggregate/compare default to pv. Vitals percentiles require `--field name=LCP` (or another specific metric). Current user classification is visit frequency within the query window; first-ever/new users cannot be inferred from retention-limited history.
+
+Time windows are `[from,to)` and at most 31 days, inside the configured retention. Times accept Unix milliseconds or ISO with explicit timezone. Comparisons require equal duration. More than 10,000 records/100 pages/100 groups is rejected instead of reporting partial totals. Indexing and browser telemetry remain best effort; `completeRead` is not proof of complete real-world activity. Query pages are zero-based.
+
+Meili's Host may pass `--actor-profile-id` with `PMATE_LOG_DELEGATE_TOKEN` in the child environment. This mode never reads or exchanges the host's personal CLI session. Auth API verifies the allowlisted Bot and the actual sender's pmate:dev permission on every call. Models cannot supply the actor or token.
+
 ### Package a desktop app
 
 `pmate app build <ns:app> --target electron --config <file>` builds the configured web app, embeds its static output in an Electron ASAR, and produces a macOS DMG and ZIP. It does not require registry login. The first build downloads pinned Electron and electron-builder versions. Current targets: macOS `arm64` and `x64`, built on macOS.

package/dist/index.d.ts

@@ -31,6 +31,7 @@ declare enum Command {
     Store = "store",
     App = "app",
     Service = "service",
+    Logs = "logs",
     Vercel = "vercel",
     Host = "host",
     Quiz = "quiz"
@@ -1143,7 +1144,14 @@ type VercelDeploysCommandArgs = {
     lastWeek: boolean;
 };
 type VercelCommandArgs = VercelProjectsCommandArgs | VercelDeploysCommandArgs;
-type CommandArgs = NoneCommandArgs | ListCommandArgs | LoginCommandArgs | AddDnsCommandArgs | StsCommandArgs | BucketCommandArgs | DeployCommandArgs | LogCommandArgs | InitCommandArgs | DeleteCommandArgs | DevCommandArgs | EnvCommandArgs | CommitCommandArgs | SummaryCommandArgs | QuizCommandArgs | ServiceCommandArgs | LinearCommandArgs | NotionCommandArgs | OssCommandArgs | QrcodeCommandArgs | RandomCommandArgs | CollectCommandArgs | ChatRoomCommandArgs | FunctionCommandArgs | WorkerCommandArgs | CallCommandArgs | NsCommandArgs | RoleCommandArgs | AccountCommandArgs | OrgCommandArgs | StoreCommandArgs | AppCommandArgs | VercelCommandArgs | HostCommandArgs;
+type LogsCommandArgs = {
+    type: Command.Logs;
+    tool: "schema" | "query" | "aggregate" | "trace" | "compare";
+    params: Record<string, string>;
+    json: boolean;
+    actorProfileId?: string;
+};
+type CommandArgs = LogsCommandArgs | NoneCommandArgs | ListCommandArgs | LoginCommandArgs | AddDnsCommandArgs | StsCommandArgs | BucketCommandArgs | DeployCommandArgs | LogCommandArgs | InitCommandArgs | DeleteCommandArgs | DevCommandArgs | EnvCommandArgs | CommitCommandArgs | SummaryCommandArgs | QuizCommandArgs | ServiceCommandArgs | LinearCommandArgs | NotionCommandArgs | OssCommandArgs | QrcodeCommandArgs | RandomCommandArgs | CollectCommandArgs | ChatRoomCommandArgs | FunctionCommandArgs | WorkerCommandArgs | CallCommandArgs | NsCommandArgs | RoleCommandArgs | AccountCommandArgs | OrgCommandArgs | StoreCommandArgs | AppCommandArgs | VercelCommandArgs | HostCommandArgs;
 
 interface ParsedArgs {
     help: boolean;

package/dist/index.js

@@ -18750,13 +18750,19 @@ async function queryDeveloperLogs(input, fetcher = fetch) {
   if (!Number.isSafeInteger(input.page) || input.page < 0) throw new Error("Invalid log page");
   if (input.sinceMs !== void 0 && (!Number.isSafeInteger(input.sinceMs) || input.sinceMs < 0)) throw new Error("Invalid log time");
   if (input.keyword && input.keyword.length > 256) throw new Error("Log search must be at most 256 characters");
-  const session = readRequiredSession({ preferredApp: appRef, fallbackToActiveApp: true });
-  if (Date.parse(session.expiresAt) <= Date.now() || !Number.isFinite(Date.parse(session.expiresAt)))
-    throw new Error("Session expired. Run pmate login --app pmate:developers");
-  async function request2(url, init) {
+  const params = new URLSearchParams({ service: input.service, page: String(input.page), topic: input.topic ?? "application" });
+  if (input.environment) params.set("environment", input.environment);
+  if (input.fields) params.set("fields", JSON.stringify(input.fields));
+  if (input.keyword) params.set("keyword", input.keyword);
+  if (input.sinceMs !== void 0) params.set("sinceMs", String(input.sinceMs));
+  return requestDeveloperLogTool("query", params, fetcher);
+}
+async function requestDeveloperLogTool(tool, params, fetcher = fetch, delegate) {
+  if (!["schema", "query", "aggregate", "trace", "compare"].includes(tool)) throw new Error("Unknown log tool");
+  async function request2(url2, init) {
     let response;
     try {
-      response = await fetcher(url, { ...init, redirect: "error", signal: AbortSignal.timeout(3e4) });
+      response = await fetcher(url2, { ...init, redirect: "error", signal: AbortSignal.timeout(3e4) });
     } catch {
       throw new Error("Developers log request failed; no anonymous fallback was attempted");
     }
@@ -18770,6 +18776,15 @@ async function queryDeveloperLogs(input, fetcher = fetch) {
     if (!body?.success) throw new Error("Developers API rejected the request");
     return body.data;
   }
+  const suffix = tool === "query" ? "" : `/${tool}`;
+  const url = `https://dev-api.pmate.chat/api/logs${suffix}?${params}`;
+  if (delegate) {
+    if (!delegate.token || !/^[a-zA-Z0-9_.:@-]{1,128}$/.test(delegate.profileId)) throw new Error("Invalid log delegation");
+    return request2(url, { headers: { Authorization: `Bearer ${delegate.token}`, "x-pmate-actor-profile-id": delegate.profileId } });
+  }
+  const session = readRequiredSession({ preferredApp: appRef, fallbackToActiveApp: true });
+  if (Date.parse(session.expiresAt) <= Date.now() || !Number.isFinite(Date.parse(session.expiresAt)))
+    throw new Error("Session expired. Run pmate login --app pmate:developers");
   const exchanged = await request2("https://auth-api-v2.pmate.chat/session/exchange", {
     method: "POST",
     headers: { Authorization: `Bearer ${session.token}`, "Content-Type": "application/json" },
@@ -18777,12 +18792,7 @@ async function queryDeveloperLogs(input, fetcher = fetch) {
   });
   if (exchanged?.session?.identity?.app !== appRef || exchanged.session.identity.accountId !== session.accountId || typeof exchanged.token !== "string" || !exchanged.token)
     throw new Error("Developers session identity mismatch");
-  const params = new URLSearchParams({ service: input.service, page: String(input.page), topic: input.topic ?? "application" });
-  if (input.environment) params.set("environment", input.environment);
-  if (input.fields) params.set("fields", JSON.stringify(input.fields));
-  if (input.keyword) params.set("keyword", input.keyword);
-  if (input.sinceMs !== void 0) params.set("sinceMs", String(input.sinceMs));
-  return request2(`https://dev-api.pmate.chat/api/logs?${params}`, { headers: { Authorization: `Bearer ${exchanged.token}` } });
+  return request2(url, { headers: { Authorization: `Bearer ${exchanged.token}` } });
 }
 
 // src/services/ServiceRuntimeRunner.ts
@@ -24744,6 +24754,74 @@ function parseServiceEnvArgs(appId, tokens) {
   throw new Error(`Unknown service env action: ${action}`);
 }
 
+// src/logsCommandParser.ts
+init_namespacedRef();
+function parseLogsArgs(input) {
+  const rest = [...input], tool = rest.shift();
+  if (!["schema", "query", "aggregate", "trace", "compare"].includes(tool)) throw Error("Usage: pmate logs schema|query|aggregate|trace|compare [ns:service] [options]");
+  const params = {}, fields = {};
+  let json = false, actorProfileId;
+  if (rest[0] && !rest[0].startsWith("--")) params.service = parseNamespacedRef(rest.shift(), { entityLabel: "service" }).fullId;
+  const keys = { "--topic": "topic", "--env": "environment", "--search": "keyword", "--group-by": "groupBy", "--interval": "interval", "--timezone": "timezone", "--request-id": "requestId", "--page": "page" };
+  const times = { "--from": "from", "--to": "to", "--compare-from": "compareFrom", "--compare-to": "compareTo" };
+  while (rest.length) {
+    const flag = rest.shift();
+    if (flag === "--json") {
+      json = true;
+      continue;
+    }
+    const value = rest.shift();
+    if (value === void 0 || value.startsWith("--")) throw Error(`Missing value for ${flag}`);
+    if (flag === "--actor-profile-id") {
+      if (!/^[a-zA-Z0-9_.:@-]{1,128}$/.test(value)) throw Error("Invalid actor profile");
+      actorProfileId = value;
+    } else if (flag === "--field") {
+      const match = /^([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)=(.*)$/.exec(value);
+      if (!match || match[1].length > 128 || match[2].length > 256) throw Error("Use --field name=value");
+      let parsed = match[2];
+      try {
+        parsed = JSON.parse(match[2]);
+      } catch {
+      }
+      if (!["string", "number", "boolean"].includes(typeof parsed)) throw Error("Field must be a scalar");
+      fields[match[1]] = parsed;
+      if (Object.keys(fields).length > 20) throw Error("At most 20 field filters");
+    } else if (times[flag]) {
+      if (!/^\d+$/.test(value) && !/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value)) throw Error("Use Unix milliseconds or ISO time with an explicit timezone");
+      const milliseconds = /^\d+$/.test(value) ? Number(value) : Date.parse(value);
+      if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) throw Error(`Invalid ${flag}`);
+      params[times[flag]] = String(milliseconds);
+    } else if (keys[flag]) params[keys[flag]] = value;
+    else throw Error(`Unknown log option: ${flag}`);
+  }
+  if (tool !== "schema" && !params.service) throw Error("Service reference required");
+  if (tool === "schema" && (Object.keys(params).length || Object.keys(fields).length)) throw Error("logs schema only accepts --json");
+  if (tool === "aggregate" || tool === "compare") {
+    if (!params.from || !params.to || Number(params.from) >= Number(params.to)) throw Error("An increasing --from/--to window is required");
+    if (params.page || params.requestId) throw Error("Use --field requestId=value for analysis; --page only applies to query/trace");
+  } else {
+    if (params.groupBy || params.interval || params.timezone || params.compareFrom || params.compareTo) throw Error("Grouping and comparison options require aggregate/compare");
+    if (params.from) {
+      params.sinceMs = params.from;
+      delete params.from;
+    }
+    if (params.to) {
+      params.untilMs = params.to;
+      delete params.to;
+    }
+  }
+  if (tool !== "compare" && (params.compareFrom || params.compareTo)) throw Error("Comparison bounds require compare");
+  if (tool === "compare" && (!params.compareFrom || !params.compareTo)) throw Error("compare requires --compare-from and --compare-to");
+  if (tool === "trace" && !params.requestId) throw Error("trace requires --request-id");
+  if (tool === "query" && params.requestId) {
+    fields.requestId = params.requestId;
+    delete params.requestId;
+  }
+  if (params.page !== void 0 && (!/^\d+$/.test(params.page) || !Number.isSafeInteger(Number(params.page)))) throw Error("Invalid --page");
+  if (Object.keys(fields).length) params.fields = JSON.stringify(fields);
+  return { type: "logs" /* Logs */, tool, params, json, ...actorProfileId ? { actorProfileId } : {} };
+}
+
 // src/roleCommandParser.ts
 function parseRoleArgs(tokens) {
   const rest = [...tokens];
@@ -26147,6 +26225,7 @@ var HELP_TEXT = [
   import_chalk4.default.bold(`pmate v${pkg.version}`),
   "",
   import_chalk4.default.bold("Usage:"),
+  "  logs schema|query|aggregate|trace|compare [service] --from <ISO|ms> --to <ISO|ms> --topic <topic> --field name=value --json",
   `  ${import_chalk4.default.cyan("pmate")} ${import_chalk4.default.gray("[options]")}`,
   "",
   import_chalk4.default.bold("Options:"),
@@ -26501,6 +26580,7 @@ function parseCommandArgs(args) {
   if (args.rest[0] === "app") {
     return parseAppArgs(args.rest.slice(1));
   }
+  if (args.rest[0] === "logs") return parseLogsArgs(args.rest.slice(1));
   if (args.rest[0] === "service") {
     return parseServiceArgs(args.rest.slice(1));
   }
@@ -28196,6 +28276,14 @@ async function main() {
         await handler.handle(commandArgs);
         return;
       }
+      case "logs" /* Logs */: {
+        const delegate = commandArgs.actorProfileId ? { profileId: commandArgs.actorProfileId, token: process.env.PMATE_LOG_DELEGATE_TOKEN ?? "" } : void 0;
+        if (delegate && !delegate.token) throw new Error("PMATE_LOG_DELEGATE_TOKEN is required for delegated log tools");
+        if (!delegate && process.env.PMATE_LOG_DELEGATE_TOKEN) throw new Error("Delegated log tools require --actor-profile-id");
+        const result = await requestDeveloperLogTool(commandArgs.tool, new URLSearchParams(commandArgs.params), fetch, delegate);
+        console.log(JSON.stringify(result, null, commandArgs.json ? void 0 : 2));
+        return;
+      }
       case "service" /* Service */: {
         const handler = new ServiceCommandHandler();
         await handler.handle(commandArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/cli",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "CLI utilities for the pMate project",
   "license": "MIT",
   "bin": {