driggsby 0.2.3 → 0.3.0

package/dist/dev/dev-state.js

@@ -0,0 +1,196 @@
+// The record of the one `driggsby dev` running on this machine:
+// ~/.driggsby/dev.json, written after both ports bind and removed when the
+// run ends. `dev --stop` reads it to find the process, and a second `dev`
+// reads it to say which folder already holds the ports. A file whose pid is
+// no longer alive (the machine rebooted, the process was killed hard) is
+// stale and treated as absent. It holds no credentials.
+import { lstat, readFile, rm } from "node:fs/promises";
+import { Agent, request as httpRequest } from "node:http";
+import { join } from "node:path";
+import { driggsbyDirectory, writeOwnerOnlyFile } from "../owner-only-file.js";
+const STATE_FILE_NAME = "dev.json";
+// The host origin answers this with the pid of the dev serving it, so a
+// record can be checked against the process actually holding the port.
+export const DEV_IDENTITY_PATH = "/-/dev-identity";
+const IDENTITY_TIMEOUT_MS = 1_000;
+// Whole-probe deadline: the socket timeout above resets on every byte, so a
+// port that dribbles bytes would otherwise hold the probe open for ever;
+// the abort surfaces as a request error, which reads as no answer.
+const IDENTITY_DEADLINE_MS = 2_000;
+const IDENTITY_ATTEMPTS = 2;
+const IDENTITY_RETRY_PAUSE_MS = 100;
+const IDENTITY_MAX_BYTES = 4_096;
+// The record is a few short fields; anything larger is not ours.
+const STATE_MAX_BYTES = 4_096;
+// Node routes fetch AND the default http agent through a proxy named in the
+// environment (NODE_USE_ENV_PROXY with HTTP_PROXY); an agent built here
+// carries no such configuration, so the identity probe below can never
+// leave the loopback interface.
+const LOOPBACK_AGENT = new Agent({ keepAlive: false });
+export function devStatePath(homeDirectory) {
+    return join(driggsbyDirectory(homeDirectory), STATE_FILE_NAME);
+}
+export async function writeDevState(homeDirectory, state) {
+    await writeOwnerOnlyFile(homeDirectory, STATE_FILE_NAME, `${JSON.stringify(state, null, 2)}\n`);
+}
+export function defaultDevProbes() {
+    return { isAlive: processIsAlive, pidServing: devPidServing };
+}
+export async function readDevState(homeDirectory, probes = defaultDevProbes()) {
+    const state = await readDevStateFile(homeDirectory);
+    if (state === null) {
+        return { status: "none", state: null };
+    }
+    if (state === "malformed") {
+        await rm(devStatePath(homeDirectory), { force: true });
+        return { status: "none", state: null };
+    }
+    if (!probes.isAlive(state.pid)) {
+        await removeDevState(homeDirectory, state.pid);
+        return { status: "none", state: null };
+    }
+    return (await probes.pidServing(state.hostPort)) === state.pid
+        ? { status: "live", state }
+        : { status: "unconfirmed", state };
+}
+// The state of a dev that is confirmed running, or null.
+export async function readLiveDevState(homeDirectory, probes = defaultDevProbes()) {
+    const read = await readDevState(homeDirectory, probes);
+    return read.status === "live" ? read.state : null;
+}
+// Asks the host origin on `hostPort` which pid serves it; null when nothing
+// answers, or whatever answers is not a driggsby dev. A short pause and one
+// retry cover a transient socket failure.
+export async function devPidServing(hostPort) {
+    for (let attempt = 0; attempt < IDENTITY_ATTEMPTS; attempt += 1) {
+        if (attempt > 0) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, IDENTITY_RETRY_PAUSE_MS);
+            });
+        }
+        const pid = await askIdentity(hostPort);
+        if (pid !== null) {
+            return pid;
+        }
+    }
+    return null;
+}
+// Loopback only, on LOOPBACK_AGENT. No redirect is followed (anything but
+// 200 is no answer), and the body is read bounded, because whatever holds
+// that port is untrusted.
+function askIdentity(hostPort) {
+    return new Promise((settle) => {
+        const request = httpRequest({
+            host: "127.0.0.1",
+            port: hostPort,
+            path: DEV_IDENTITY_PATH,
+            method: "GET",
+            timeout: IDENTITY_TIMEOUT_MS,
+            signal: AbortSignal.timeout(IDENTITY_DEADLINE_MS),
+            agent: LOOPBACK_AGENT,
+        }, (response) => {
+            if (response.statusCode !== 200) {
+                response.resume();
+                settle(null);
+                return;
+            }
+            const chunks = [];
+            let total = 0;
+            response.on("data", (chunk) => {
+                total += chunk.byteLength;
+                if (total > IDENTITY_MAX_BYTES) {
+                    request.destroy();
+                    settle(null);
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on("end", () => {
+                settle(pidFromIdentityBody(Buffer.concat(chunks).toString("utf8")));
+            });
+            response.on("error", () => {
+                settle(null);
+            });
+        });
+        request.on("timeout", () => {
+            request.destroy();
+        });
+        request.on("error", () => {
+            settle(null);
+        });
+        request.end();
+    });
+}
+function pidFromIdentityBody(body) {
+    try {
+        const payload = JSON.parse(body);
+        const pid = typeof payload === "object" && payload !== null ? payload.pid : null;
+        return isPid(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Removes the file only if it still names `pid`: a dev that ends must never
+// erase the record of a newer dev that took the ports after it.
+export async function removeDevState(homeDirectory, pid) {
+    const state = await readDevStateFile(homeDirectory);
+    if (state === null) {
+        return;
+    }
+    if (state === "malformed" || state.pid === pid) {
+        await rm(devStatePath(homeDirectory), { force: true });
+    }
+}
+export function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to someone else.
+        return error.code === "EPERM";
+    }
+}
+// Only a small regular file is read: a symlink, a device, or anything
+// oversized at that path is not our record.
+async function readDevStateFile(homeDirectory) {
+    const path = devStatePath(homeDirectory);
+    let raw;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > STATE_MAX_BYTES) {
+            return "malformed";
+        }
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return isDevState(parsed) ? parsed : "malformed";
+    }
+    catch {
+        return "malformed";
+    }
+}
+function isDevState(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (isPid(record.pid) &&
+        typeof record.folder === "string" &&
+        typeof record.startedAt === "string" &&
+        isPort(record.hostPort) &&
+        isPort(record.appPort));
+}
+// Only a real, positive pid: 0 and negatives are process groups to kill(2),
+// and a record must never turn into a broadcast signal.
+function isPid(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isPort(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65_535;
+}

package/dist/dev/dev-stop.js

@@ -0,0 +1,76 @@
+// driggsby dev --stop: end the `driggsby dev` running on this machine from
+// any terminal, so an agent that started one in the background can put the
+// ports (and the live-data preview) away without hunting for the process.
+// The record in ~/.driggsby/dev.json is trusted only after the recorded
+// port confirms it is served by the recorded pid (see readDevState).
+import { CliError } from "../cli-error.js";
+import { DEV_START_COMMAND, DEV_STOP_COMMAND } from "./dev-commands.js";
+import { defaultDevProbes, readDevState, removeDevState } from "./dev-state.js";
+import { displayFolder } from "./display-folder.js";
+// How many waits of `waitMs` a signalled dev gets to go before we report it.
+const STOP_ATTEMPTS = 20;
+function defaultDevStopDeps() {
+    return {
+        ...defaultDevProbes(),
+        terminate: (pid) => {
+            process.kill(pid, "SIGTERM");
+        },
+        waitMs: 250,
+    };
+}
+function defaultDevStopIo() {
+    return {
+        out: (text) => {
+            process.stdout.write(text);
+        },
+    };
+}
+export async function runDevStop(homeDirectory, io = defaultDevStopIo(), deps = defaultDevStopDeps()) {
+    const read = await readDevState(homeDirectory, deps);
+    if (read.status === "none") {
+        io.out(nothingRunning());
+        return 0;
+    }
+    const state = read.state;
+    const folder = displayFolder(state.folder);
+    if (read.status === "unconfirmed") {
+        // The pid is alive but the port did not answer as that dev: it may be
+        // busy, or the pid may have been recycled. Never signal a process the
+        // port has not vouched for, and never claim nothing is running.
+        throw new CliError(`driggsby dev is recorded for the app in:\n  ${folder}\n\n` +
+            "but didn't answer, so it wasn't stopped. If it's still running, press\n" +
+            `Ctrl+C in the terminal where it runs, then try again:\n  ${DEV_STOP_COMMAND}\n\n` +
+            `If nothing is running there, the next driggsby dev replaces this record.`, 1);
+    }
+    try {
+        deps.terminate(state.pid);
+    }
+    catch (error) {
+        // Gone between the check and the signal, or a pid that is not ours to
+        // signal (another user's process): either way there is no dev to stop.
+        // Any other failure leaves the record, since the dev may well be running.
+        const code = error.code;
+        if (code === "ESRCH" || code === "EPERM") {
+            await removeDevState(homeDirectory, state.pid);
+            io.out(nothingRunning());
+            return 0;
+        }
+        throw error;
+    }
+    for (let attempt = 0; attempt < STOP_ATTEMPTS; attempt += 1) {
+        if (!deps.isAlive(state.pid)) {
+            await removeDevState(homeDirectory, state.pid);
+            io.out(`✓ Stopped   driggsby dev for the app in:\n  ${folder}\n\nStart it again with:\n  ${DEV_START_COMMAND}\n`);
+            return 0;
+        }
+        await new Promise((resolve) => {
+            setTimeout(resolve, deps.waitMs);
+        });
+    }
+    throw new CliError(`driggsby dev was asked to stop but is still running for the app in:\n  ${folder}\n\n` +
+        "Press Ctrl+C in the terminal where it runs, then check again:\n" +
+        `  ${DEV_STOP_COMMAND}`, 1);
+}
+function nothingRunning() {
+    return `No driggsby dev is running on this machine.\n\nStart one in an app's folder with:\n  ${DEV_START_COMMAND}\n`;
+}

package/dist/dev/display-folder.js

@@ -0,0 +1,23 @@
+// A project folder as printed in `dev` messages: the person's home shortens
+// to "~" so the common case fits a terminal line, and the result goes
+// through quotedForTerminal because a path is text this CLI did not author.
+import { homedir } from "node:os";
+import { isAbsolute, relative, sep } from "node:path";
+import { quotedForTerminal } from "../terminal-text.js";
+const MAX_FOLDER_CHARS = 200;
+export function displayFolder(folder, home = homedir()) {
+    return quotedForTerminal(homeRelative(folder, home), MAX_FOLDER_CHARS);
+}
+function homeRelative(folder, home) {
+    if (home === "" || !isAbsolute(folder)) {
+        return folder;
+    }
+    const inside = relative(home, folder);
+    if (inside === "") {
+        return "~";
+    }
+    if (inside.startsWith("..") || isAbsolute(inside)) {
+        return folder;
+    }
+    return `~${sep}${inside}`;
+}

package/dist/dev/host-page.js

@@ -82,12 +82,56 @@ export const HOST_PAGE_JS = [
     "",
     "let appRoute = sanitizeAppRoute(window.location.hash);",
     "",
-    "// URL writes are bounded (leading + one trailing per window) because",
-    "// the frame controls their rate, and each write is guarded: Safari",
-    "// hard-errors on rapid replaceState bursts.",
-    "const ROUTE_WRITE_WINDOW_MS = 1000;",
+    "// URL writes are bounded because the frame controls their rate, but",
+    "// ordinary clicking should not feel the bound — a token bucket does",
+    "// both, matching the production host: a flurry of up to 15",
+    "// navigations writes instantly, sustained clicking faster than one",
+    "// per 600ms then paces at 600ms, and a frame spamming routes drains",
+    "// the bucket and degrades to paced trailing writes that still land",
+    "// the final state. Burst (15) plus refills (one per 600ms = 50 per",
+    "// 30s) tops out at 65 writes per 30s, leaving at least ~35 of",
+    "// Safari's ~100-per-30s per-document replaceState budget for the",
+    "// host page's own writes. Keep these two constants identical to the",
+    "// production host's; nothing pins them across the two codebases.",
+    "const ROUTE_WRITE_BUCKET_CAPACITY = 15;",
+    "const ROUTE_WRITE_REFILL_MS = 600;",
+    "let routeTokens = ROUTE_WRITE_BUCKET_CAPACITY;",
+    "let routeLastRefillMs = Date.now();",
     "let routeWriteTimer = null;",
     "",
+    "function refillRouteTokens() {",
+    "  const now = Date.now();",
+    "  // A backward clock step would otherwise strand the refill mark in",
+    "  // the future and stall every write until the clock caught back up.",
+    "  if (now < routeLastRefillMs) {",
+    "    routeLastRefillMs = now;",
+    "  }",
+    "  const earned = Math.floor((now - routeLastRefillMs) / ROUTE_WRITE_REFILL_MS);",
+    "  if (earned < 1) {",
+    "    return;",
+    "  }",
+    "  routeTokens = Math.min(ROUTE_WRITE_BUCKET_CAPACITY, routeTokens + earned);",
+    "  routeLastRefillMs += earned * ROUTE_WRITE_REFILL_MS;",
+    "}",
+    "",
+    "function takeRouteToken() {",
+    "  refillRouteTokens();",
+    "  if (routeTokens < 1) {",
+    "    return false;",
+    "  }",
+    "  routeTokens -= 1;",
+    "  return true;",
+    "}",
+    "",
+    "function routeRetryDelayMs() {",
+    "  refillRouteTokens();",
+    "  if (routeTokens >= 1) {",
+    "    return 1;",
+    "  }",
+    "  const sinceRefill = Date.now() - routeLastRefillMs;",
+    "  return Math.min(ROUTE_WRITE_REFILL_MS, Math.max(1, ROUTE_WRITE_REFILL_MS - sinceRefill));",
+    "}",
+    "",
     "function writeRouteToUrl() {",
     "  if (window.location.hash === appRoute) {",
     "    return;",
@@ -100,16 +144,33 @@ export const HOST_PAGE_JS = [
     "  }",
     "}",
     "",
+    "function scheduleTrailingRouteWrite() {",
+    "  routeWriteTimer = setTimeout(() => {",
+    "    routeWriteTimer = null;",
+    "    if (takeRouteToken()) {",
+    "      writeRouteToUrl();",
+    "    } else {",
+    "      // The clock can land a hair before the token accrues; wait out",
+    "      // the remainder rather than writing over budget.",
+    "      scheduleTrailingRouteWrite();",
+    "    }",
+    "  }, routeRetryDelayMs());",
+    "}",
+    "",
     "function applyRoute(hash) {",
     "  appRoute = hash;",
     "  if (routeWriteTimer !== null) {",
+    "    return; // the trailing write reads appRoute",
+    "  }",
+    "  // Already mirrored: nothing to write, no token spent on nothing.",
+    "  if (window.location.hash === hash) {",
     "    return;",
     "  }",
-    "  writeRouteToUrl();",
-    "  routeWriteTimer = setTimeout(() => {",
-    "    routeWriteTimer = null;",
+    "  if (takeRouteToken()) {",
     "    writeRouteToUrl();",
-    "  }, ROUTE_WRITE_WINDOW_MS);",
+    "    return;",
+    "  }",
+    "  scheduleTrailingRouteWrite();",
     "}",
     "",
     "function postToApp(message) {",

package/dist/dev/mcp-broker.js

@@ -4,6 +4,7 @@
 // { ok, result | error } envelope. Bounds mirror the production host: a few
 // calls in flight, a bounded queue, and a hard per-call timeout, so a
 // buggy app can hammer its own laptop but never Driggsby.
+import { capForTerminal, sanitizeForTerminal } from "../terminal-text.js";
 import { GENERIC_TOOL_TROUBLE } from "./dev-servers.js";
 export const MAX_IN_FLIGHT_CALLS = 4;
 export const MAX_QUEUED_CALLS = 64;
@@ -16,8 +17,9 @@ export const SIGN_IN_AGAIN_MESSAGE = "Your sign-in on this machine isn't valid a
 // endpoint requires a short reason on most read tools; a locally previewed
 // dashboard has exactly one.
 const DEFAULT_REASON = "Rendering this data in the developer's own Driggsby app preview.";
-// One broker per `driggsby dev` run. runToolCall never rejects — every
-// failure becomes an { ok: false } envelope with a person-readable message.
+// One broker per `driggsby dev` run (or per `driggsby query`). With the
+// default transportErrors, runToolCall never rejects — every failure
+// becomes an { ok: false } envelope with a person-readable message.
 export class McpBroker {
     options;
     queue = [];
@@ -30,8 +32,8 @@ export class McpBroker {
         if (this.queue.length >= MAX_QUEUED_CALLS) {
             return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
         }
-        return await new Promise((resolve) => {
-            this.queue.push({ tool, argumentsObject, resolve });
+        return await new Promise((resolve, reject) => {
+            this.queue.push({ tool, argumentsObject, resolve, reject });
             this.pump();
         });
     }
@@ -53,7 +55,11 @@ export class McpBroker {
         try {
             result = await this.callMcp(call.tool, call.argumentsObject);
         }
-        catch {
+        catch (error) {
+            if (this.options.transportErrors === "throw") {
+                call.reject(error);
+                return;
+            }
             result = { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
         }
         call.resolve(result);
@@ -61,7 +67,7 @@ export class McpBroker {
     async callMcp(tool, argumentsObject) {
         const toolArguments = { ...argumentsObject };
         if (typeof toolArguments.reason !== "string" || toolArguments.reason.trim() === "") {
-            toolArguments.reason = DEFAULT_REASON;
+            toolArguments.reason = this.options.defaultReason ?? DEFAULT_REASON;
         }
         const requestId = this.nextRequestId;
         this.nextRequestId += 1;
@@ -87,7 +93,7 @@ export class McpBroker {
             signal: AbortSignal.timeout(this.options.timeoutMs ?? TOOL_CALL_TIMEOUT_MS),
         });
         if (response.status === 401) {
-            return { ok: false, error: { message: SIGN_IN_AGAIN_MESSAGE } };
+            return { ok: false, error: { message: this.options.signInAgainMessage ?? SIGN_IN_AGAIN_MESSAGE } };
         }
         if (!response.ok) {
             return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
@@ -142,8 +148,15 @@ function toolRefusalMessage(resultRecord) {
     }
     return GENERIC_TOOL_TROUBLE;
 }
+// The server's own error text is hostile input on every path that shows it
+// (a terminal for `query`, a page for `dev`): strip control and bidi bytes
+// and cap the length in one place, so no caller has to remember to.
 function capMessage(message) {
-    return message.length > MAX_ERROR_MESSAGE_CHARS
-        ? `${message.slice(0, MAX_ERROR_MESSAGE_CHARS)}…`
-        : message;
+    const clean = sanitizeForTerminal(message);
+    // Text that was nothing but invisible code points sanitizes to nothing;
+    // a blank error helps nobody.
+    if (clean.trim() === "") {
+        return GENERIC_TOOL_TROUBLE;
+    }
+    return clean.length > MAX_ERROR_MESSAGE_CHARS ? `${capForTerminal(clean, MAX_ERROR_MESSAGE_CHARS)}…` : clean;
 }

package/dist/help.js

@@ -5,6 +5,9 @@
 // the long setup help, and the distinct short/long setup variants). The root
 // help grew past the Rust CLI when login/logout landed; its fixture pins the
 // current text.
+import { DEV_IDLE_MINUTES } from "./dev/dev-commands.js";
+import { APP_TOOL_ALLOWLIST } from "./dev/tool-allowlist.js";
+import { wrapNames } from "./terminal-text.js";
 export const ROOT_HELP = `Usage: npx driggsby@latest <COMMAND>
 
 Commands:
@@ -16,6 +19,7 @@ Commands:
   deploy    Deploy the app in this directory to Driggsby.
   rollback  Switch which deployed version of your app is live.
   versions  List your deployed app's versions.
+  query     Run one Driggsby data tool and print its result as JSON.
 
 Options:
   -h, --help     Print help
@@ -30,6 +34,7 @@ Examples:
   npx driggsby@latest init money-dash
   npx driggsby@latest dev
   npx driggsby@latest deploy
+  npx driggsby@latest query get_overview
 `;
 export const INIT_HELP = `Create a new Driggsby app in a new folder.
 
@@ -80,22 +85,27 @@ files reload the page on save.
 
 While dev runs, the preview serves your financial data to this machine —
 other websites can't reach it, but anything running locally can, so stop
-it when you're done.
+it when you're done: press Ctrl+C, or from any terminal run
+npx driggsby@latest dev --stop. It also stops on its own after
+${String(DEV_IDLE_MINUTES)} minutes with no page open.
 
 Sign in first with npx driggsby@latest login.
 
-Usage: npx driggsby@latest dev
+Usage: npx driggsby@latest dev [--stop]
 
 Options:
+      --stop  Stop the driggsby dev running on this machine.
   -h, --help  Print help
 `;
 export const DEPLOY_HELP = `Deploy the app in this directory to Driggsby.
 
 This reads driggsby.json next to your app files, uploads only what changed,
-and makes the new version live at your app's driggsby.dev address. The
-first deploy creates the app: Driggsby assigns its address (your name plus
-a unique ending) and saves it back into driggsby.json. With --preview, the
-version is uploaded and kept ready without changing what's live.
+and makes the new version live. It prints the app's page in Driggsby, where
+it runs with your data, then the app's own driggsby.dev address, which
+shows no Driggsby data when opened directly. The first deploy creates the
+app: Driggsby assigns its address (your name plus a unique ending) and
+saves it back into driggsby.json. With --preview, the version is uploaded
+and kept ready without changing what's live.
 
 Sign in first with npx driggsby@latest login.
 
@@ -128,6 +138,36 @@ Usage: npx driggsby@latest versions
 Options:
   -h, --help  Print help
 `;
+// The tool list is the allowlist itself, so the help can never name a tool
+// a Driggsby app cannot watch.
+const QUERY_TOOL_LINES = wrapNames([...APP_TOOL_ALLOWLIST], "          ");
+export const QUERY_HELP = `Run one Driggsby data tool and print its result as JSON.
+
+The output is exactly what driggsby.watch hands an app's callback for the
+same tool and params, so you can read a result's shape before writing any
+render code. Only the read-only tools an app can watch are accepted. The
+JSON goes to stdout and nothing else does; messages go to stderr.
+
+Sign in first with npx driggsby@latest login.
+
+Usage: npx driggsby@latest query <TOOL> [--sql <SQL>] [--params <JSON>]
+
+Arguments:
+  <TOOL>  One of:
+${QUERY_TOOL_LINES}
+
+Options:
+      --sql <SQL>      The SQL for query_cash_sql or query_investment_sql.
+                       Overrides a sql key given in --params.
+      --params <JSON>  Other params as a JSON object, for example
+                       '{"history_type":"liabilities"}'.
+  -h, --help           Print help
+
+Examples:
+  npx driggsby@latest query get_overview
+  npx driggsby@latest query list_recurring_transactions
+  npx driggsby@latest query query_cash_sql --sql "SELECT 1"
+`;
 export const MCP_HELP = `Set up Driggsby MCP clients.
 
 Usage: npx driggsby@latest mcp <COMMAND>

package/dist/init/templates.js

@@ -21,8 +21,6 @@ export function indexHtml(slug) {
   <main>
     <header>
       <h1>${slug}</h1>
-      <p class="sample-note" id="sample-note" hidden>Sample data — your real
-      accounts appear when this app runs inside Driggsby.</p>
     </header>
     <!-- The bars below are skeleton placeholders. app.js replaces them
          with data on its first render; edit the render functions there,
@@ -112,6 +110,11 @@ export const APP_JS = `// Your app's code. Edit anything — driggsby dev reload
 // Params mirror Driggsby's public MCP tools of the same names, with one
 // simplification: those tools require a "reason" string, but a watch can
 // leave it out — Driggsby fills one in naming the dashboard.
+//
+// To see a tool's exact result shape before writing render code, run it
+// once from the terminal — the JSON it prints is what the callback gets:
+//
+//   npx driggsby@latest query <tool>
 
 // ---------------------------------------------------------------------------
 // Sample data. Every name and number here is invented. It paints only
@@ -232,25 +235,18 @@ function renderAccounts(result) {
 // Live data. window.driggsby exists when the Driggsby SDK loaded — inside
 // Driggsby, or under driggsby dev. Whether anything embeds this page is
 // knowable synchronously: opened directly in a tab, no host will ever
-// answer, so the sample data replaces the skeleton right away and the note
-// explaining it is revealed (it ships hidden in the HTML, so an embedded
-// page never shows it, not even for the moment before this script runs).
-// Embedded, sample numbers never paint at all — the shipped skeleton holds
-// the layout until the first real results replace it and fade in.
+// answer, so the sample data replaces the skeleton right away, and the SDK
+// shows its own notice explaining that the page runs with real data only
+// inside Driggsby. Embedded, sample numbers never paint at all — the
+// shipped skeleton holds the layout until the first real results replace
+// it and fade in.
 // ---------------------------------------------------------------------------
 
 const standalone = window.parent === window;
-const note = document.getElementById("sample-note");
 
 if (standalone) {
-  // The note and the sample values paint together (this whole branch is
-  // one synchronous task). The reveal is kept first so an edit that ever
-  // makes rendering async can't paint values before their label.
-  if (note) note.hidden = false;
   renderOverview(SAMPLE_OVERVIEW);
   renderAccounts(SAMPLE_ACCOUNTS);
-} else if (note) {
-  note.remove();
 }
 
 if (window.driggsby) {
@@ -267,8 +263,6 @@ export const STYLES_CSS = `:root {
   --text: #1f2430;
   --text-muted: #6d7280;
   --hairline: #e6e8ec;
-  --note-background: #fdf6e3;
-  --note-text: #7a5b1e;
 }
 
 * {
@@ -302,21 +296,6 @@ h2 {
   font-weight: 600;
 }
 
-.sample-note {
-  display: inline-block;
-  margin: 12px 0 0;
-  padding: 4px 10px;
-  border-radius: 6px;
-  background: var(--note-background);
-  color: var(--note-text);
-  font-size: 13px;
-}
-
-/* The display rule above would defeat the hidden attribute without this. */
-.sample-note[hidden] {
-  display: none;
-}
-
 /* The skeleton ships in the HTML so the first paint is the final layout as
    muted bars; the first render replaces it and fades in (see app.js). The
    bar margins make each skeleton block exactly the height of the text it