driggsby 0.2.4 → 0.3.1

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

@@ -23,33 +23,40 @@ export function hostPageHtml(slug, appOrigin, background) {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${slug} — driggsby dev</title>
   <style>
+    /* The strip above the frame is the console's title row, in its own
+       measured values: 46px tall on the black ground, 14px ink, a 14%
+       white hairline under it. */
     * { box-sizing: border-box; }
+    html { color-scheme: dark; }
     body {
       margin: 0;
       display: flex;
       flex-direction: column;
       height: 100vh;
-      background: #ffffff;
-      color: #1f2430;
-      font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+      background: #000000;
+      color: #fafafa;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
       font-size: 14px;
+      line-height: 21px;
+      -webkit-font-smoothing: antialiased;
     }
     header {
       display: flex;
-      align-items: baseline;
+      align-items: center;
       justify-content: space-between;
-      padding: 10px 16px;
-      border-bottom: 1px solid #e6e8ec;
+      height: 46px;
+      padding: 0 16px;
+      border-bottom: 1px solid rgba(255, 255, 255, 0.14);
     }
-    header .slug { font-weight: 600; }
-    header .mode { color: #6d7280; font-size: 13px; }
+    header .slug { font-weight: 500; }
+    header .mode { color: #a1a1a1; font-size: 13px; }
     iframe {
       flex: 1;
       width: 100%;
       border: none;
       /* The app's declared background from driggsby.json, painted while
          the app loads — the same surface the production host shows. */
-      background: ${background ?? "#ffffff"};
+      background: ${background ?? "#000000"};
     }
   </style>
 </head>

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/init-command.js

@@ -9,7 +9,8 @@ import { join } from "node:path";
 import { slugProblem } from "@driggsby/deploy";
 import { CliError } from "../cli-error.js";
 import { quotedForTerminal, wrapProse } from "../terminal-text.js";
-import { APP_JS, STYLES_CSS, driggsbyJsonText, indexHtml } from "./templates.js";
+import { STYLES_CSS } from "./template-styles.js";
+import { APP_JS, driggsbyJsonText, indexHtml } from "./templates.js";
 // Argv and prompt answers echo back inside quotes with this cap; a slug can
 // never be longer than 63 characters, so the cap only trims hostile input.
 const MAX_SLUG_ECHO_CHARS = 80;