rootr-cli 0.29.0 → 0.30.1

package/README.md

@@ -11,7 +11,7 @@ citations back to the exact paragraph.
 *(한국어 문서: [README.ko.md](https://github.com/gwmage/rootr-cli/blob/main/README.ko.md))*
 
 - `rootr` CLI — documents, databases, forms, signed documents, publishing, permissions, memory
-- `rootr mcp` — stdio MCP server, **214 tools** (see [MCP tools](#mcp-tools))
+- `rootr mcp` — stdio MCP server, **217 tools** (see [MCP tools](#mcp-tools))
 
 Plain Node.js ESM, no build step. Node 18+ (uses the built-in `fetch`).
 
@@ -331,6 +331,21 @@ cannot hold a CNAME — connect `www.` and forward the root to it (the guide sho
 Only when the same name was registered before by a *different* workspace, one extra `TXT` line
 (`_rootr-verify.www`) is required, so nobody can take over a domain whose CNAME was left behind.
 
+### Page visit tracking
+
+Turn on GA-style tracking for a published PAGE. The numbers land in ordinary workspace nodes next to the page —
+an "Analytics" folder with a visit **LOG** (one entry per visit, scroll depth, block seen, click, form / booking
+step, time on page — with channel, utm, device, in-app browser, country), a **daily visits table** (one row per
+KST day, refilled every 15 minutes) and a **dashboard page** of live charts. Only the published address records;
+no cookies, IPs are not stored.
+
+```bash
+rootr page track /홈페이지 on                    # create the folder + log + daily table + dashboard and start recording
+rootr page stats /홈페이지                       # last 7 days visitors / sessions / conversions + where the nodes are
+rootr page recount /홈페이지 --days 30           # recount the daily table now
+rootr page track /홈페이지 off                   # stop recording (every node stays)
+```
+
 ### Signed documents and research notes
 
 A signed document is a markdown document whose body **freezes the moment it is submitted**; the
@@ -489,7 +504,7 @@ is refused and says when the grace was used.
 
 ## MCP tools
 
-`rootr mcp` speaks MCP over stdio. 214 tools:
+`rootr mcp` speaks MCP over stdio. 217 tools:
 
 | Group | Count | Tools |
 |---|---|---|
@@ -501,7 +516,7 @@ is refused and says when the grace was used.
 | Forms | 10 | create, read, update, responses, share links, collectors |
 | Presentations & images | 10 | decks, slides, diagram slides, image generation and background removal |
 | Workspaces & scaffolding | 10 | list, create, delete, switch, set the emblem (sidebar logo), plan / review / apply a document tree, health check |
-| Pages | 6 | HTML page nodes: create, read, update, append and patch blocks, live data |
+| Pages | 7 | HTML page nodes: create, read, update, append and patch blocks, live data, visit tracking (GA-style visits / scroll / conversions stored as a LOG, a daily table and a dashboard) |
 | Spreadsheets | 7 | create, read, update, per-sheet create/update/delete, patch cells & formulas |
 | Recordings | 7 | create, upload & download audio, transcribe, summarize, rename speakers |
 | Issue tracker | 6 | create tracker, list / create / get / update issue, comment |

package/bin/rootr.js

@@ -120,6 +120,9 @@ const USAGE_KO = `Rootr CLI v${pkg.version}
   rootr mail webhook add <url> [--events …] | list | rm <id> | test <id>
                                                    받은 문서·회수·읽음을 내 주소로 알려 주는 웹훅(내 계정 것, HMAC 서명)
                                                    ※ 다른 명령 뒤 새로 받은 문서가 있으면 stderr 로 한 줄 알림(끄기: ROOTR_MAIL_NOTICE=0)
+  rootr page stats <페이지 path|id> [--json]       방문 기록 상태 — 최근 7일 방문자·방문·전환, 기록(LOG)·일별 표·대시보드 위치
+  rootr page track <페이지 path|id> on|off [--locale ko|en]  방문 기록 켜기(페이지 옆에 「방문 분석」 폴더: 방문 기록 LOG·일별 방문 표·대시보드)·끄기(노드는 남음)
+  rootr page recount <페이지 path|id> [--days 90]  일별 방문 표를 지금 다시 세기(보통은 15분마다 자동)
   rootr domain list                                내 도메인 목록 — 종류(내 도메인·무료 주소)·상태와 가리키는 페이지, 자리 사용(유료 n/m·무료 n/3)
   rootr domain detect <도메인> [--provider <업체>]   등록 전에 — DNS 를 어디서 관리하는지(가비아·Cloudflare…)와 넣을 한 줄·단계 안내
   rootr domain add <도메인> <페이지·문서 path|id> [--provider <업체>] [--confirm-charge]  발행한 페이지·문서를 내 도메인(www.회사.co.kr)으로 연결 (Team 플랜, 도메인 1개당 월 $10·연 결제 시 월 $8 — 자리가 꽉 찼으면 --confirm-charge 로 1개 추가 결제)
@@ -256,6 +259,9 @@ usage:
   rootr mail access <id> read|comment|write        change what the recipient of a document you sent can do
   rootr mail revoke <id>                           withdraw a document you sent — the recipient can no longer open the original
   rootr mail hide <id> [--box inbox|sent]          remove from your own mailbox (a received one then stops opening for your account)
+  rootr page stats <page path|id> [--json]         visit tracking status — last 7 days visitors/sessions/conversions, where the log, daily table and dashboard are
+  rootr page track <page path|id> on|off [--locale ko|en]  turn visit tracking on (an "Analytics" folder next to the page: visit LOG, daily visits table, dashboard) or off (nodes stay)
+  rootr page recount <page path|id> [--days 90]    recount the daily visits table now (normally every 15 minutes)
   rootr domain list                                your custom domains — status (waiting for DNS / issuing certificate / connected) and page
   rootr domain detect <domain> [--provider <id>]   before adding — where the DNS is managed (Gabia, Cloudflare…), the one line to add, step by step
   rootr domain add <domain> <page|doc path|id> [--provider <id>] [--confirm-charge]  open a published page or document at your own domain (Team plan; $10/month per domain, $8 billed yearly — when slots are full, --confirm-charge buys one more)
@@ -3287,6 +3293,16 @@ async function cmdDbRowPageType(args) {
 }
 
 /** 경로로 줘도 되게 — 표 인자도 문서 도구들과 같은 규칙을 따른다. */
+/**
+ * 노드 id·"/경로"·루터 주소 어느 것이든 노드 id 로. (예전엔 이 이름을 부르기만 하고 정의가 없어 `rootr form mapping` 이
+ * "resolveNodeId is not defined" 로 죽었다 — 2026-10-25 page 명령을 실제로 불러 보다 발견.)
+ */
+async function resolveNodeId(client, target) {
+  const resolved = await resolveTarget(client, target);
+  if (resolved.existed === false) throw new Error(tr(`찾을 수 없습니다: ${target}`, `Not found: ${target}`));
+  return resolved.id ?? target;
+}
+
 async function resolveDatabaseId(client, target) {
   if (typeof target === 'string' && target.startsWith('/')) {
     const resolved = await resolveTarget(client, target);
@@ -3845,6 +3861,46 @@ function printDomainStatus(d) {
   if (d.message || d.lastError) console.log(`  ${d.message || d.lastError}`);
 }
 
+/**
+ * PAGE-ANALYTICS — `rootr page stats|track|recount <page>`. 방문 기록은 워크스페이스 노드(LOG·일별 표·대시보드)에 쌓인다 —
+ * 숫자를 더 깊게 보려면 `rootr db rows <일별 표>`·`rootr log query <방문 기록>` 을 그대로 쓴다.
+ */
+async function cmdPage(args) {
+  const sub = args._[0];
+  const target = args._[1];
+  const usageText = tr(
+    'rootr page stats <페이지> | rootr page track <페이지> on|off [--locale ko|en] | rootr page recount <페이지> [--days 90]',
+    'rootr page stats <page> | rootr page track <page> on|off [--locale ko|en] | rootr page recount <page> [--days 90]',
+  );
+  if (!target || !['stats', 'track', 'recount'].includes(sub)) throw new Error(usageText);
+  const client = makeClient();
+  const id = await resolveNodeId(client, target);
+  let out;
+  if (sub === 'track') {
+    const mode = args._[2];
+    if (mode !== 'on' && mode !== 'off') throw new Error(usageText);
+    out = await client.setPageAnalytics(id, { enabled: mode === 'on', locale: args.locale });
+  } else if (sub === 'recount') {
+    out = (await client.refreshPageAnalytics(id, args.days)).status;
+  } else {
+    out = await client.getPageAnalytics(id);
+  }
+  if (args.json) return console.log(JSON.stringify(out, null, 2));
+  console.log(out.enabled ? tr('방문 기록: 켜짐', 'Visit tracking: on') : tr('방문 기록: 꺼짐', 'Visit tracking: off'));
+  if (out.last7d) {
+    console.log(tr(
+      `최근 7일  방문자 ${out.last7d.visitors} · 방문 ${out.last7d.sessions} · 전환 ${out.last7d.conversions}`,
+      `Last 7 days  visitors ${out.last7d.visitors} · sessions ${out.last7d.sessions} · conversions ${out.last7d.conversions}`,
+    ));
+  }
+  for (const [label, n] of [[tr('대시보드', 'Dashboard'), out.dashboard], [tr('일별 표', 'Daily table'), out.daily], [tr('방문 기록', 'Visit log'), out.log]]) {
+    if (n) console.log(`  ${label}\t${n.name}\t${n.id}${n.url ? `\t${n.url}` : ''}`);
+  }
+  if (out.enabled && !out.lastEventAt) {
+    console.log(tr('  아직 기록 없음 — 웹에 게시된 주소에서만 기록됩니다(rootr publish).', '  No visits yet — only the published address records (rootr publish).'));
+  }
+}
+
 async function cmdDomain(args) {
   const sub = args._[0];
   const client = makeClient();
@@ -4040,6 +4096,9 @@ async function main() {
     case 'domain':
     case 'domains':
       return cmdDomain(args);
+    case 'page':
+    case 'pages':
+      return cmdPage(args);
     case 'feedback':
       return cmdFeedback(args);
     case 'scaffold':

package/lib/client.js

@@ -1700,6 +1700,20 @@ export class RootrClient {
     return this.request(`/pages/${encodeURIComponent(pageId)}/live-data`);
   }
 
+  // PAGE-ANALYTICS — 방문 기록(켜면 LOG·일별 표·대시보드가 페이지 옆에 선다)
+  async getPageAnalytics(pageId) {
+    return this.request(`/pages/${encodeURIComponent(pageId)}/analytics`);
+  }
+
+  async setPageAnalytics(pageId, { enabled, locale } = {}) {
+    return this.request(`/pages/${encodeURIComponent(pageId)}/analytics`, { method: 'POST', body: { enabled, ...(locale ? { locale } : {}) } });
+  }
+
+  async refreshPageAnalytics(pageId, days) {
+    const q = days ? `?days=${encodeURIComponent(days)}` : '';
+    return this.request(`/pages/${encodeURIComponent(pageId)}/analytics/refresh${q}`, { method: 'POST' });
+  }
+
   // ---- Presentations (slide decks) ----------------------------------------
 
   async createPresentation(workspaceId, { name, parentId, theme, slides, config, icon } = {}) {

package/lib/mcp-tools/pages.js

@@ -100,8 +100,9 @@ const BLOCK_GUIDE =
   'that name. The server resolves it and stores the id (the response shows the id). A path or name it cannot resolve — ' +
   'missing, not readable by you, wrong node type, or a name shared by two nodes — is rejected with 400 and NOTHING is ' +
   'saved; it is never stored as a silently empty block. `column`/`labelColumn`/' +
-  '`valueColumn`/`orderBy.column` are the column NAMES as shown in the table (not column ids). A table or form that ' +
-  'sits in a PRIVATE subtree is silently skipped on the published page — that is deliberate, never a bug to work around.\n' +
+  '`valueColumn`/`orderBy.column` are the column NAMES as shown in the table (not column ids). A live-block source table ' +
+  'that sits in a PRIVATE subtree is silently skipped on the published page (inside the app whoever can open it still sees ' +
+  'it) — that is deliberate, never a bug to work around. Form and booking blocks are not affected by PRIVATE.\n' +
   'LINKS: every `target` is {kind:"url", href} (absolute http(s)://, mailto: or tel: only), {kind:"node", nodeId} ' +
   'for a document in the same workspace, or {kind:"block", blockId} to JUMP TO ANOTHER BLOCK ON THIS SAME PAGE ' +
   '(e.g. a hero button "Book a free consult" → the booking block further down: smooth scroll in the same tab, no new tab — ' +
@@ -293,7 +294,7 @@ export function registerPageTools(server) {
         '(category {labels, series[]} · single {value, previous, goal, spark} · xy · distribution · tree · flow · ohlc · range). ' +
         'A chart that cannot draw says why: `{shape:"empty", reason:"column_missing"|"no_rows"|"needs_number", column}` — ' +
         'fix that column name or filter. A block missing from the result means its source was not found, is deleted, ' +
-        'or sits in a PRIVATE subtree.',
+        'or you cannot open it.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         pageId: z.string().describe(`PAGE node id${NODE_TARGET_HINT}`),
@@ -309,4 +310,41 @@ export function registerPageTools(server) {
       }
     },
   );
+  server.registerTool(
+    'rootr_page_analytics',
+    {
+      title: 'Turn on / read visit tracking for a published page',
+      description:
+        'GA-style visit tracking for a Rootr (루터) PAGE, stored in the workspace itself. action "enable" creates, next to the page, ' +
+        'a folder "<page> · 방문 분석" (Analytics) holding: a LOG node (one entry per visitor action — visit, scroll 25/50/75/90%, ' +
+        'block seen, click, form seen/started/submitted, booking steps, time on page — with channel/utm/referrer/device/browser/' +
+        'country columns), a DATABASE "일별 방문" (Daily visits: one row per KST day — visitors, sessions, new visitors, page views, ' +
+        'avg seconds, read-half/read-to-end sessions, clicks, form submits, bookings, conversions, conversion rate; filled every 15 min), ' +
+        'and a PAGE dashboard of live charts over both. Read the numbers with rootr_read_database (daily table), ' +
+        'rootr_query_log_entries / rootr_log_stats (the log) or rootr_read_page_live_data (the dashboard). ' +
+        'Only the PUBLISHED page records (rootr_publish_node, Team plan); the editor preview never does. "disable" stops recording ' +
+        'and keeps every node. "refresh" recounts the daily table now (default 90 days). "status" (default) returns the node ids, ' +
+        'last visit time and last-7-day totals. Field names follow `locale` (ko|en, first enable only). No cookies; visitors are ' +
+        'random per-page tags, IPs are never stored.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        pageId: z.string().describe(`PAGE node id${NODE_TARGET_HINT}`),
+        action: z.enum(['status', 'enable', 'disable', 'refresh']).optional().describe('default "status"'),
+        locale: z.enum(['ko', 'en']).optional().describe('column/node names on first enable (default ko)'),
+        days: z.number().int().min(1).max(400).optional().describe('refresh: how many days back to recount (default 90)'),
+      },
+    },
+    async ({ pageId, action, locale, days }) => {
+      try {
+        const client = makeClient();
+        pageId = await resolveNodeId(client, pageId);
+        if (action === 'enable') return jsonResult(await client.setPageAnalytics(pageId, { enabled: true, locale }));
+        if (action === 'disable') return jsonResult(await client.setPageAnalytics(pageId, { enabled: false }));
+        if (action === 'refresh') return jsonResult(await client.refreshPageAnalytics(pageId, days));
+        return jsonResult(await client.getPageAnalytics(pageId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/workspaces.js

@@ -54,6 +54,7 @@ const ACCESS_HINT =
   'Any property may carry `align: "left"|"center"|"right"` and `wrap: true`; a date property `highlightOverdue: true` ' +
   '(past dates red — off by default), `allowTime: false` (no time) and `allowRange: false` (no end date). A table view ' +
   'config may carry `density: "compact"` and `frozenColumns: 1` (first N visible columns fixed while scrolling sideways). ' +
+  'A PAGE node may carry `page.analytics: true` (visit tracking — an "Analytics" folder with a visit LOG, a daily visits table and a dashboard is created next to it; records once published). ' +
   'A DOCUMENT\'s `content` may embed a live ' +
   'table/sheet/deck with a line `[[embed:<name of a node in this same tree>]]` or `[[embed:/absolute/path]]` — it is ' +
   'linked to the real node after the whole tree is built (an unknown name rolls the whole tree back).';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
   "type": "module",
   "bin": {