@pmate/cli 0.33.1 → 0.34.1

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.
@@ -275,3 +293,7 @@ Config (paths relative to the config file, `web.dist` relative to `web.cwd`):
 Use `--dry-run` to inspect the plan, `--dir` for an unpacked `.app`, or `--signed` to require a configured macOS signing identity. Default builds are ad-hoc signed for local use; they are not notarized distribution releases. Signed builds use electron-builder's standard signing/notarization environment variables; verify notarization separately before distributing.
 
 The shell serves the bundled renderer under its existing exact HTTPS origin, preserving authentication callbacks and API CORS. Other origins remain normal network requests. Static resources are hashed and checked at launch; missing assets return 404. The renderer is sandboxed with Node disabled and no privileged preload bridge. Sign-in, chat and inference still require internet. Updates require a new package. Each build prints its artifact directory and a resource/signing report; no build uploads or auto-updates occur.
+
+### 日志统计默认口径
+
+请求次数与日均可使用 `pmate logs aggregate pmate:issues-api --metric count --topic application --field event=http.access --interval day --timezone Asia/Shanghai --from <ISO> --to <ISO> --json`。计数由数据库完成，返回 `count`、`durationDays`、`averagePerDay`，时间桶包含零值；不返回 UV 或延迟百分位。JSON 模式失败以非零状态退出并返回固定 `error.code`，区分权限、保留期、查询预算和上游故障，避免泄露上游原始错误。

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

@@ -18743,6 +18743,30 @@ function capitalize(value) {
 // src/services/DeveloperLogsClient.ts
 init_sessionStore();
 init_namespacedRef();
+var DeveloperLogError = class extends Error {
+  constructor(code, status, message) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+};
+function logResponseError(status, message) {
+  const errors = {
+    400: ["logs_invalid_query", "Invalid log query; correct parameters before retrying"],
+    401: ["logs_unauthenticated", "Log session expired or invalid"],
+    403: ["logs_forbidden", "Log access denied for this sender"],
+    404: ["logs_not_found", "Requested log service or resource was not found"],
+    409: ["logs_index_changed", "Log index changed; retry the same query once"],
+    422: ["logs_query_limit", "Log query exceeded a retention or analysis limit"],
+    429: ["logs_rate_limited", "Log service rate limit reached"]
+  };
+  if (status === 422 && message === "Requested window extends beyond the safe retained log window")
+    return new DeveloperLogError("logs_retention", status, "Requested time window is outside retained logs");
+  if (status === 422 && ["Analysis exceeds 100 pages; reduce the time window", "Analysis exceeds 10000 records; reduce the time window", "Analysis budget exceeded; reduce the time window", "More than 100 groups; narrow query or choose a coarser dimension"].includes(String(message)))
+    return new DeveloperLogError("logs_budget_exceeded", status, "Analysis limit exceeded; use metric=count for counts, or narrow the window/dimensions for detailed metrics");
+  const [code, detail] = errors[status] ?? ["logs_unavailable", "Log service temporarily unavailable"];
+  return new DeveloperLogError(code, status, `${detail} (HTTP ${status})`);
+}
 var appRef = "pmate:developers";
 async function queryDeveloperLogs(input, fetcher = fetch) {
   if (input.app) parseNamespacedRef(input.app, { entityLabel: "app ref" });
@@ -18750,17 +18774,30 @@ 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");
     }
-    if (!response.ok) throw new Error(`Developers log request failed (HTTP ${response.status}); check login, pmate:dev role`);
+    if (!response.ok) {
+      let detail;
+      try {
+        detail = (await response.json())?.message;
+      } catch {
+      }
+      throw logResponseError(response.status, detail);
+    }
     let body;
     try {
       body = await response.json();
@@ -18770,6 +18807,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 +18823,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 +24785,75 @@ 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 = { "--metric": "metric", "--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.metric && params.metric !== "count") throw Error("Supported metric: count");
+    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.metric || 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 +26257,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 +26612,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 +28308,21 @@ 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");
+        try {
+          const result = await requestDeveloperLogTool(commandArgs.tool, new URLSearchParams(commandArgs.params), fetch, delegate);
+          console.log(JSON.stringify(result, null, commandArgs.json ? void 0 : 2));
+        } catch (error) {
+          if (!commandArgs.json) throw error;
+          const failure = error instanceof DeveloperLogError ? { code: error.code, status: error.status, message: error.message } : { code: "logs_unavailable", message: "Log tool failed before receiving a valid response" };
+          console.log(JSON.stringify({ ok: false, error: failure }));
+          process.exitCode = 1;
+        }
+        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.1",
   "description": "CLI utilities for the pMate project",
   "license": "MIT",
   "bin": {