driggsby 0.2.4 → 0.3.1

package/README.md

@@ -60,7 +60,8 @@ This runs the app locally, embedded exactly the way Driggsby embeds it
 after a deploy, and reloads the page when you save a file. 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.
+done: press Ctrl+C, or from any terminal run `npx driggsby@latest dev --stop`.
+It also stops on its own after 30 minutes with no page open.
 
 ## Deploying an app
 
@@ -75,6 +76,9 @@ The first deploy creates the app: Driggsby assigns its address — the name
 you picked plus a unique ending, like
 `your-app-name-x7k2qf.driggsby.dev` — and saves the assigned name back
 into `driggsby.json`, so any readable name works and names never collide.
+`deploy` prints the Driggsby page for the app first; that is where it runs
+with your data. The `driggsby.dev` address is the app on its own, which
+shows no Driggsby data when opened directly.
 If the project lives in git, commit the updated `driggsby.json` — it is the
 only record of your app's address, and a fresh checkout without it would
 create a second app.
@@ -82,7 +86,10 @@ Every deploy after that uploads only the files that changed. Deploy with
 `--preview` to upload a version without
 changing what visitors see, `npx driggsby@latest versions` to list every
 kept version, and `npx driggsby@latest rollback` to switch which one is
-live — switching re-uploads nothing.
+live — switching re-uploads nothing. `npx driggsby@latest query <tool>`
+runs one read-only data tool and prints its result as JSON, the same
+shape a `driggsby.watch` callback receives, so you can see the data
+before writing any render code.
 
 The CLI is pure TypeScript and installs from the npm registry alone — no
 binary downloads, no install scripts — and runs on macOS, Linux, and Windows

package/dist/args-deploy.js

@@ -1,7 +1,7 @@
 // Argv parsing for the deploy command family: deploy, rollback, versions.
 // Same behavior contract as the rest of the tree — help on -h/--help, usage
 // errors exit 2, echoed argv is sanitized — without chasing clap byte quirks.
-import { unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
+import { helpCommand, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
 import { CliError } from "./cli-error.js";
 import { DEPLOY_HELP, ROLLBACK_HELP, VERSIONS_HELP } from "./help.js";
 import { sanitizeForTerminal } from "./terminal-text.js";
@@ -73,9 +73,6 @@ export function parseVersions(argv) {
     }
     return { kind: "versions" };
 }
-function helpCommand(text) {
-    return { kind: "print-help", text, stream: "stdout", exitCode: 0 };
-}
 // Version numbers are the small positive integers shown by `versions` (v1,
 // v2, ...). Anything else is a usage mistake, reported like other bad argv —
 // including a digit string too large for an exact integer, which would

package/dist/args-dev.js

@@ -0,0 +1,27 @@
+// Argv parsing for `driggsby dev [--stop]`. Same contract as the rest of the
+// tree: help on -h/--help, usage errors exit 2, echoed argv is sanitized.
+import { helpCommand, unexpectedArgument, unexpectedFlagValue } from "./args-shared.js";
+import { DEV_HELP } from "./help.js";
+export const DEV_USAGE = "Usage: npx driggsby@latest dev [--stop]";
+export function parseDev(argv) {
+    let stop = false;
+    let optionsEnded = false;
+    for (const token of argv) {
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return helpCommand(DEV_HELP);
+        }
+        if (!optionsEnded && token === "--stop") {
+            stop = true;
+            continue;
+        }
+        if (!optionsEnded && token.startsWith("--stop=")) {
+            throw unexpectedFlagValue("--stop", token.slice("--stop=".length), DEV_USAGE);
+        }
+        throw unexpectedArgument(token, DEV_USAGE);
+    }
+    return { kind: "dev", stop };
+}

package/dist/args-init.js

@@ -1,7 +1,7 @@
 // Argv parsing for driggsby init: one optional positional (the app's name),
 // help, and the shared usage-error shape — usage errors exit 2, echoed argv
 // is sanitized by the shared builders.
-import { unexpectedArgument } from "./args-shared.js";
+import { helpCommand, unexpectedArgument } from "./args-shared.js";
 import { INIT_HELP } from "./help.js";
 const INIT_USAGE = "Usage: npx driggsby@latest init [NAME]";
 export function parseInit(argv) {
@@ -13,7 +13,7 @@ export function parseInit(argv) {
             continue;
         }
         if (!optionsEnded && (token === "-h" || token === "--help")) {
-            return { kind: "print-help", text: INIT_HELP, stream: "stdout", exitCode: 0 };
+            return helpCommand(INIT_HELP);
         }
         // Any other flag-looking token is a mistake, not a name; after "--"
         // everything is positional and slug validation refuses bad names.

package/dist/args-query.js

@@ -0,0 +1,120 @@
+// Argv parsing for `driggsby query <TOOL> [--sql <SQL>] [--params <JSON>]`.
+// Same behavior contract as the rest of the tree: help on -h/--help, usage
+// errors exit 2, echoed argv is sanitized. The tool is checked against the
+// allowlist here so a typo is a usage error naming the twelve, not a
+// server round trip.
+import { helpCommand, unexpectedArgument } from "./args-shared.js";
+import { didYouMean } from "./clap-suggestions.js";
+import { CliError } from "./cli-error.js";
+import { APP_TOOL_ALLOWLIST } from "./dev/tool-allowlist.js";
+import { QUERY_HELP } from "./help.js";
+import { quotedForTerminal, wrapNames } from "./terminal-text.js";
+// The two tools that take SQL: --sql applies only to these, and a retry
+// line names --sql only for them.
+export const SQL_TOOLS = new Set(["query_cash_sql", "query_investment_sql"]);
+const QUERY_USAGE = "Usage: npx driggsby@latest query <TOOL> [--sql <SQL>] [--params <JSON>]";
+export function parseQuery(argv) {
+    let tool = null;
+    let sql = null;
+    let params = null;
+    let optionsEnded = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return helpCommand(QUERY_HELP);
+        }
+        if (!optionsEnded && token === "--sql") {
+            sql = requireFlagValue(argv, index, "--sql");
+            index += 1;
+            continue;
+        }
+        if (!optionsEnded && token.startsWith("--sql=")) {
+            sql = token.slice("--sql=".length);
+            if (sql.trim() === "") {
+                throw missingFlagValue("--sql");
+            }
+            continue;
+        }
+        if (!optionsEnded && token === "--params") {
+            params = parseParams(requireFlagValue(argv, index, "--params", { allowBlank: true }));
+            index += 1;
+            continue;
+        }
+        if (!optionsEnded && token.startsWith("--params=")) {
+            params = parseParams(token.slice("--params=".length));
+            continue;
+        }
+        if (tool === null && (optionsEnded || !token.startsWith("-"))) {
+            tool = token;
+            continue;
+        }
+        throw unexpectedArgument(token, QUERY_USAGE);
+    }
+    if (tool === null) {
+        throw missingTool();
+    }
+    if (!APP_TOOL_ALLOWLIST.has(tool)) {
+        throw unknownTool(tool);
+    }
+    if (sql !== null && !SQL_TOOLS.has(tool)) {
+        throw sqlForNonSqlTool(tool);
+    }
+    const merged = { ...(params ?? {}) };
+    if (sql !== null) {
+        merged.sql = sql;
+    }
+    return { kind: "query", tool, params: merged };
+}
+// A following flag is never a value: `--sql --params '{}'` is a missing SQL,
+// not SQL that reads "--params" (SQL that must start with "-" can use the
+// --sql= spelling).
+function requireFlagValue(argv, index, flag, options = {}) {
+    const value = argv[index + 1];
+    const looksLikeFlag = value !== undefined && value.length > 1 && value.startsWith("-");
+    const blank = value === undefined || looksLikeFlag || (value.trim() === "" && options.allowBlank !== true);
+    if (blank) {
+        throw missingFlagValue(flag);
+    }
+    return value;
+}
+function missingFlagValue(flag) {
+    return new CliError(`error: a value is required for '${flag}' but none was supplied\n\n${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
+}
+// --params is the tool's params object, verbatim; anything that is not a
+// JSON object (an array, a string, unparseable text) is a usage mistake.
+function parseParams(rawValue) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawValue);
+    }
+    catch {
+        throw invalidParams();
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw invalidParams();
+    }
+    return parsed;
+}
+function invalidParams() {
+    return new CliError(`error: invalid value for '--params':\n'--params' must be a JSON object, like '{"history_type":"liabilities"}'\n\n` +
+        `${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
+}
+function missingTool() {
+    return new CliError(`error: the following required arguments were not provided:\n  <TOOL>\n\n${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
+}
+function unknownTool(tool) {
+    const similar = didYouMean(tool, [...APP_TOOL_ALLOWLIST]);
+    const tip = similar === undefined ? "" : `  tip: a similar tool exists: '${similar}'\n\n`;
+    return new CliError(`error: ${quotedForTerminal(tool, 60)} isn't a tool a Driggsby app can call.\n` +
+        `Apps can watch these read-only tools:\n` +
+        `${wrapNames([...APP_TOOL_ALLOWLIST], "  ")}\n\n${tip}${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
+}
+function sqlForNonSqlTool(tool) {
+    return new CliError(`error: '--sql' only applies to query_cash_sql or query_investment_sql;\n` +
+        `'${tool}' takes no SQL.\n\n` +
+        `${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
+}

package/dist/args-shared.js

@@ -5,6 +5,9 @@
 import { CliError } from "./cli-error.js";
 import {} from "./mcp-setup/known-client.js";
 import { sanitizeForTerminal } from "./terminal-text.js";
+export function helpCommand(text) {
+    return { kind: "print-help", text, stream: "stdout", exitCode: 0 };
+}
 // "--print=true" / "--help=x" / "--version=x": these flags take no value.
 export function unexpectedFlagValue(flag, rawValue, usage) {
     const value = sanitizeForTerminal(rawValue);

package/dist/args.js

@@ -6,12 +6,14 @@
 // (login, logout) keep the same behavior and exit codes without chasing
 // clap's byte-level quirks.
 import { parseDeploy, parseRollback, parseVersions } from "./args-deploy.js";
+import { parseDev } from "./args-dev.js";
 import { parseInit } from "./args-init.js";
 import { parseMcpSetup } from "./args-mcp-setup.js";
+import { parseQuery } from "./args-query.js";
 import { removeDashesTip, similarArgumentTip, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
 import { didYouMean } from "./clap-suggestions.js";
 import { CliError } from "./cli-error.js";
-import { DEV_HELP, LOGIN_HELP, LOGOUT_HELP, MCP_HELP, ROOT_HELP } from "./help.js";
+import { LOGIN_HELP, LOGOUT_HELP, MCP_HELP, ROOT_HELP } from "./help.js";
 import { sanitizeForTerminal } from "./terminal-text.js";
 export {} from "./args-shared.js";
 const ROOT_USAGE = "Usage: npx driggsby@latest <COMMAND>";
@@ -19,17 +21,18 @@ const MCP_USAGE = "Usage: npx driggsby@latest mcp <COMMAND>";
 const ROOT_LEVEL = {
     helpText: ROOT_HELP,
     usage: ROOT_USAGE,
-    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions"],
+    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "query"],
     longFlags: ["help", "version"],
     subcommandFlags: [
         { name: "mcp", longFlags: ["help"] },
         { name: "login", longFlags: ["help"] },
         { name: "logout", longFlags: ["help"] },
         { name: "init", longFlags: ["help"] },
-        { name: "dev", longFlags: ["help"] },
+        { name: "dev", longFlags: ["stop", "help"] },
         { name: "deploy", longFlags: ["preview", "help"] },
         { name: "rollback", longFlags: ["to", "help"] },
         { name: "versions", longFlags: ["help"] },
+        { name: "query", longFlags: ["sql", "params", "help"] },
     ],
     usagePrefix: "npx driggsby@latest",
     hasVersion: true,
@@ -88,13 +91,15 @@ function dispatchSubcommand(name, rest) {
         case "init":
             return parseInit(rest);
         case "dev":
-            return parseBareCommand({ kind: "dev" }, DEV_HELP, "Usage: npx driggsby@latest dev", rest);
+            return parseDev(rest);
         case "deploy":
             return parseDeploy(rest);
         case "rollback":
             return parseRollback(rest);
         case "versions":
             return parseVersions(rest);
+        case "query":
+            return parseQuery(rest);
         case "setup":
             return parseMcpSetup(rest);
         default:

package/dist/credentials/file-store.js

@@ -2,12 +2,13 @@
 // atomically with owner-only permissions. This is the only backend on
 // Windows (no readable credential CLI exists there; the profile directory's
 // default user-only ACL is the boundary) and the fallback everywhere else.
-import { randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { readdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
+import { driggsbyDirectory, writeOwnerOnlyFile } from "../owner-only-file.js";
 import {} from "./clear-outcome.js";
+const CREDENTIALS_FILE_NAME = "credentials.json";
 export function credentialsFilePath(homeDirectory) {
-    return join(homeDirectory, ".driggsby", "credentials.json");
+    return join(driggsbyDirectory(homeDirectory), CREDENTIALS_FILE_NAME);
 }
 export async function readFileToken(homeDirectory) {
     let raw;
@@ -30,21 +31,7 @@ export async function readFileToken(homeDirectory) {
     }
 }
 export async function writeFileToken(homeDirectory, token) {
-    const directory = join(homeDirectory, ".driggsby");
-    // mode applies only when the directory is created; an existing ~/.driggsby
-    // keeps whatever permissions the user already gave it.
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    const finalPath = credentialsFilePath(homeDirectory);
-    const temporaryPath = join(directory, `credentials.json.${randomUUID()}.tmp`);
-    const body = `${JSON.stringify({ app_token: token }, null, 2)}\n`;
-    try {
-        await writeFile(temporaryPath, body, { mode: 0o600 });
-        await rename(temporaryPath, finalPath);
-    }
-    catch (error) {
-        await rm(temporaryPath, { force: true });
-        throw error;
-    }
+    await writeOwnerOnlyFile(homeDirectory, CREDENTIALS_FILE_NAME, `${JSON.stringify({ app_token: token }, null, 2)}\n`);
 }
 export async function clearFileToken(homeDirectory) {
     let outcome;
@@ -59,10 +46,10 @@ export async function clearFileToken(homeDirectory) {
     // readable token in a `credentials.json.<uuid>.tmp` file; removal must not
     // leave one behind while reporting the token gone.
     try {
-        for (const entry of await readdir(join(homeDirectory, ".driggsby"))) {
+        for (const entry of await readdir(driggsbyDirectory(homeDirectory))) {
             if (entry.startsWith("credentials.json.") && entry.endsWith(".tmp")) {
                 try {
-                    await rm(join(homeDirectory, ".driggsby", entry), { force: true });
+                    await rm(join(driggsbyDirectory(homeDirectory), entry), { force: true });
                 }
                 catch {
                     outcome = "failed";

package/dist/deploy/api-session.js

@@ -9,6 +9,8 @@ import { CliError } from "../cli-error.js";
 import { readStoredToken, } from "../credentials/store.js";
 import { capForTerminal, wrapProse } from "../terminal-text.js";
 const LOGIN_COMMAND = "npx driggsby@latest login";
+// The one wording for a saved sign-in the server no longer accepts.
+export const SIGN_IN_AGAIN_MESSAGE = "Your sign-in on this machine isn't valid anymore. Sign in again:\n" + `  ${LOGIN_COMMAND}`;
 const MAX_ERROR_DESCRIPTION_CHARS = 300;
 // Server-supplied display strings go through capForTerminal (sanitize plus
 // a hard length bound) with bounds sized to each string's real contract so
@@ -67,8 +69,7 @@ function apiFailure(error, retryCommand) {
         return new CliError(`Driggsby is briefly unavailable just now. Please try again:\n  ${retryCommand}`, 1);
     }
     if (error.status === 401) {
-        return new CliError("Your sign-in on this machine isn't valid anymore. Sign in again:\n" +
-            `  ${LOGIN_COMMAND}`, 1);
+        return new CliError(SIGN_IN_AGAIN_MESSAGE, 1);
     }
     if (error.code === "deploy_scope_required") {
         return new CliError("Your saved sign-in can read your Driggsby data but wasn't approved for\n" +

package/dist/deploy/deploy-command.js

@@ -1,11 +1,11 @@
 // driggsby deploy: read driggsby.json, hash the serve folder, upload what
 // Driggsby doesn't have, and make the new version live (or hold it as a
 // ready-but-not-live version with --preview).
-import { collectDeployFiles, deployProjectFiles, formatBytes, readProjectConfig, } from "@driggsby/deploy";
+import { collectDeployFiles, deployProjectFiles, formatBytes, hasLiveAddress, liveAddresses, liveAddressLines, readProjectConfig, } from "@driggsby/deploy";
 import { apiBaseUrl } from "../api/base-url.js";
 import { defaultCredentialEnvironment, } from "../credentials/store.js";
-import { capForTerminal, quotedForTerminal, wrapProse } from "../terminal-text.js";
-import { deployFailure, MAX_SERVER_TEXT_CHARS, MAX_SERVER_URL_CHARS, requireDeploySession, } from "./api-session.js";
+import { quotedForTerminal, wrapProse } from "../terminal-text.js";
+import { deployFailure, MAX_SERVER_TEXT_CHARS, requireDeploySession, } from "./api-session.js";
 const DEPLOY_RETRY_COMMAND = "npx driggsby@latest deploy";
 function defaultDeployIo() {
     return {
@@ -48,9 +48,12 @@ export async function runDeploy(options, environment = defaultCredentialEnvironm
         const seconds = (io.now() - startedAt) / 1_000;
         io.out(`${changedNote(outcome)}\n`);
         io.out(`${uploadedLine(outcome, seconds)}\n`);
-        io.out(`${resultLine(outcome)}\n`);
-        if (outcome.url !== null) {
-            io.out(`\n  ${capForTerminal(outcome.url, MAX_SERVER_URL_CHARS)}\n`);
+        const addresses = liveAddresses(outcome.url, outcome.consoleUrl, session.baseUrl);
+        io.out(`${resultLine(outcome, addresses)}\n`);
+        // A preview has no address to open: the Driggsby page shows the live
+        // version, which a preview leaves unchanged.
+        if (outcome.live) {
+            io.out(liveAddressLines(addresses));
         }
         if (collected.skippedNodeModules.length > 0) {
             io.out(`\n${wrapProse("Note: node_modules doesn't deploy — Driggsby serves your app as static files, so it isn't needed.")}\n`);
@@ -89,12 +92,12 @@ function uploadedLine(outcome, seconds) {
     }
     return `✓ Uploaded  ${formatBytes(outcome.uploadedBytes)} in ${formatSeconds(seconds)}`;
 }
-function resultLine(outcome) {
+function resultLine(outcome, addresses) {
     if (outcome.live) {
-        // "at:" only when the URL that line promises actually follows.
-        return outcome.url === null
-            ? `✓ Live      v${outcome.versionNumber}`
-            : `✓ Live      v${outcome.versionNumber}, at:`;
+        // "at:" only when an address that line promises actually follows.
+        return hasLiveAddress(addresses)
+            ? `✓ Live      v${outcome.versionNumber}, at:`
+            : `✓ Live      v${outcome.versionNumber}`;
     }
     return `✓ Ready     v${outcome.versionNumber} is uploaded but not live — what visitors see is unchanged`;
 }

package/dist/deploy/rollback-command.js

@@ -2,12 +2,12 @@
 // re-uploads — the switch is a pointer change on Driggsby's side. With --to N
 // it acts directly; without it, it shows the choices and asks (or, when not
 // attached to a person, explains how to re-run with --to).
-import { setLiveVersion, readProjectConfig } from "@driggsby/deploy";
+import { hasLiveAddress, liveAddresses, liveAddressLines, readProjectConfig, setLiveVersion, } from "@driggsby/deploy";
 import { apiBaseUrl } from "../api/base-url.js";
 import { CliError } from "../cli-error.js";
 import { defaultCredentialEnvironment, } from "../credentials/store.js";
-import { capForTerminal, wrapProse } from "../terminal-text.js";
-import { deployFailure, MAX_SERVER_URL_CHARS, requireDeploySession, } from "./api-session.js";
+import { wrapProse } from "../terminal-text.js";
+import { deployFailure, requireDeploySession, } from "./api-session.js";
 import { fetchVersionList, renderVersionRows } from "./versions-command.js";
 const ROLLBACK_RETRY_COMMAND = "npx driggsby@latest rollback";
 function defaultRollbackIo() {
@@ -56,13 +56,11 @@ export async function runRollback(options, environment = defaultCredentialEnviro
         const previousLive = list.liveVersionNumber;
         const result = await setLiveVersion(api, config.slug, target);
         const was = previousLive === null ? "" : ` (was v${previousLive})`;
-        // "at:" only when the URL that line promises actually follows; the URL
-        // is a server-supplied string, sanitized before printing.
-        const atSuffix = result.url === null ? "" : ", at:";
+        // "at:" only when an address that line promises actually follows.
+        const addresses = liveAddresses(result.url, result.consoleUrl, session.baseUrl);
+        const atSuffix = hasLiveAddress(addresses) ? ", at:" : "";
         io.out(`✓ Live      v${result.versionNumber} is what visitors see now${was}${atSuffix}\n`);
-        if (result.url !== null) {
-            io.out(`\n  ${capForTerminal(result.url, MAX_SERVER_URL_CHARS)}\n`);
-        }
+        io.out(liveAddressLines(addresses));
         io.out(`\n${wrapProse(`Nothing re-uploaded — Driggsby already had v${result.versionNumber} in full.`)}\n` +
             "\nNext:\n  See every version with npx driggsby@latest versions\n");
         return 0;

package/dist/dev/dev-command.js

@@ -13,12 +13,16 @@ import { defaultCredentialEnvironment, } from "../credentials/store.js";
 import { requireDeploySession } from "../deploy/api-session.js";
 import { tryOpenUrl } from "../login/open-url.js";
 import { wrapProse } from "../terminal-text.js";
+import { DEV_IDLE_MINUTES, DEV_START_COMMAND, DEV_STOP_COMMAND } from "./dev-commands.js";
 import { startDevServers } from "./dev-servers.js";
+import { readLiveDevState, removeDevState, writeDevState } from "./dev-state.js";
+import { displayFolder } from "./display-folder.js";
 import { McpBroker } from "./mcp-broker.js";
 import { watchDirectory } from "./watcher.js";
 export const DEV_HOST_PORT = 4111;
 export const DEV_APP_PORT = 4112;
-const DEV_RETRY_COMMAND = "npx driggsby@latest dev";
+const DEV_IDLE_TIMEOUT_MS = DEV_IDLE_MINUTES * 60 * 1000;
+const DEV_IDLE_CHECK_MS = 15 * 1000;
 function defaultDevIo() {
     return {
         out: (text) => {
@@ -33,6 +37,13 @@ function defaultDevIo() {
                 process.once("SIGTERM", () => {
                     resolve();
                 });
+                // A closed terminal window: still a clean stop, so the record and
+                // the ports are released like any other exit. (On Windows, a signal
+                // from `dev --stop` ends the process outright instead; `dev --stop`
+                // then removes the record itself once the pid is gone.)
+                process.once("SIGHUP", () => {
+                    resolve();
+                });
             });
         },
     };
@@ -61,25 +72,100 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
         });
     }
     catch (error) {
-        throw devStartFailure(error, baseUrl);
+        throw await devStartFailure(error, baseUrl, environment.homeDirectory);
     }
     const stopWatching = watchDirectory(config.serveDirectory, () => {
         servers.notifyChange();
     });
+    const idleTimeoutMs = options.idleTimeoutMs ?? DEV_IDLE_TIMEOUT_MS;
+    const idle = idleWatch(servers, idleTimeoutMs, options.idleCheckMs ?? DEV_IDLE_CHECK_MS);
     try {
+        // The record is what `dev --stop` finds; a home that can't be written
+        // costs that convenience, not the preview.
+        const recorded = await tryWriteDevState(environment.homeDirectory, projectDirectory, servers);
         const opened = await io.openUrl(servers.hostOrigin);
-        io.out(`✓ Ready     ${config.slug} is running with your live Driggsby data${opened ? ", at:" : ":"}\n\n` +
-            `  ${servers.hostOrigin}\n\n` +
-            `${wrapProse("Edit the app's files and the page reloads on save. Press Ctrl+C to stop.")}\n` +
-            "\nNext:\n  Put it live on driggsby.dev with npx driggsby@latest deploy\n");
-        await io.waitForShutdown();
+        io.out(readyText(config.slug, servers, opened, recorded, idleTimeoutMs));
+        const ending = await Promise.race([io.waitForShutdown().then(() => "shutdown"), idle.expired]);
+        if (ending === "idle") {
+            io.out(`✓ Stopped   No page was open for ${idleWindowWords(idleTimeoutMs)}, so ` +
+                `driggsby dev stopped itself.\n\nStart it again with:\n  ${DEV_START_COMMAND}\n`);
+        }
         return 0;
     }
     finally {
+        idle.cancel();
         stopWatching();
+        // The record goes before the ports are freed, so a dev starting the
+        // instant these close never finds a record this one is about to remove.
+        // (A `dev --stop` waiting on this exit polls the pid for five seconds,
+        // and closing takes well under one.) The record is a convenience: a
+        // failure to remove it must never keep the ports open.
+        try {
+            await removeDevState(environment.homeDirectory, process.pid);
+        }
+        catch {
+            // Left behind; the next read finds a dead pid and removes it.
+        }
         await servers.close();
     }
 }
+async function tryWriteDevState(homeDirectory, folder, servers) {
+    try {
+        await writeDevState(homeDirectory, {
+            pid: process.pid,
+            folder,
+            startedAt: new Date().toISOString(),
+            hostPort: servers.hostPort,
+            appPort: servers.appPort,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readyText(slug, servers, opened, recorded, idleTimeoutMs) {
+    const stopLine = recorded
+        ? `${wrapProse("Edit the app's files and the page reloads on save. Press Ctrl+C to stop, or from any terminal:")}\n  ${DEV_STOP_COMMAND}\n`
+        : `${wrapProse("Edit the app's files and the page reloads on save. Press Ctrl+C to stop.")}\n`;
+    return (`✓ Ready     ${slug} is running with your live Driggsby data${opened ? ", at:" : ":"}\n\n` +
+        `  ${servers.hostOrigin}\n\n` +
+        `${wrapProse(`That page embeds the app from ${servers.appOrigin}. Opened on its own, the app gets no Driggsby data, so use the address above.`)}\n\n` +
+        `${stopLine}\n` +
+        `${wrapProse(`It stops on its own after ${idleWindowWords(idleTimeoutMs)} with no page open.`)}\n` +
+        "\nNext:\n  Put it live on driggsby.dev with npx driggsby@latest deploy\n");
+}
+export function idleWindowWords(timeoutMs) {
+    const minutes = Math.round(timeoutMs / 60_000);
+    if (minutes < 1) {
+        return "a moment";
+    }
+    return minutes === 1 ? "1 minute" : `${String(minutes)} minutes`;
+}
+function idleWatch(servers, timeoutMs, checkMs) {
+    let resolveExpired = () => undefined;
+    const expired = new Promise((resolve) => {
+        resolveExpired = resolve;
+    });
+    let idleSince = Date.now();
+    const timer = setInterval(() => {
+        if (servers.clientCount() > 0) {
+            idleSince = Date.now();
+            return;
+        }
+        if (Date.now() - idleSince >= timeoutMs) {
+            resolveExpired("idle");
+        }
+    }, checkMs);
+    // A pending check must never hold the process open once the run ends.
+    timer.unref();
+    return {
+        expired,
+        cancel: () => {
+            clearInterval(timer);
+        },
+    };
+}
 // The Driggsby SDK bundle ships inside @driggsby/sdk; dev serves it on the
 // app origin at the same path production serves it, so the scaffold's
 // script tag works identically in both places.
@@ -88,20 +174,26 @@ async function loadSdkBundle() {
     const bundlePath = require.resolve("@driggsby/sdk/driggsby-sdk.js");
     return await readFile(bundlePath, "utf8");
 }
-function devStartFailure(error, baseUrl) {
+async function devStartFailure(error, baseUrl, homeDirectory) {
     if (error instanceof CliError) {
         return error;
     }
     if (error.code === "EADDRINUSE") {
-        return new CliError(`${wrapProse(`Ports ${String(DEV_HOST_PORT)} and ${String(DEV_APP_PORT)} are how driggsby dev serves the preview, and something on this machine is already using one of them. Stop that program (often another driggsby dev) and try again:`)}\n` +
-            `  ${DEV_RETRY_COMMAND}`, 1);
+        const running = await readLiveDevState(homeDirectory);
+        if (running !== null) {
+            return new CliError(`driggsby dev is already running for the app in:\n  ${displayFolder(running.folder)}\n\n` +
+                `Only one can run at a time. Stop it first:\n  ${DEV_STOP_COMMAND}\n\n` +
+                `Then try again here:\n  ${DEV_START_COMMAND}`, 1);
+        }
+        return new CliError(`${wrapProse(`Ports ${String(DEV_HOST_PORT)} and ${String(DEV_APP_PORT)} are how driggsby dev serves the preview, and something on this machine is already using one of them. Stop that program and try again:`)}\n` +
+            `  ${DEV_START_COMMAND}`, 1);
     }
     const blocked = blockedNetworkError(error, {
         host: apiHost(baseUrl),
-        retryCommand: DEV_RETRY_COMMAND,
+        retryCommand: DEV_START_COMMAND,
     });
     if (blocked !== null) {
         return blocked;
     }
-    return new CliError(`We weren't able to start the preview just now. Please try again:\n  ${DEV_RETRY_COMMAND}`, 1);
+    return new CliError(`We weren't able to start the preview just now. Please try again:\n  ${DEV_START_COMMAND}`, 1);
 }

package/dist/dev/dev-commands.js

@@ -0,0 +1,10 @@
+// The commands `driggsby dev` names in its own output and help, and the
+// idle window it enforces, in one place so no two surfaces can disagree.
+export const DEV_START_COMMAND = "npx driggsby@latest dev";
+export const DEV_STOP_COMMAND = "npx driggsby@latest dev --stop";
+// A preview nobody has open for this long stops itself, so a dev started in
+// the background (often by an agent) does not keep serving live financial
+// data on this machine indefinitely.
+// Spelled out as prose in README.md and packages/driggsby/README.md too;
+// change those with this.
+export const DEV_IDLE_MINUTES = 30;

package/dist/dev/dev-servers.js

@@ -5,6 +5,7 @@
 // only. The app token never appears here — the broker callback holds it in
 // the CLI process.
 import { createServer } from "node:http";
+import { DEV_IDENTITY_PATH } from "./dev-state.js";
 import { hostPageHtml, HOST_PAGE_JS } from "./host-page.js";
 import { serveStaticFile } from "./static-files.js";
 import { APP_TOOL_ALLOWLIST } from "./tool-allowlist.js";
@@ -55,6 +56,7 @@ export async function startDevServers(options) {
                 client.write("event: change\ndata: files-changed\n\n");
             }
         },
+        clientCount: () => sseClients.size,
         close: async () => {
             for (const client of sseClients) {
                 client.end();
@@ -116,6 +118,12 @@ async function handleHostRequest(options, hostPort, appOrigin, sseClients, reque
         return;
     }
     const path = requestPath(request);
+    if (request.method === "GET" && path === DEV_IDENTITY_PATH) {
+        // Lets `dev --stop` (and a colliding `dev`) confirm that the process in
+        // ~/.driggsby/dev.json is the one actually serving this port.
+        sendJson(response, 200, { pid: process.pid });
+        return;
+    }
     if (request.method === "GET" && path === "/") {
         sendHostPage(response, hostPageHtml(options.slug, appOrigin, options.background), appOrigin);
         return;