tracksiy 0.2.0 → 0.4.0

package/README.md

@@ -126,6 +126,7 @@ Labels: `bug`, `feature`, `question`, `blocker`. `npx tracksiy support` prints t
 | `monitors declare` | Declare monitors for a project up front, idempotently: heartbeats for jobs, HTTP checks, TLS, ingest silence. | write | `monitors_declare` |
 | `monitors delete <slug>` | Remove one of a project's monitors by the slug it was declared with. | **destructive** | `monitors_delete` |
 | `performance` | Is this project slow, and did it get slower? Transactions compared with the previous window, plus uptime. | read | `performance` |
+| `queries` | Which database queries and outbound HTTP calls make this project slow, with N+1 detection and the routes that run them. | read | `queries` |
 | `issues list` | Recent issues of a project, newest activity first, with the frames that matter inlined. | read | `issues_list` |
 | `issues view <id>` | One issue in enough depth to act on: latest event, stack frames, tags, recent volume. | read | `issues_view` |
 | `issues resolve <ids...>` | Mark issues resolved, optionally fixed in a release so old clients do not reopen them. Records why. | write | `issues_resolve` |
@@ -134,6 +135,7 @@ Labels: `bug`, `feature`, `question`, `blocker`. `npx tracksiy support` prints t
 | `issues bulk-status` | Change the status of every issue matching a filter. Dry run unless --apply. | write | `issues_bulk_status` |
 | `issues comment <id>` | Leave a comment on an issue for the next agent or human: what you found, what you tried. | write | `issues_comment` |
 | `issues activity <id>` | Who did what to an issue and why: resolutions (and in which release), regressions, comments, claims. | read | `issues_activity` |
+| `issues verify-fixed <id>` | Did the fix hold? Judged by the fix release's own traffic: fixed, regressed or undetermined. Exit 10 unless fixed. | read | `issues_verify_fixed` |
 | `issues claim <id>` | Take a lease on an issue so no other agent works on it meanwhile. Lapses on its own. | write | `issues_claim` |
 | `issues unclaim <id>` | Give back your lease on an issue. | write | `issues_unclaim` |
 | `projects create <name>` | Everything a new app needs in one idempotent call: the project, an ingest key per surface, an upload token, and the next steps. | write | `projects_create` |

package/dist/tracksiy.mjs

@@ -4,7 +4,7 @@
 import { readFileSync as readFileSync2 } from "node:fs";
 
 // src/version.ts
-var VERSION = true ? "0.2.0" : "0.0.0-dev";
+var VERSION = true ? "0.4.0" : "0.0.0-dev";
 var USER_AGENT = `tracksiy-cli/${VERSION} (node ${process.versions.node}; ${process.platform})`;
 
 // src/core/errors.ts
@@ -851,10 +851,16 @@ var monitorsDeclare = {
     ssl: { type: "list", value: "<slug>=<url>", description: "TLS certificate check (expiry is reported on every check)." },
     ingest: { type: "list", value: "<slug>[:<surface>]", description: "Alert when this project (or surface) stops sending events." },
     interval: { type: "integer", value: "<seconds>", description: "Interval for --get/--ping/--ssl/--ingest monitors." },
+    "expect-text": { type: "string", value: "<text>", description: "--get: down unless the body contains this (a 200 with an empty shell is down)." },
+    "expect-no-text": { type: "string", value: "<text>", description: "--get: down if the body contains this, e.g. Whoops or Exception." },
+    "user-agent": { type: "string", value: "<ua>", description: "--get/--ping: ask as this User-Agent, e.g. GPTBot/1.0, to see what crawlers get." },
+    "dry-run": { type: "boolean", description: "Show what would be created, adopted or changed; write nothing." },
     body: { type: "json", value: "<json|@file|->", description: "Raw request body; overrides the shorthand flags." }
   },
   examples: [
-    { command: "tracksiy monitors declare --heartbeat nightly-backup:93600 --get site=https://example.com", description: "A backup heartbeat and a homepage check." }
+    { command: "tracksiy monitors declare --heartbeat nightly-backup:93600 --get site=https://example.com", description: "A backup heartbeat and a homepage check." },
+    { command: "tracksiy monitors declare --get tr-landing=https://example.com/tr --expect-text '<h1' --expect-no-text Whoops --user-agent GPTBot/1.0", description: "The page as an answer engine gets it: real content, no error template." },
+    { command: "tracksiy monitors declare --heartbeat tariff-sync:608400 --dry-run", description: "See the change before making it." }
   ],
   output: "Server result per monitor, including check-in URLs for heartbeats.",
   async run(ctx) {
@@ -870,7 +876,17 @@ var monitorsDeclare = {
         for (const item of i[type] ?? []) {
           const eq = String(item).indexOf("=");
           if (eq < 1) throw usageError("bad_value", `--${type} expects <slug>=<url>, got ${JSON.stringify(item)}`);
-          monitors.push(compact({ slug: item.slice(0, eq), type, url: item.slice(eq + 1), intervalSeconds: i.interval }));
+          monitors.push(
+            compact({
+              slug: item.slice(0, eq),
+              type,
+              url: item.slice(eq + 1),
+              intervalSeconds: i.interval,
+              expectText: type === "get" ? i.expectText : void 0,
+              expectNoText: type === "get" ? i.expectNoText : void 0,
+              userAgent: type !== "ssl" ? i.userAgent : void 0
+            })
+          );
         }
       }
       for (const item of i.ingest ?? []) {
@@ -880,6 +896,7 @@ var monitorsDeclare = {
       if (!monitors.length) throw usageError("missing_flag", "Nothing to declare.", "Add --heartbeat, --get, --ping, --ssl, --ingest, or --body.");
       body = { monitors };
     }
+    if (i.dryRun) body = { ...body, dryRun: true };
     return ctx.api.send("POST", await projectPath(ctx, "monitors"), body);
   }
 };
@@ -904,16 +921,26 @@ var performance = {
   effect: "read",
   endpoint: { method: "GET", path: "/api/agent/v1/projects/{org}/{project}/performance" },
   flags: {
-    since: { type: "string", value: TIME, description: "Window start (default: server's, 24h)." },
-    op: { type: "string", value: "<op>", description: "Only this operation, e.g. http.server." },
-    sort: { type: "string", value: "<key>", description: "Order (server default: slower first)." },
-    limit: { type: "integer", value: "<n>", description: "How many transactions." }
+    since: { type: "string", value: TIME, description: "Window start (default: server's, 24h; 7d with --release)." },
+    op: { type: "string", value: "<op>", description: "Only this operation, e.g. http.server or pageload." },
+    sort: { type: "string", enum: ["slower", "duration", "p95", "failures"], description: "Order (default: slower first)." },
+    limit: { type: "integer", value: "<n>", description: "How many transactions." },
+    release: { type: "string", value: "<version>", description: "Compare this release's transactions with --against instead of two time windows." },
+    against: { type: "string", value: "<version>", description: "The release to compare with (default: the one before --release)." }
   },
-  output: "{since, until, transactions:[{transaction, op, current{...}, previous{...}, changeRatio, slower}], uptime[...], blindSpots[...]}",
+  examples: [
+    { command: "tracksiy performance --sort p95", description: "The slowest routes by p95." },
+    { command: "tracksiy performance --release web@$(git rev-parse HEAD)", description: "Did this deploy make anything slower or failing?" },
+    { command: "tracksiy performance --op pageload --select transactions.transaction,transactions.current.webVitals", description: "Core Web Vitals (p75) per page." }
+  ],
+  output: "{since, until, release?, againstRelease?, transactions:[{transaction, op, current{count, avgDurationMs, p50Ms, p95Ms, p99Ms, failureRate, failed, status, webVitals}, previous{...}, changeRatio, slower}], uptime[...], blindSpots[...]}",
   text: (d) => `${table(d.transactions ?? [], [
     "transaction",
     "op",
-    ["p95 ms", (r) => r.current?.p95Ms ?? r.current?.p95 ?? "-"],
+    ["p50", (r) => r.current?.p50Ms ?? "-"],
+    ["p95", (r) => r.current?.p95Ms ?? "-"],
+    ["p99", (r) => r.current?.p99Ms ?? "-"],
+    ["fail", (r) => r.current?.failureRate == null ? "-" : `${(r.current.failureRate * 100).toFixed(1)}%`],
     ["count", (r) => r.current?.count ?? "-"],
     ["change", (r) => r.changeRatio == null ? "-" : `${r.changeRatio > 0 ? "+" : ""}${Math.round(r.changeRatio * 100)}%`],
     ["slower", (r) => r.slower]
@@ -926,11 +953,52 @@ ${table(d.uptime, ["name", "url", "upNow", "avgResponseMs", "downChecks"])}` : "
       since: since(ctx.input.since),
       op: ctx.input.op,
       sort: ctx.input.sort,
+      limit: ctx.input.limit,
+      release: ctx.input.release,
+      against: ctx.input.against
+    });
+  }
+};
+var queries = {
+  path: ["queries"],
+  aliases: [["performance", "queries"]],
+  summary: "Which database queries and outbound HTTP calls make this project slow, with N+1 detection and the routes that run them.",
+  description: "Aggregated from the spans of sampled transactions (op db* and http.client), normalized so no literal is stored. Ranked by total time by default: the query that costs the most overall. nPlusOne marks a query one request ran 10+ times.",
+  context: "project",
+  effect: "read",
+  endpoint: { method: "GET", path: "/api/agent/v1/projects/{org}/{project}/queries" },
+  flags: {
+    since: { type: "string", value: TIME, description: "Window start (default 24h)." },
+    op: { type: "string", value: "<db|http.client|op>", description: "db (every db* op), http.client, or an exact op." },
+    transaction: { type: "string", value: "<route>", description: "Only queries run by this transaction, e.g. /orders." },
+    sort: { type: "string", enum: ["total", "avg", "max", "count", "perTransaction"], description: "Order (default total)." },
+    limit: { type: "integer", value: "<n>", description: "How many (max 100)." }
+  },
+  examples: [
+    { command: "tracksiy queries --since 24h", description: "The queries that cost the most time today." },
+    { command: "tracksiy queries --sort perTransaction --select queries.query,queries.maxPerTransaction,queries.routes", description: "N+1 candidates." }
+  ],
+  output: "{since, until, queries:[{fingerprint, op, query, count, transactions, perTransaction, maxPerTransaction, totalMs, avgMs, maxMs, previous{count, avgMs}, changeRatio, nPlusOne, routes[{transaction, count, avgMs}]}], note}",
+  text: (d) => table(d.queries ?? [], [
+    ["total ms", (r) => r.totalMs],
+    ["avg", (r) => r.avgMs ?? "-"],
+    ["max", (r) => r.maxMs],
+    ["count", (r) => r.count],
+    ["per req", (r) => r.perTransaction],
+    ["n+1", (r) => r.nPlusOne ? "yes" : ""],
+    ["query", (r) => String(r.query).slice(0, 90)]
+  ]),
+  async run(ctx) {
+    return ctx.api.get(await projectPath(ctx, "queries"), {
+      since: since(ctx.input.since),
+      op: ctx.input.op,
+      transaction: ctx.input.transaction,
+      sort: ctx.input.sort,
       limit: ctx.input.limit
     });
   }
 };
-var fleet_default = [orgs, projects, overview, changes, health, monitorsList, monitorsDeclare, monitorsDelete, performance];
+var fleet_default = [orgs, projects, overview, changes, health, monitorsList, monitorsDeclare, monitorsDelete, performance, queries];
 
 // src/commands/issues.ts
 var FILTERS = {
@@ -1122,6 +1190,40 @@ var activity = {
     return ctx.api.get(await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/activity`), { limit: ctx.input.limit });
   }
 };
+var verifyFixed = {
+  path: ["issues", "verify-fixed"],
+  summary: "Did the fix hold? Judged by the fix release's own traffic: fixed, regressed or undetermined. Exit 10 unless fixed.",
+  description: "regressed: the issue has an event from the fix release or a newer one. undetermined: the fix release has had too little traffic (--min-traffic), or the issue's old rate predicts fewer than 3 occurrences in that traffic. fixed otherwise. The fix release defaults to the one the issue was resolved in. --wait polls until the verdict is not undetermined.",
+  context: "project",
+  effect: "read",
+  endpoint: { method: "GET", path: "/api/agent/v1/projects/{org}/{project}/issues/{issue_id}/verify" },
+  args: [{ name: "id", required: true, description: "Issue id." }],
+  flags: {
+    release: { type: "string", value: "<version>", description: "The fix release. Default: the one it was resolved in." },
+    "min-traffic": { type: "integer", value: "<n>", description: "Transactions + errors + sessions from the fix release needed before silence counts (default 100)." },
+    wait: { type: "integer", value: "<seconds>", description: "Poll every 30 s until fixed or regressed, up to this long." }
+  },
+  examples: [
+    { command: "tracksiy issues verify-fixed 4812", description: "Verdict now." },
+    { command: "tracksiy issues verify-fixed 4812 --wait 1800", description: "In a deploy script: wait up to 30 min for enough traffic." }
+  ],
+  output: "{verdict, reason, release, since, eventsSince, staleEvents, traffic{transactions, errors, sessions, total}, baselinePer1000, expectedEvents, latestEvent?}",
+  text: (d) => kv(d, ["verdict", "reason", "release", "since", "eventsSince", "staleEvents", "expectedEvents"]) + `
+traffic: ${d.traffic?.total ?? 0} (${d.traffic?.transactions ?? 0} transactions, ${d.traffic?.errors ?? 0} errors, ${d.traffic?.sessions ?? 0} sessions)`,
+  async run(ctx) {
+    const path = await projectPath(ctx, `issues/${encodeURIComponent(ctx.input.id)}/verify`);
+    const query = { release: ctx.input.release, minTraffic: ctx.input.minTraffic };
+    const deadline = Date.now() + (ctx.input.wait ?? 0) * 1e3;
+    let data = await ctx.api.get(path, query);
+    while (data?.verdict === "undetermined" && Date.now() + 3e4 <= deadline) {
+      ctx.log(`undetermined: ${data.reason} -- checking again in 30 s`);
+      await new Promise((r) => setTimeout(r, 3e4));
+      data = await ctx.api.get(path, query);
+    }
+    if (data?.verdict !== "fixed") throw new CheckFailed(`${data?.verdict ?? "unknown"}: ${data?.reason ?? ""}`, data, data?.verdict === "regressed" ? "Reopened by its own release: look at latestEvent." : "Wait for traffic (--wait), or lower --min-traffic.");
+    return data;
+  }
+};
 var claim = {
   path: ["issues", "claim"],
   summary: "Take a lease on an issue so no other agent works on it meanwhile. Lapses on its own.",
@@ -1195,7 +1297,7 @@ var bulk = {
     return ctx.api.send("POST", await projectPath(ctx, "issues/status"), body);
   }
 };
-var issues_default = [list, view, resolve2, ignore, unresolve, bulk, comment, activity, claim, unclaim];
+var issues_default = [list, view, resolve2, ignore, unresolve, bulk, comment, activity, verifyFixed, claim, unclaim];
 
 // src/commands/projects.ts
 var create = {
@@ -1294,12 +1396,12 @@ var onboarding = {
 var projects_default = [create, verify, onboarding];
 
 // src/commands/alerts.ts
-var RECIPIENT_TYPES = ["email", "webhook", "discord", "googlechat", "telegram"];
+var RECIPIENT_TYPES = ["email", "webhook", "discord", "googlechat", "telegram", "peerpacket"];
 var DECLARE = {
   recipient: {
     type: "list",
     value: "email|<type>:<url>",
-    description: `Who is told. Repeatable. \`email\` alone reaches the members of the project's teams; webhook, discord, googlechat and telegram take a URL: \`<type>:<url>\` (telegram: the Bot API sendMessage URL with chat_id).`
+    description: `Who is told. Repeatable. \`email\` alone reaches the members of the project's teams; webhook, discord, googlechat and telegram take a URL: \`<type>:<url>\` (telegram: the Bot API sendMessage URL with chat_id; peerpacket: https://peerpacket.com/channels/<channel>?to=<handle>&as=<author>&key=<pp_live_\u2026> -- each alert becomes a ticket for that agent, closed when its issues are resolved).`
   },
   delivery: { type: "string", enum: ["immediate", "digest"], description: "For --recipient: send each alert now, or batch into the digest hours. Default immediate." },
   "new-issue": { type: "boolean", description: "Alert on every new issue (default true). --no-new-issue to turn off." },
@@ -1376,7 +1478,8 @@ var set = {
   flags: DECLARE,
   examples: [
     { command: "tracksiy alerts set --recipient email --threshold 50/10", description: "Email the project's team on new issues, on bursts, and on downtime." },
-    { command: "tracksiy alerts set --recipient 'telegram:https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>' --delivery digest", description: "Telegram, batched into the digest hours." }
+    { command: "tracksiy alerts set --recipient 'telegram:https://api.telegram.org/bot<token>/sendMessage?chat_id=<id>' --delivery digest", description: "Telegram, batched into the digest hours." },
+    { command: "tracksiy alerts set --recipient 'peerpacket:https://peerpacket.com/channels/shop-ops?to=shop-agent&as=tracksiy-alerts&key=pp_live_\u2026'", description: "Alerts land as PeerPacket tickets for the shop's agent." }
   ],
   output: "The stored alerting state, same shape as `alerts get`.",
   text: rulesText,
@@ -3066,7 +3169,7 @@ var COMMANDS = [
 ];
 var GROUPS = [
   ["Start", "init auth onboarding describe"],
-  ["Look", "overview changes health orgs projects issues monitors performance releases alerts keys artifacts"],
+  ["Look", "overview changes health orgs projects issues monitors performance queries releases alerts keys artifacts"],
   ["Ship", "sourcemaps proguard"],
   ["Manage", "tokens"],
   ["Talk to us", "support"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracksiy",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Agent-first CLI and MCP server for Tracksiy: errors, uptime, alerts, releases and source maps, from one token.",
   "type": "module",
   "bin": {