naro-cli 0.13.0 → 0.14.0

package/README.md

@@ -69,9 +69,13 @@ naro logs <deployment-id>          Build logs of a deployment
 naro logs --type build --follow    Stream build logs until READY/FAILED
 naro logs --env preview            Preview-surface runtime logs
 
-naro insights                      Speed Insights: Web Vitals p75 (--metric lcp, --range 7d)
+naro analytics                     Web Analytics: visitors, page views, top pages, referrers, countries, devices, browsers, operating systems (--range 7d)
+naro analytics --country KR --os ios  Narrow it: --path, --referrer, --country, --device, --browser, --os (one value each, all must match)
+
+naro insights                      Speed Insights: Web Vitals p75, and the page load's p75 and the mean of each step (--metric lcp, --range 7d)
 naro insights --route '/posts/[id]'  The paths under one route
 naro insights --env preview        The same for the preview worker
+naro insights --country KR --device mobile  Narrow it: --path, --country, --device, --browser, --os (no --referrer: Speed Insights has none)
 naro insights enable | disable     Turn measuring on or off
 
 naro protection                    Preview protection: on or off, and whether a bypass secret is set
@@ -789,6 +793,39 @@ An `--update-check` you give replaces the default: without
 
 ## Release notes
 
+### 0.14.0
+
+- `naro analytics` shows the project's Web Analytics from the terminal: the
+  range's visitors and page views (`--range 24h|7d|30d`, 7d by default), then
+  the top pages, referrers, countries, devices, browsers and operating systems
+  by page views, and `--json` prints the whole report, trend included. The
+  same six filters as on the dashboard narrow it, one value each, all of them
+  at once: `naro analytics --country KR --os ios`. The first line names the
+  filters that applied; filters that leave no visit print one line under it,
+  `No visits match these filters. Drop a filter to see more.`, instead of six
+  empty tables. The CLI does not check the values; the server answers
+  `400 VALIDATION_FAILED` with the rule the value broke (`--country` is an
+  uppercase two-letter code like `KR`, `--referrer` a lowercase host like
+  `t.co`; `kr` and `T.co` are refused). It reads the
+  production worker only, so `--env` is refused with `VALIDATION_FAILED` and
+  nothing is sent. An API token (`--token`, `NARO_TOKEN`) can read it.
+- `naro insights` takes the same filters: `--path`, `--country`, `--device`,
+  `--browser` and `--os` narrow it to one value each (`--referrer` is refused
+  with `VALIDATION_FAILED` and nothing is sent: a vitals row has no referrer).
+  The first line names the filters that applied
+  (`· filtered by country=KR, os=ios`); filters that leave no measurement print
+  `No measurements match these filters. Drop a filter to see more.` instead of
+  waiting advice.
+  The filters narrow a report only: `naro insights enable | disable` refuses
+  them (`Filters only narrow a report; drop --country.`) and sends nothing, and
+  an empty value (`--referrer=`) is no filter.
+- `naro insights` prints a `Page load p75 … · mean per step: …` line under the
+  metrics table: the p75 of how long visits took to load the page, to the end
+  of the load event, then the mean of each step (wait, DNS, connect, server,
+  download, processing, onload), so the steps need not add up to the p75. It is
+  left out until a visit has sent a page load. The dashboard's Speed Insights
+  tab has the same Page load card.
+
 ### 0.13.0
 
 - `naro insights` shows the project's Speed Insights from the terminal: each

package/dist/{chunk-O4NJRDJE.js → chunk-U7AZSAFS.js}

@@ -18488,6 +18488,16 @@ function createLogSender(ports) {
   };
 }
 
+// ../../packages/sdk/src/analytics.ts
+var ANALYTICS_FILTER_KEYS = [
+  "path",
+  "referrer",
+  "country",
+  "device",
+  "browser",
+  "os"
+];
+
 // ../../packages/sdk/src/auth.ts
 import { homedir as homedir2 } from "os";
 
@@ -18960,6 +18970,23 @@ function openBrowser(url2) {
   child.unref();
 }
 
+// ../../packages/sdk/src/insights.ts
+var SPEED_INSIGHTS_METRICS = [
+  "lcp",
+  "inp",
+  "cls",
+  "fcp",
+  "ttfb"
+];
+var SPEED_INSIGHTS_FILTER_KEYS = [
+  "path",
+  "country",
+  "device",
+  "browser",
+  "os"
+];
+var SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES = 20;
+
 // ../../packages/sdk/src/types.ts
 var TERMINAL_DEPLOYMENT_STATUSES = [
   "READY",
@@ -19052,6 +19079,7 @@ var NaroClient = class {
   backend;
   storage;
   insights;
+  analytics;
   protection;
   constructor(options) {
     this.baseUrl = (options.baseUrl ?? controlPlaneUrl()).replace(/\/$/, "");
@@ -19069,6 +19097,7 @@ var NaroClient = class {
     this.backend = new BackendApi(this);
     this.storage = new StorageApi(this);
     this.insights = new InsightsApi(this);
+    this.analytics = new AnalyticsApi(this);
     this.protection = new ProtectionApi(this);
   }
   async request(path, options) {
@@ -19477,12 +19506,20 @@ var LogsApi = class {
     return body.entries;
   }
 };
+function appendFilters(params, keys, filters) {
+  if (!filters) return;
+  for (const key of keys) {
+    const value = filters[key];
+    if (value) params.set(key, value);
+  }
+}
 function insightsQuery(options) {
   const params = new URLSearchParams();
   if (options.range !== void 0) params.set("range", options.range);
   if (options.metric !== void 0) params.set("metric", options.metric);
   if (options.environment !== void 0) params.set("env", options.environment);
   if (options.route !== void 0) params.set("route", options.route);
+  appendFilters(params, SPEED_INSIGHTS_FILTER_KEYS, options.filters);
   const text2 = params.toString();
   return text2 ? `?${text2}` : "";
 }
@@ -19493,7 +19530,7 @@ var InsightsApi = class {
   base(projectId) {
     return `/api/projects/${encodeURIComponent(projectId)}/speed-insights`;
   }
-  /** The five metrics' summary, and the trend, pages, devices and elements of one. */
+  /** The five metrics' summary, and the trend, pages, devices, browsers, operating systems, countries and elements of one. */
   async report(projectId, options = {}) {
     return this.client.request(
       `${this.base(projectId)}${insightsQuery(options)}`,
@@ -19553,6 +19590,22 @@ var InsightsApi = class {
     });
   }
 };
+var AnalyticsApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Visitors, page views, the trend, and the pages, referrers, countries, devices, browsers and operating systems behind them. */
+  async report(projectId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.range !== void 0) params.set("range", options.range);
+    appendFilters(params, ANALYTICS_FILTER_KEYS, options.filters);
+    const text2 = params.toString();
+    return this.client.request(
+      `/api/projects/${encodeURIComponent(projectId)}/analytics${text2 ? `?${text2}` : ""}`,
+      { context: "Read Analytics" }
+    );
+  }
+};
 var ProtectionApi = class {
   constructor(client) {
     this.client = client;
@@ -27333,16 +27386,6 @@ function generateTypes(tables, options = {}) {
 `;
 }
 
-// ../../packages/sdk/src/insights.ts
-var SPEED_INSIGHTS_METRICS = [
-  "lcp",
-  "inp",
-  "cls",
-  "fcp",
-  "ttfb"
-];
-var SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES = 20;
-
 // ../../packages/sdk/src/link.ts
 import {
   existsSync as existsSync4,
@@ -28464,6 +28507,7 @@ export {
   schemaMigrationTitle,
   projectPath,
   splitStatements,
+  ANALYTICS_FILTER_KEYS,
   NaroError,
   isNaroError,
   toNaroError,
@@ -28477,6 +28521,9 @@ export {
   login,
   resolveAuth,
   openBrowser,
+  SPEED_INSIGHTS_METRICS,
+  SPEED_INSIGHTS_FILTER_KEYS,
+  SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES,
   isTerminalStatus,
   BACKEND_STEPS,
   isStalledBackend,
@@ -28515,8 +28562,6 @@ export {
   formatRedirectEntry,
   policiesForTypes,
   generateTypes,
-  SPEED_INSIGHTS_METRICS,
-  SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES,
   readProjectLink,
   writeProjectLink,
   removeProjectLink,

package/dist/deploy.js

@@ -5,7 +5,7 @@ import {
   parseDotenv,
   readProjectEnv,
   slugify
-} from "./chunk-O4NJRDJE.js";
+} from "./chunk-U7AZSAFS.js";
 import "./chunk-K3NQKI34.js";
 export {
   deployDirectory,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  ANALYTICS_FILTER_KEYS,
   BACKEND_STEPS,
   BOOKMARK_FORMAT_MESSAGE,
   INDEX_SQL,
@@ -13,6 +14,7 @@ import {
   RESET_BACKEND_OUTDATED,
   RESTORE_OUTCOME_UNKNOWN_CODES,
   SCHEMA_SQL,
+  SPEED_INSIGHTS_FILTER_KEYS,
   SPEED_INSIGHTS_METRICS,
   SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES,
   STORAGE_OBJECTS_TABLE,
@@ -81,7 +83,7 @@ import {
   toNaroError,
   unreadablePolicyComment,
   writeProjectLink
-} from "./chunk-O4NJRDJE.js";
+} from "./chunk-U7AZSAFS.js";
 import "./chunk-K3NQKI34.js";
 
 // src/args.ts
@@ -139,6 +141,12 @@ var STRING_FLAGS = {
   "--metric": "metric",
   "--range": "range",
   "--route": "route",
+  "--path": "path",
+  "--referrer": "referrer",
+  "--country": "country",
+  "--device": "device",
+  "--browser": "browser",
+  "--os": "os",
   "--file": "file",
   "--output": "output",
   "--lang": "lang",
@@ -490,86 +498,9 @@ import { readFileSync as readFileSync5 } from "fs";
 import { dirname as dirname4, join as join7 } from "path";
 import { fileURLToPath } from "url";
 
-// src/commands/auth.ts
-async function runLogin(context) {
-  const { output } = context;
-  output.log("Opening your browser to sign in with GitHub...");
-  const session = await login({
-    openBrowser: (url) => {
-      output.log(`If your browser did not open, visit:
-  ${url}`);
-      openBrowser(url);
-    }
-  });
-  saveSession(session);
-  output.result(
-    {
-      user: {
-        id: session.user.id,
-        email: session.user.email,
-        github: session.user.github
-      }
-    },
-    [`\u2705 Logged in as ${session.user.email ?? session.user.id}`]
-  );
-}
-async function runLogout(context) {
-  const session = loadStoredSession();
-  if (session) {
-    try {
-      const client = createAuthClient();
-      await client.auth.setSession({
-        access_token: session.access_token,
-        refresh_token: session.refresh_token
-      });
-      await client.auth.signOut();
-    } catch {
-    }
-  }
-  clearSession();
-  context.output.result({ loggedOut: true }, ["Logged out."]);
-}
-async function currentSession() {
-  let session = loadStoredSession();
-  if (!session)
-    throw new NaroError("NOT_LOGGED_IN", "Not logged in. Run `naro login`.");
-  if (isExpired(session)) {
-    try {
-      session = await refreshStoredSession(session.refresh_token);
-      saveSession(session);
-    } catch {
-      throw new NaroError(
-        "NOT_LOGGED_IN",
-        "Session expired. Run `naro login`."
-      );
-    }
-  }
-  return session;
-}
-async function runWhoami(context) {
-  const session = await currentSession();
-  const handle = session.user.github ? ` (${session.user.github})` : "";
-  context.output.result(
-    {
-      user: {
-        id: session.user.id,
-        email: session.user.email,
-        github: session.user.github
-      }
-    },
-    [`Logged in as ${session.user.email ?? session.user.id}${handle}`]
-  );
-}
-async function runToken(context) {
-  const session = await currentSession();
-  process.stderr.write(
-    "\u26A0 Access tokens expire after about an hour \u2014 generate one per CI run.\n"
-  );
-  context.output.result(
-    { token: session.access_token, expiresAt: session.expires_at },
-    [session.access_token]
-  );
-}
+// src/commands/migration.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, relative } from "path";
 
 // src/commands/confirm.ts
 function cannotAsk(context) {
@@ -588,8 +519,6 @@ async function confirmOrAbort(context, question) {
 }
 
 // src/commands/migration.ts
-import { mkdirSync, readFileSync, writeFileSync } from "fs";
-import { join, relative } from "path";
 var processStdin = {
   stdinIsTty: () => process.stdin.isTTY === true,
   readStdin
@@ -792,34 +721,409 @@ async function runMigrationUp(context) {
     ]);
     return;
   }
-  if (context.flags.dryRun) {
-    const problems = policyProblems(dir, pending);
-    context.output.result({ projectId, dryRun: true, pending, problems }, [
-      `Pending migrations (${String(pending.length)}):`,
-      ...pending.map((name) => `  ${printable(name)}`),
-      ...problems.map(
-        (problem) => `${printable(problem.migration)}: ${printable(problem.message)}`
-      )
-    ]);
-    if (problems.length > 0) process.exitCode = 1;
-    return;
+  if (context.flags.dryRun) {
+    const problems = policyProblems(dir, pending);
+    context.output.result({ projectId, dryRun: true, pending, problems }, [
+      `Pending migrations (${String(pending.length)}):`,
+      ...pending.map((name) => `  ${printable(name)}`),
+      ...problems.map(
+        (problem) => `${printable(problem.migration)}: ${printable(problem.message)}`
+      )
+    ]);
+    if (problems.length > 0) process.exitCode = 1;
+    return;
+  }
+  context.output.log(`Pending migrations (${String(pending.length)}):`);
+  for (const name of pending) context.output.log(`  ${printable(name)}`);
+  await confirmOrAbort(
+    context,
+    `Apply ${String(pending.length)} migration(s) to the project database? Each file is applied all-or-nothing; a failure stops the run.`
+  );
+  const { applied, warnings } = await applyMigrationFiles(
+    context,
+    client,
+    projectId,
+    dir,
+    pending
+  );
+  context.output.result({ projectId, applied, pending: [], warnings }, [
+    `\u2705 Applied ${String(applied.length)} migration(s).`
+  ]);
+}
+
+// src/commands/filters.ts
+function filtersOf(flags, keys) {
+  const filters = {};
+  for (const key of keys) {
+    const value = flags[key];
+    if (value !== void 0) filters[key] = value;
+  }
+  return filters;
+}
+function givenFilterFlag(flags) {
+  return ANALYTICS_FILTER_KEYS.find((key) => {
+    const value = flags[key];
+    return value !== void 0 && value !== "";
+  });
+}
+function filteredBy(filters) {
+  const applied = ANALYTICS_FILTER_KEYS.flatMap((key) => {
+    const value = filters[key];
+    return value ? [`${key}=${printable(value)}`] : [];
+  });
+  return applied.length === 0 ? "" : ` \xB7 filtered by ${applied.join(", ")}`;
+}
+
+// src/commands/insights-format.ts
+var OFF_LINE = "Speed Insights is off for this project. Turn it on: naro insights enable";
+var TURNED_ON = "Speed Insights is on. Measuring starts within about a minute; values arrive when visitors leave a page.";
+var TURNED_OFF = "Speed Insights is off. Measuring stops within about a minute; turning it back on shows past measurements again.";
+var RANGE_TEXT = {
+  "24h": "last 24 hours",
+  "7d": "last 7 days",
+  "30d": "last 30 days"
+};
+var PART_TEXT = {
+  ttfb: "TTFB",
+  loadDelay: "load delay",
+  loadDuration: "load duration",
+  renderDelay: "render delay",
+  inputDelay: "input delay",
+  processing: "processing",
+  presentation: "presentation"
+};
+var PAGE_LOAD_PART_TEXT = {
+  wait: "wait",
+  dns: "DNS",
+  connect: "connect",
+  server: "server",
+  download: "download",
+  processing: "processing",
+  onload: "onload"
+};
+function rangeText(range) {
+  const known = RANGE_TEXT;
+  return known[range] ?? printable(range);
+}
+function partText(name) {
+  const known = PART_TEXT;
+  return known[name] ?? printable(name);
+}
+function pageLoadPartText(name) {
+  const known = PAGE_LOAD_PART_TEXT;
+  return known[name] ?? printable(name);
+}
+var ATTRIBUTED = /* @__PURE__ */ new Set([
+  "lcp",
+  "inp",
+  "cls"
+]);
+var DEPLOYMENT_ROWS = 10;
+var SUBJECT_LENGTH = 50;
+function formatMs(ms) {
+  const rounded = Math.round(ms);
+  return rounded < 1e3 ? `${String(rounded)} ms` : `${(rounded / 1e3).toFixed(2)} s`;
+}
+function formatValue(metric, value) {
+  return metric === "cls" ? value.toFixed(2) : formatMs(value);
+}
+function formatChange(metric, change2) {
+  const size = formatValue(metric, Math.abs(change2));
+  if (Number.parseFloat(size) === 0) return "\xB10";
+  return change2 > 0 ? `\u25B2 +${size}` : `\u25BC \u2212${size}`;
+}
+function formatCount(count2) {
+  return Math.round(count2).toLocaleString("en-US");
+}
+function percent(part, total) {
+  return `${String(Math.round(part / total * 100))}%`;
+}
+function label(metric) {
+  return metric.toUpperCase();
+}
+function environmentSuffix(environment) {
+  return environment === "preview" ? ", preview" : "";
+}
+function environmentWord(environment) {
+  return environment === "preview" ? "preview " : "";
+}
+function table(rows) {
+  const widths = [];
+  for (const row of rows)
+    row.forEach((cell, i) => {
+      widths[i] = Math.max(widths[i] ?? 0, cell.length);
+    });
+  return rows.map(
+    (row) => `  ${row.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ")}`.trimEnd()
+  );
+}
+function summaryLines(report) {
+  return table([
+    ["Metric", "p75", "Good", "Needs improvement", "Poor", "Visits"],
+    ...SPEED_INSIGHTS_METRICS.map((metric) => {
+      const summary = report.summary[metric];
+      if (summary.p75 === null || summary.samples <= 0)
+        return [label(metric), "\u2014", "\u2014", "\u2014", "\u2014", "0"];
+      return [
+        label(metric),
+        formatValue(metric, summary.p75),
+        percent(summary.good, summary.samples),
+        percent(summary.needsImprovement, summary.samples),
+        percent(summary.poor, summary.samples),
+        formatCount(summary.samples)
+      ];
+    })
+  ]);
+}
+function pageLoadLine(pageLoad) {
+  if (!pageLoad || pageLoad.samples <= 0 || pageLoad.p75 === null) return null;
+  const head = `Page load p75 ${formatMs(pageLoad.p75)}`;
+  if (pageLoad.parts.length === 0) return head;
+  const steps = pageLoad.parts.map(
+    (part) => `${pageLoadPartText(part.name)} ${formatMs(part.ms)}`
+  );
+  return `${head} \xB7 mean per step: ${steps.join(" \xB7 ")}`;
+}
+function breakdownTable(heading, metric, rows) {
+  if (rows.length === 0) return ["  (none)"];
+  return table([
+    ["p75", "Visits", heading],
+    ...rows.map((row) => [
+      formatValue(metric, row.p75),
+      formatCount(row.samples),
+      printable(row.name)
+    ])
+  ]);
+}
+function elementLines(metric, elements) {
+  const lines = ["", `${label(metric)} elements behind slow visits`];
+  if (elements.length === 0) return [...lines, "  (none)"];
+  for (const row of elements) {
+    lines.push(
+      `  ${printable(row.element)} on ${printable(row.route)}: ${formatCount(row.slow)} slow visits, average ${formatValue(metric, row.average)}`
+    );
+    if (row.parts && row.parts.length > 0)
+      lines.push(
+        `    ${row.parts.map((part) => `${partText(part.name)} ${formatMs(part.ms)}`).join(" \xB7 ")}`
+      );
+    if (row.url) lines.push(`    image ${printable(row.url)}`);
+  }
+  return lines;
+}
+function deploymentName(row) {
+  if (row.source === "cli" || !row.commitSha) return row.id.slice(0, 8);
+  const sha = printable(row.commitSha.slice(0, 7));
+  const subject = [
+    ...printable(row.commitMessage?.split("\n")[0]?.trim() ?? "")
+  ];
+  if (subject.length === 0) return sha;
+  return subject.length > SUBJECT_LENGTH ? `${sha} ${subject.slice(0, SUBJECT_LENGTH - 1).join("")}\u2026` : `${sha} ${subject.join("")}`;
+}
+function changeText(metric, row) {
+  if (row.samples < SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES)
+    return "too few visits";
+  if (row.change === null) return "\u2013";
+  return formatChange(metric, row.change);
+}
+function deploymentLines(metric, deployments, environment) {
+  if (deployments === null) return [];
+  const lines = [
+    "",
+    `${label(metric)} by ${environmentWord(environment)}deployment, newest first`
+  ];
+  const measured = deployments.filter((row) => row.samples > 0).slice(0, DEPLOYMENT_ROWS);
+  if (measured.length === 0) return [...lines, "  (none)"];
+  return [
+    ...lines,
+    ...table([
+      ["", "p75", "Visits", "Change", "Deployment"],
+      ...measured.map((row) => [
+        row.liveUntil === null ? "Live" : "",
+        row.p75 === null ? "\u2014" : formatValue(metric, row.p75),
+        formatCount(row.samples),
+        changeText(metric, row),
+        deploymentName(row)
+      ])
+    ])
+  ];
+}
+function reportLines(report, deployments, filters = {}) {
+  if (!report.enabled) return [OFF_LINE];
+  const { metric, range, environment } = report;
+  const filtered = filteredBy(filters);
+  const head = `Speed Insights \u2014 ${label(metric)}, ${rangeText(range)}${environmentSuffix(environment)}${filtered}`;
+  if (SPEED_INSIGHTS_METRICS.every((m) => report.summary[m].samples <= 0))
+    return [
+      head,
+      "",
+      // The dashboard's noFilteredSamples: waiting is the wrong advice when a
+      // filter is what emptied the report.
+      filtered === "" ? `No ${environmentWord(environment)}measurements in the ${rangeText(range)} yet. Values arrive when visitors leave a page.` : "No measurements match these filters. Drop a filter to see more."
+    ];
+  const pageLoad = pageLoadLine(report.pageLoad);
+  return [
+    head,
+    "",
+    ...summaryLines(report),
+    ...pageLoad === null ? [] : ["", pageLoad],
+    "",
+    `${label(metric)} by page`,
+    ...breakdownTable("Page", metric, report.paths),
+    "",
+    `${label(metric)} by device`,
+    ...breakdownTable("Device", metric, report.devices),
+    ...ATTRIBUTED.has(metric) ? elementLines(metric, report.elements) : [],
+    ...deploymentLines(metric, deployments, environment)
+  ];
+}
+function routePathsLines(result, filters = {}) {
+  return [
+    `${label(result.metric)} p75 under ${printable(result.route)}, ${rangeText(result.range)}${environmentSuffix(result.environment)}${filteredBy(filters)}`,
+    ...breakdownTable("Path", result.metric, result.paths)
+  ];
+}
+
+// src/commands/analytics-format.ts
+var TABLES = [
+  { key: "pages", title: "Pages", column: "Page" },
+  { key: "referrers", title: "Referrers", column: "Referrer" },
+  { key: "countries", title: "Countries", column: "Country" },
+  { key: "devices", title: "Devices", column: "Device" },
+  { key: "browsers", title: "Browsers", column: "Browser" },
+  { key: "os", title: "Operating systems", column: "Operating system" }
+];
+function breakdownLines({ title, column }, rows) {
+  if (rows.length === 0) return [title, "  No data yet."];
+  return [
+    title,
+    ...table([
+      ["Page views", column],
+      // The name last: free text is never padded against anything after it.
+      ...rows.map((row) => [formatCount(row.views), printable(row.name)])
+    ])
+  ];
+}
+function analyticsLines(report, range, filters) {
+  const filtered = filteredBy(filters);
+  const head = `Visitors ${formatCount(report.totals.visitors)} \xB7 Page views ${formatCount(report.totals.views)} \xB7 last ${printable(range)}${filtered}`;
+  if (filtered !== "" && report.totals.views === 0)
+    return [
+      head,
+      "",
+      "No visits match these filters. Drop a filter to see more."
+    ];
+  return [
+    head,
+    ...TABLES.flatMap((spec) => [
+      "",
+      ...breakdownLines(spec, report[spec.key])
+    ])
+  ];
+}
+
+// src/commands/analytics.ts
+function queryOf(flags) {
+  const filters = filtersOf(flags, ANALYTICS_FILTER_KEYS);
+  return {
+    ...flags.range !== void 0 ? { range: flags.range } : {},
+    ...Object.keys(filters).length > 0 ? { filters } : {}
+  };
+}
+async function runAnalytics(context) {
+  if (context.flags.env !== void 0)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      "Analytics reads the production worker only; drop --env."
+    );
+  const client = await context.client();
+  const projectId = await context.resolveProjectId();
+  const query = queryOf(context.flags);
+  const report = await client.analytics.report(projectId, query);
+  context.output.result(
+    { projectId, ...report },
+    analyticsLines(report, report.range, query.filters ?? {})
+  );
+}
+
+// src/commands/auth.ts
+async function runLogin(context) {
+  const { output } = context;
+  output.log("Opening your browser to sign in with GitHub...");
+  const session = await login({
+    openBrowser: (url) => {
+      output.log(`If your browser did not open, visit:
+  ${url}`);
+      openBrowser(url);
+    }
+  });
+  saveSession(session);
+  output.result(
+    {
+      user: {
+        id: session.user.id,
+        email: session.user.email,
+        github: session.user.github
+      }
+    },
+    [`\u2705 Logged in as ${session.user.email ?? session.user.id}`]
+  );
+}
+async function runLogout(context) {
+  const session = loadStoredSession();
+  if (session) {
+    try {
+      const client = createAuthClient();
+      await client.auth.setSession({
+        access_token: session.access_token,
+        refresh_token: session.refresh_token
+      });
+      await client.auth.signOut();
+    } catch {
+    }
+  }
+  clearSession();
+  context.output.result({ loggedOut: true }, ["Logged out."]);
+}
+async function currentSession() {
+  let session = loadStoredSession();
+  if (!session)
+    throw new NaroError("NOT_LOGGED_IN", "Not logged in. Run `naro login`.");
+  if (isExpired(session)) {
+    try {
+      session = await refreshStoredSession(session.refresh_token);
+      saveSession(session);
+    } catch {
+      throw new NaroError(
+        "NOT_LOGGED_IN",
+        "Session expired. Run `naro login`."
+      );
+    }
   }
-  context.output.log(`Pending migrations (${String(pending.length)}):`);
-  for (const name of pending) context.output.log(`  ${printable(name)}`);
-  await confirmOrAbort(
-    context,
-    `Apply ${String(pending.length)} migration(s) to the project database? Each file is applied all-or-nothing; a failure stops the run.`
+  return session;
+}
+async function runWhoami(context) {
+  const session = await currentSession();
+  const handle = session.user.github ? ` (${session.user.github})` : "";
+  context.output.result(
+    {
+      user: {
+        id: session.user.id,
+        email: session.user.email,
+        github: session.user.github
+      }
+    },
+    [`Logged in as ${session.user.email ?? session.user.id}${handle}`]
   );
-  const { applied, warnings } = await applyMigrationFiles(
-    context,
-    client,
-    projectId,
-    dir,
-    pending
+}
+async function runToken(context) {
+  const session = await currentSession();
+  process.stderr.write(
+    "\u26A0 Access tokens expire after about an hour \u2014 generate one per CI run.\n"
+  );
+  context.output.result(
+    { token: session.access_token, expiresAt: session.expires_at },
+    [session.access_token]
   );
-  context.output.result({ projectId, applied, pending: [], warnings }, [
-    `\u2705 Applied ${String(applied.length)} migration(s).`
-  ]);
 }
 
 // src/commands/backend.ts
@@ -1455,7 +1759,7 @@ async function allUsers(client, projectId) {
 function orDash(value) {
   return value === null ? "-" : printable(value);
 }
-function label(user) {
+function label2(user) {
   return printable(user.username ?? user.email ?? user.id);
 }
 function userTable(users) {
@@ -1537,7 +1841,7 @@ async function runBackendUsersCreate(context, input = processStdin3) {
   );
   const signIn = user.username === null ? "naro.auth.signIn({ email, password })" : `naro.auth.signIn({ username: ${JSON.stringify(printable(user.username))}, password })`;
   context.output.result({ projectId, user }, [
-    `\u2705 Created user ${label(user)}. It signs in at once with ${signIn}.`,
+    `\u2705 Created user ${label2(user)}. It signs in at once with ${signIn}.`,
     ...userLines(user)
   ]);
 }
@@ -1562,7 +1866,7 @@ async function runBackendUsersDelete(context) {
       "USER_NOT_FOUND",
       `No user has the id, username or email ${printable(given)}. \`naro backend users\` lists them.`
     );
-  const named = user.id === label(user) ? label(user) : `${label(user)} (${printable(user.id)})`;
+  const named = user.id === label2(user) ? label2(user) : `${label2(user)} (${printable(user.id)})`;
   await confirmOrAbort(
     context,
     `Delete the user ${named}? Their sessions end at once and the account cannot be brought back.`
@@ -4583,206 +4887,35 @@ async function runGenTypes(context) {
   ]);
 }
 
-// src/commands/insights-format.ts
-var OFF_LINE = "Speed Insights is off for this project. Turn it on: naro insights enable";
-var TURNED_ON = "Speed Insights is on. Measuring starts within about a minute; values arrive when visitors leave a page.";
-var TURNED_OFF = "Speed Insights is off. Measuring stops within about a minute; turning it back on shows past measurements again.";
-var RANGE_TEXT = {
-  "24h": "last 24 hours",
-  "7d": "last 7 days",
-  "30d": "last 30 days"
-};
-var PART_TEXT = {
-  ttfb: "TTFB",
-  loadDelay: "load delay",
-  loadDuration: "load duration",
-  renderDelay: "render delay",
-  inputDelay: "input delay",
-  processing: "processing",
-  presentation: "presentation"
-};
-function rangeText(range) {
-  const known = RANGE_TEXT;
-  return known[range] ?? printable(range);
-}
-function partText(name) {
-  const known = PART_TEXT;
-  return known[name] ?? printable(name);
-}
-var ATTRIBUTED = /* @__PURE__ */ new Set([
-  "lcp",
-  "inp",
-  "cls"
-]);
-var DEPLOYMENT_ROWS = 10;
-var SUBJECT_LENGTH = 50;
-function formatMs(ms) {
-  const rounded = Math.round(ms);
-  return rounded < 1e3 ? `${String(rounded)} ms` : `${(rounded / 1e3).toFixed(2)} s`;
-}
-function formatValue(metric, value) {
-  return metric === "cls" ? value.toFixed(2) : formatMs(value);
-}
-function formatChange(metric, change2) {
-  const size = formatValue(metric, Math.abs(change2));
-  if (Number.parseFloat(size) === 0) return "\xB10";
-  return change2 > 0 ? `\u25B2 +${size}` : `\u25BC \u2212${size}`;
-}
-function formatCount(count2) {
-  return Math.round(count2).toLocaleString("en-US");
-}
-function percent(part, total) {
-  return `${String(Math.round(part / total * 100))}%`;
-}
-function label2(metric) {
-  return metric.toUpperCase();
-}
-function environmentSuffix(environment) {
-  return environment === "preview" ? ", preview" : "";
-}
-function environmentWord(environment) {
-  return environment === "preview" ? "preview " : "";
-}
-function table(rows) {
-  const widths = [];
-  for (const row of rows)
-    row.forEach((cell, i) => {
-      widths[i] = Math.max(widths[i] ?? 0, cell.length);
-    });
-  return rows.map(
-    (row) => `  ${row.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ")}`.trimEnd()
-  );
-}
-function summaryLines(report) {
-  return table([
-    ["Metric", "p75", "Good", "Needs improvement", "Poor", "Visits"],
-    ...SPEED_INSIGHTS_METRICS.map((metric) => {
-      const summary = report.summary[metric];
-      if (summary.p75 === null || summary.samples <= 0)
-        return [label2(metric), "\u2014", "\u2014", "\u2014", "\u2014", "0"];
-      return [
-        label2(metric),
-        formatValue(metric, summary.p75),
-        percent(summary.good, summary.samples),
-        percent(summary.needsImprovement, summary.samples),
-        percent(summary.poor, summary.samples),
-        formatCount(summary.samples)
-      ];
-    })
-  ]);
-}
-function breakdownTable(heading, metric, rows) {
-  if (rows.length === 0) return ["  (none)"];
-  return table([
-    ["p75", "Visits", heading],
-    ...rows.map((row) => [
-      formatValue(metric, row.p75),
-      formatCount(row.samples),
-      printable(row.name)
-    ])
-  ]);
-}
-function elementLines(metric, elements) {
-  const lines = ["", `${label2(metric)} elements behind slow visits`];
-  if (elements.length === 0) return [...lines, "  (none)"];
-  for (const row of elements) {
-    lines.push(
-      `  ${printable(row.element)} on ${printable(row.route)}: ${formatCount(row.slow)} slow visits, average ${formatValue(metric, row.average)}`
-    );
-    if (row.parts && row.parts.length > 0)
-      lines.push(
-        `    ${row.parts.map((part) => `${partText(part.name)} ${formatMs(part.ms)}`).join(" \xB7 ")}`
-      );
-    if (row.url) lines.push(`    image ${printable(row.url)}`);
-  }
-  return lines;
-}
-function deploymentName(row) {
-  if (row.source === "cli" || !row.commitSha) return row.id.slice(0, 8);
-  const sha = printable(row.commitSha.slice(0, 7));
-  const subject = [
-    ...printable(row.commitMessage?.split("\n")[0]?.trim() ?? "")
-  ];
-  if (subject.length === 0) return sha;
-  return subject.length > SUBJECT_LENGTH ? `${sha} ${subject.slice(0, SUBJECT_LENGTH - 1).join("")}\u2026` : `${sha} ${subject.join("")}`;
-}
-function changeText(metric, row) {
-  if (row.samples < SPEED_INSIGHTS_MIN_DEPLOYMENT_SAMPLES)
-    return "too few visits";
-  if (row.change === null) return "\u2013";
-  return formatChange(metric, row.change);
-}
-function deploymentLines(metric, deployments, environment) {
-  if (deployments === null) return [];
-  const lines = [
-    "",
-    `${label2(metric)} by ${environmentWord(environment)}deployment, newest first`
-  ];
-  const measured = deployments.filter((row) => row.samples > 0).slice(0, DEPLOYMENT_ROWS);
-  if (measured.length === 0) return [...lines, "  (none)"];
-  return [
-    ...lines,
-    ...table([
-      ["", "p75", "Visits", "Change", "Deployment"],
-      ...measured.map((row) => [
-        row.liveUntil === null ? "Live" : "",
-        row.p75 === null ? "\u2014" : formatValue(metric, row.p75),
-        formatCount(row.samples),
-        changeText(metric, row),
-        deploymentName(row)
-      ])
-    ])
-  ];
-}
-function reportLines(report, deployments) {
-  if (!report.enabled) return [OFF_LINE];
-  const { metric, range, environment } = report;
-  const head = `Speed Insights \u2014 ${label2(metric)}, ${rangeText(range)}${environmentSuffix(environment)}`;
-  if (SPEED_INSIGHTS_METRICS.every((m) => report.summary[m].samples <= 0))
-    return [
-      head,
-      "",
-      `No ${environmentWord(environment)}measurements in the ${rangeText(range)} yet. Values arrive when visitors leave a page.`
-    ];
-  return [
-    head,
-    "",
-    ...summaryLines(report),
-    "",
-    `${label2(metric)} by page`,
-    ...breakdownTable("Page", metric, report.paths),
-    "",
-    `${label2(metric)} by device`,
-    ...breakdownTable("Device", metric, report.devices),
-    ...ATTRIBUTED.has(metric) ? elementLines(metric, report.elements) : [],
-    ...deploymentLines(metric, deployments, environment)
-  ];
-}
-function routePathsLines(result) {
-  return [
-    `${label2(result.metric)} p75 under ${printable(result.route)}, ${rangeText(result.range)}${environmentSuffix(result.environment)}`,
-    ...breakdownTable("Path", result.metric, result.paths)
-  ];
-}
-
 // src/commands/insights.ts
-function queryOf(flags) {
+function queryOf2(flags) {
+  const filters = filtersOf(flags, SPEED_INSIGHTS_FILTER_KEYS);
   return {
     ...flags.range !== void 0 ? { range: flags.range } : {},
     ...flags.metric !== void 0 ? { metric: flags.metric } : {},
-    ...flags.env !== void 0 ? { environment: flags.env } : {}
+    ...flags.env !== void 0 ? { environment: flags.env } : {},
+    ...Object.keys(filters).length > 0 ? { filters } : {}
   };
 }
 async function runInsights(context) {
+  if (context.flags.referrer !== void 0 && context.flags.referrer !== "")
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      "Speed Insights has no referrer; drop --referrer."
+    );
   const client = await context.client();
   const projectId = await context.resolveProjectId();
-  const query = queryOf(context.flags);
+  const query = queryOf2(context.flags);
+  const filters = query.filters ?? {};
   if (context.flags.route !== void 0) {
     const result = await client.insights.paths(projectId, {
       ...query,
       route: context.flags.route
     });
-    context.output.result({ projectId, ...result }, routePathsLines(result));
+    context.output.result(
+      { projectId, ...result },
+      routePathsLines(result, filters)
+    );
     return;
   }
   const overview = await client.insights.overview(projectId, query);
@@ -4792,7 +4925,7 @@ async function runInsights(context) {
     );
   context.output.result(
     { projectId, ...overview },
-    reportLines(overview.report, overview.deployments)
+    reportLines(overview.report, overview.deployments, filters)
   );
 }
 async function setInsights(context, enabled) {
@@ -4801,6 +4934,12 @@ async function setInsights(context, enabled) {
       "VALIDATION_FAILED",
       "Speed Insights has one switch for production and preview; drop --env."
     );
+  const filter = givenFilterFlag(context.flags);
+  if (filter !== void 0)
+    throw new NaroError(
+      "VALIDATION_FAILED",
+      `Filters only narrow a report; drop --${filter}.`
+    );
   const client = await context.client();
   const projectId = await context.resolveProjectId();
   const result = await client.insights.setEnabled(projectId, enabled);
@@ -8061,9 +8200,13 @@ Usage:
   naro logs [deployment-id]          Runtime logs (or build logs of a deployment)
        [--type build|runtime] [--env production|preview] [--level error] [--follow]
 
-  naro insights [--metric lcp] [--range 7d] [--env preview]
+  naro analytics [--range 7d] [--path p] [--referrer host] [--country KR] [--device mobile] [--browser safari] [--os ios]
+                                     Web Analytics: visitors and page views, then the top pages,
+                                     referrers, countries, devices, browsers and operating systems
+  naro insights [--metric lcp] [--range 7d] [--env preview] [--path p] [--country KR] [--device mobile] [--browser safari] [--os ios]
                                      Speed Insights: Web Vitals p75 by page, device, the elements
-                                     behind slow visits and deployment (production by default)
+                                     behind slow visits and deployment, and the page load: its p75
+                                     and the mean of each step (production by default)
   naro insights --route '/posts/[id]'  The paths opened under one route
   naro insights enable | disable     Turn measuring on or off (production pages get a
                                      same-origin script, preview pages too; past measurements are kept)
@@ -8221,8 +8364,14 @@ Global options:
   --prod          Deploy/target production
   --wait          Poll until the domain goes live (naro domains verify)
   --metric <m>    lcp, inp, cls, fcp or ttfb; lcp by default (naro insights)
-  --range <r>     24h, 7d or 30d; 7d by default (naro insights)
+  --range <r>     24h, 7d or 30d; 7d by default (naro analytics, naro insights)
   --route <pattern>  A route from the pages table, e.g. '/posts/[id]': the paths under it (naro insights)
+  --path <p>      Only this page, starting with /, e.g. /pricing (naro analytics, naro insights)
+  --referrer <host>  Only visits that came from this lowercase host, e.g. t.co (naro analytics only: Speed Insights has no referrer)
+  --country <cc>  Only this country, an uppercase two-letter code like KR (naro analytics, naro insights)
+  --device <d>    Only this device: desktop, mobile or tablet (naro analytics, naro insights)
+  --browser <b>   Only this browser: chrome, edge, firefox, opera, safari or other (naro analytics, naro insights)
+  --os <o>        Only this operating system: android, ios, linux, macos, windows or other (naro analytics, naro insights)
   --env <e>       production or preview (naro logs, naro insights: production by default; naro env pull: preview by default)
   --no-www        Register the apex alone (naro domains add)
   --file <path>   SQL file to run (naro db query, naro policy create)
@@ -8438,6 +8587,9 @@ function route(parsed) {
       return { handler: runCancel, positionals };
     case "logs":
       return { handler: runLogs, positionals };
+    // Spec 2026-10-08-analytics-cli-pageload §5.
+    case "analytics":
+      return positionals.length === 0 ? { handler: runAnalytics, positionals: [] } : null;
     // Spec 2026-10-08 §5.
     case "insights": {
       if (positionals.length > 1) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "bin": {
     "naro": "./dist/index.js"
@@ -34,11 +34,11 @@
     "typescript": "7.0.2",
     "vitest": "3.2.7",
     "naro-js": "0.3.0",
-    "@next-deploy/data-core": "0.1.0",
     "@next-deploy/build": "0.1.0",
     "@next-deploy/config": "0.1.0",
     "@next-deploy/core": "0.1.0",
-    "@next-deploy/sdk": "0.1.0"
+    "@next-deploy/sdk": "0.1.0",
+    "@next-deploy/data-core": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",