driggsby 0.4.1 → 0.5.1

package/README.md

@@ -60,8 +60,9 @@ 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: 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.
+done: press Ctrl+C, or run `npx driggsby@latest dev --stop` in the app's
+folder. It also stops on its own after 30 minutes with no page open.
+Previews for several apps can run at once; each prints its own addresses.
 
 ## Deploying an app
 

package/dist/dev/dev-command.js

@@ -15,12 +15,15 @@ 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 { pruneDevStatesForPorts, readDevStates, removeDevState, writeDevState } from "./dev-state.js";
 import { McpBroker } from "./mcp-broker.js";
 import { watchDirectory } from "./watcher.js";
 export const DEV_HOST_PORT = 4111;
 export const DEV_APP_PORT = 4112;
+// Previews for other folders can already hold the default pair (a person
+// often runs several agents at once), so dev moves up two ports at a time,
+// 4111/4112, then 4113/4114, and so on, through this many pairs.
+export const DEV_PORT_PAIRS = 10;
 const DEV_IDLE_TIMEOUT_MS = DEV_IDLE_MINUTES * 60 * 1000;
 const DEV_IDLE_CHECK_MS = 15 * 1000;
 function defaultDevIo() {
@@ -57,22 +60,36 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
             "  npx driggsby@latest deploy", 1);
     }
     const session = await requireDeploySession(environment);
+    await refuseSecondPreview(environment.homeDirectory, projectDirectory);
     const sdkBundle = await loadSdkBundle();
     const broker = new McpBroker({ baseUrl: session.baseUrl, token: session.token });
-    let servers;
-    try {
-        servers = await startDevServers({
-            slug: config.slug,
-            background: config.background,
-            serveDirectory: config.serveDirectory,
-            sdkBundle,
-            runToolCall: (tool, argumentsObject) => broker.runToolCall(tool, argumentsObject),
-            hostPort: options.hostPort ?? DEV_HOST_PORT,
-            appPort: options.appPort ?? DEV_APP_PORT,
-        });
-    }
-    catch (error) {
-        throw await devStartFailure(error, baseUrl, environment.homeDirectory);
+    const hostPort = options.hostPort ?? DEV_HOST_PORT;
+    const appPort = options.appPort ?? DEV_APP_PORT;
+    const pairs = options.portPairs ?? DEV_PORT_PAIRS;
+    // Ephemeral ports (0, in tests) are never in use, so they never move.
+    const fixedPorts = hostPort !== 0 && appPort !== 0;
+    let servers = null;
+    for (let pair = 0; servers === null; pair += 1) {
+        try {
+            servers = await startDevServers({
+                slug: config.slug,
+                background: config.background,
+                serveDirectory: config.serveDirectory,
+                sdkBundle,
+                runToolCall: (tool, argumentsObject) => broker.runToolCall(tool, argumentsObject),
+                hostPort: shiftedPort(hostPort, pair),
+                appPort: shiftedPort(appPort, pair),
+            });
+        }
+        catch (error) {
+            // A pair already in use (another folder's preview, most often) moves
+            // the run to the next pair; startDevServers has released the port it
+            // did bind.
+            if (portUnavailable(error) && pair + 1 < pairs && fixedPorts) {
+                continue;
+            }
+            throw devStartFailure(error, baseUrl, { hostPort, appPort, pairs });
+        }
     }
     const stopWatching = watchDirectory(config.serveDirectory, () => {
         servers.notifyChange();
@@ -111,6 +128,8 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
 }
 async function tryWriteDevState(homeDirectory, folder, servers) {
     try {
+        // Records a dev left behind on these ports can't be live: they're ours now.
+        await pruneDevStatesForPorts(homeDirectory, process.pid, servers.hostPort, servers.appPort);
         await writeDevState(homeDirectory, {
             pid: process.pid,
             folder,
@@ -126,7 +145,7 @@ async function tryWriteDevState(homeDirectory, folder, servers) {
 }
 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, or run this in the app's folder:")}\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` +
@@ -174,19 +193,36 @@ async function loadSdkBundle() {
     const bundlePath = require.resolve("@driggsby/sdk/driggsby-sdk.js");
     return await readFile(bundlePath, "utf8");
 }
-async function devStartFailure(error, baseUrl, homeDirectory) {
+function shiftedPort(port, pair) {
+    return port === 0 ? 0 : port + pair * 2;
+}
+// In use, or reserved (Windows can exclude port ranges for Hyper-V and
+// WinNAT, which reads as access denied).
+function portUnavailable(error) {
+    const code = error?.code;
+    return code === "EADDRINUSE" || code === "EACCES";
+}
+// One preview per folder: a second would only compete with the first for
+// the same files, so dev points at the one already running instead.
+async function refuseSecondPreview(homeDirectory, projectDirectory) {
+    const reads = await readDevStates(homeDirectory, undefined, projectDirectory);
+    const running = reads.find((read) => read.status === "live")?.state;
+    if (running === undefined) {
+        return;
+    }
+    throw new CliError(`driggsby dev is already running for this app, at:\n  http://127.0.0.1:${String(running.hostPort)}\n\n` +
+        `${wrapProse("Open that address, or stop it and start again:")}\n  ${DEV_STOP_COMMAND}\n  ${DEV_START_COMMAND}`, 1);
+}
+function devStartFailure(error, baseUrl, ports) {
     if (error instanceof CliError) {
         return error;
     }
-    if (error.code === "EADDRINUSE") {
-        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);
+    if (portUnavailable(error)) {
+        const first = Math.min(ports.hostPort, ports.appPort);
+        const last = Math.max(shiftedPort(ports.hostPort, ports.pairs - 1), shiftedPort(ports.appPort, ports.pairs - 1));
+        return new CliError(`${wrapProse(`driggsby dev serves previews in pairs of ports from ${String(first)} to ${String(last)}, and none of those pairs is free on this machine. Stop a preview you're done with, in its app's folder:`)}\n` +
+            `  ${DEV_STOP_COMMAND}\n\n` +
+            `Then try again here:\n  ${DEV_START_COMMAND}`, 1);
     }
     const blocked = blockedNetworkError(error, {
         host: apiHost(baseUrl),

package/dist/dev/dev-servers.js

@@ -119,8 +119,8 @@ async function handleHostRequest(options, hostPort, appOrigin, sseClients, reque
     }
     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.
+        // Lets `dev --stop` (and `dev`) confirm that a record in ~/.driggsby
+        // names the process actually serving this port.
         sendJson(response, 200, { pid: process.pid });
         return;
     }

package/dist/dev/dev-state.js

@@ -1,14 +1,19 @@
-// 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";
+// The records of the `driggsby dev` previews running on this machine, one
+// per run: ~/.driggsby/dev-<pid>.json, written after both ports bind and
+// removed when the run ends. `dev --stop` reads them to find the process
+// for a folder, and `dev` reads them to say where a folder's preview is
+// already running. A file whose pid is no longer alive (the machine
+// rebooted, the process was killed hard) is stale and treated as absent.
+// Earlier versions kept one machine-wide record in ~/.driggsby/dev.json;
+// it is still read, so a preview started by one of them can be stopped.
+// They hold no credentials.
+import { constants } from "node:fs";
+import { open, readdir, rm } from "node:fs/promises";
 import { Agent, request as httpRequest } from "node:http";
-import { join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { driggsbyDirectory, writeOwnerOnlyFile } from "../owner-only-file.js";
-const STATE_FILE_NAME = "dev.json";
+const STATE_FILE_PATTERN = /^dev-([1-9]\d{0,9})\.json$/;
+const LEGACY_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";
@@ -27,36 +32,109 @@ const STATE_MAX_BYTES = 4_096;
 // 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 function devStatePath(homeDirectory, pid) {
+    return join(driggsbyDirectory(homeDirectory), stateFileName(pid));
+}
+function stateFileName(pid) {
+    return `dev-${String(pid)}.json`;
 }
 export async function writeDevState(homeDirectory, state) {
-    await writeOwnerOnlyFile(homeDirectory, STATE_FILE_NAME, `${JSON.stringify(state, null, 2)}\n`);
+    await writeOwnerOnlyFile(homeDirectory, stateFileName(state.pid), `${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 };
+// Every record on this machine that may still be a running dev, oldest
+// first; stale and malformed records are removed on the way. With
+// `onlyFolder`, only that folder's records are read and probed.
+export async function readDevStates(homeDirectory, probes = defaultDevProbes(), onlyFolder) {
+    const reads = [];
+    for (const record of await recordFiles(homeDirectory)) {
+        const state = await readDevStateFile(record.path);
+        if (state === null || state === "skip") {
+            continue;
+        }
+        // A record must name the pid its file is named for, so no one run's
+        // file can speak for another's.
+        if (state === "malformed" || (record.pid !== null && state.pid !== record.pid)) {
+            await removeQuietly(record.path);
+            continue;
+        }
+        if (onlyFolder !== undefined && !sameFolder(state.folder, onlyFolder)) {
+            continue;
+        }
+        if (!probes.isAlive(state.pid)) {
+            await removeQuietly(record.path);
+            continue;
+        }
+        const servingPid = await probes.pidServing(state.hostPort);
+        if (servingPid !== null && servingPid !== state.pid) {
+            await removeQuietly(record.path);
+            continue;
+        }
+        reads.push(servingPid === state.pid ? { status: "live", state } : { status: "unconfirmed", state });
     }
-    if (!probes.isAlive(state.pid)) {
-        await removeDevState(homeDirectory, state.pid);
-        return { status: "none", state: null };
+    return reads.sort((a, b) => (a.state.startedAt < b.state.startedAt ? -1 : a.state.startedAt > b.state.startedAt ? 1 : 0));
+}
+// A dev that has just bound its ports clears every other record naming one
+// of them: those ports are held exclusively on 127.0.0.1, so no dev such a
+// record names can still be serving there.
+export async function pruneDevStatesForPorts(homeDirectory, ownPid, hostPort, appPort) {
+    const ours = [hostPort, appPort];
+    for (const record of await recordFiles(homeDirectory)) {
+        const state = await readDevStateFile(record.path);
+        if (state === null || state === "skip" || state === "malformed" || state.pid === ownPid) {
+            continue;
+        }
+        if (ours.includes(state.hostPort) || ours.includes(state.appPort)) {
+            await removeQuietly(record.path);
+        }
     }
-    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;
+// Windows has neither flag; there a symlink is followed and still checked
+// as a regular file through the one handle.
+function readFlags() {
+    return process.platform === "win32" ? constants.O_RDONLY : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+}
+// Two records name the same folder when their resolved paths match; paths
+// on Windows compare without regard to case, as its filesystems do.
+export function sameFolder(a, b) {
+    const left = resolve(a);
+    const right = resolve(b);
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+// Removal is best-effort: an entry that cannot be removed (a directory, a
+// file another program holds open on Windows) must never stop a dev from
+// starting or stopping.
+async function removeQuietly(path) {
+    await rm(path, { force: true }).catch(() => undefined);
+}
+// The states of the devs confirmed running, oldest first.
+export async function readLiveDevStates(homeDirectory, probes = defaultDevProbes()) {
+    const reads = await readDevStates(homeDirectory, probes);
+    return reads.filter((read) => read.status === "live").map((read) => read.state);
+}
+async function recordFiles(homeDirectory) {
+    const directory = driggsbyDirectory(homeDirectory);
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const name of names) {
+        if (name === LEGACY_STATE_FILE_NAME) {
+            files.push({ path: join(directory, name), pid: null });
+            continue;
+        }
+        const match = STATE_FILE_PATTERN.exec(name);
+        if (match !== null) {
+            files.push({ path: join(directory, name), pid: Number(match[1]) });
+        }
+    }
+    return files;
 }
 // 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
@@ -131,15 +209,14 @@ function pidFromIdentityBody(body) {
         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.
+// Removes the run's own record, and the legacy machine-wide record only if
+// it still names `pid`: a dev that ends must never erase another's record.
 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 });
+    await removeQuietly(devStatePath(homeDirectory, pid));
+    const legacyPath = join(driggsbyDirectory(homeDirectory), LEGACY_STATE_FILE_NAME);
+    const legacy = await readDevStateFile(legacyPath);
+    if (legacy !== null && legacy !== "skip" && legacy !== "malformed" && legacy.pid === pid) {
+        await removeQuietly(legacyPath);
     }
 }
 export function processIsAlive(pid) {
@@ -152,20 +229,41 @@ export function processIsAlive(pid) {
         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);
+// Only a small regular file is read. The file is opened without following
+// a symlink (a symlink reads as malformed, and removing it unlinks only the
+// link) and without blocking (a FIFO never hangs the read), then checked
+// and read through that one handle, so nothing swapped in after a check is
+// ever read. Anything else at the path (a directory, a device) is skipped.
+async function readDevStateFile(path) {
+    let handle;
+    try {
+        handle = await open(path, readFlags());
+    }
+    catch (error) {
+        const code = error.code;
+        return code === "ELOOP" || code === "EMLINK" ? "malformed" : code === "ENOENT" ? null : "skip";
+    }
     let raw;
     try {
-        const info = await lstat(path);
-        if (!info.isFile() || info.size > STATE_MAX_BYTES) {
+        const info = await handle.stat();
+        if (!info.isFile()) {
+            return "skip";
+        }
+        if (info.size > STATE_MAX_BYTES) {
             return "malformed";
         }
-        raw = await readFile(path, "utf8");
+        const buffer = Buffer.alloc(STATE_MAX_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > STATE_MAX_BYTES) {
+            return "malformed";
+        }
+        raw = buffer.subarray(0, bytesRead).toString("utf8");
     }
     catch {
-        return null;
+        return "skip";
+    }
+    finally {
+        await handle.close();
     }
     try {
         const parsed = JSON.parse(raw);
@@ -181,7 +279,10 @@ function isDevState(value) {
     }
     const record = value;
     return (isPid(record.pid) &&
+        // Always absolute as dev writes it; a relative one would match any
+        // folder it is read from.
         typeof record.folder === "string" &&
+        isAbsolute(record.folder) &&
         typeof record.startedAt === "string" &&
         isPort(record.hostPort) &&
         isPort(record.appPort));

package/dist/dev/dev-stop.js

@@ -1,11 +1,18 @@
-// 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).
+// driggsby dev --stop: end a `driggsby dev` without its 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. Several previews
+// can run at once, one per app folder, often each an agent's: run anywhere
+// inside an app (its folder or a subfolder), it stops that app's preview
+// and never another's; run outside any app, it stops the only preview
+// running, and with several it names them rather than guess. A record is
+// trusted only after its recorded port confirms it is served by the
+// recorded pid (see readDevStates), and that is confirmed again just before
+// the signal.
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve as resolvePath } from "node:path";
 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 { defaultDevProbes, readDevStates, removeDevState, sameFolder, } 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;
@@ -25,42 +32,65 @@ function defaultDevStopIo() {
         },
     };
 }
-export async function runDevStop(homeDirectory, io = defaultDevStopIo(), deps = defaultDevStopDeps()) {
-    const read = await readDevState(homeDirectory, deps);
-    if (read.status === "none") {
+export async function runDevStop(homeDirectory, io = defaultDevStopIo(), deps = defaultDevStopDeps(), currentFolder = process.cwd()) {
+    const reads = await readDevStates(homeDirectory, deps);
+    if (reads.length === 0) {
         io.out(nothingRunning());
         return 0;
     }
+    // The app this runs in, found the way `dev` records it: the nearest folder
+    // at or above this one with a driggsby.json. Its live preview comes first:
+    // a leftover record for the app must never hide the one running there.
+    const appFolder = await appFolderAround(currentFolder);
+    const here = reads.filter((each) => sameFolder(each.state.folder, appFolder ?? currentFolder));
+    let read = here.find(isLive) ?? here[0];
+    if (read === undefined) {
+        if (appFolder !== null) {
+            io.out(nothingRunningForThisApp(reads));
+            return 0;
+        }
+        const live = reads.filter(isLive);
+        read = live.length === 1 ? live[0] : live.length === 0 && folderCount(reads) === 1 ? reads[0] : undefined;
+    }
+    if (read === undefined) {
+        throw severalRunning(reads);
+    }
     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);
+    // 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. The port
+    // is asked again right before the signal, since reading every record
+    // can take a few seconds on a busy machine.
+    if (read.status === "unconfirmed" || (await deps.pidServing(state.hostPort)) !== state.pid) {
+        throw unconfirmed(folder);
     }
     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.
+        // Gone between the check and the signal: nothing left to stop. A dev
+        // the port vouched for that this process may not signal (a sandboxed
+        // agent, another user's process) is still running, so its record stays
+        // and the person is told where to stop it. Any other failure leaves the
+        // record too.
         const code = error.code;
-        if (code === "ESRCH" || code === "EPERM") {
+        if (code === "ESRCH") {
             await removeDevState(homeDirectory, state.pid);
-            io.out(nothingRunning());
+            io.out(`driggsby dev had already stopped for the app in:\n  ${folder}\n`);
             return 0;
         }
+        if (code === "EPERM") {
+            throw new CliError(`driggsby dev is running for the app in:\n  ${folder}\n\n` +
+                "but isn't allowed to be stopped from here. Press Ctrl+C in the terminal\n" +
+                "where it runs.", 1);
+        }
         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`);
+            io.out(`✓ Stopped   driggsby dev for the app in:\n  ${folder}\n\nStart it again in its folder with:\n  ${DEV_START_COMMAND}\n`);
             return 0;
         }
         await new Promise((resolve) => {
@@ -71,6 +101,60 @@ export async function runDevStop(homeDirectory, io = defaultDevStopIo(), deps =
         "Press Ctrl+C in the terminal where it runs, then check again:\n" +
         `  ${DEV_STOP_COMMAND}`, 1);
 }
+function isLive(read) {
+    return read.status === "live";
+}
+async function appFolderAround(folder) {
+    for (let current = resolvePath(folder);; current = dirname(current)) {
+        if (await hasAppConfig(current)) {
+            return current;
+        }
+        if (dirname(current) === current) {
+            return null;
+        }
+    }
+}
+async function hasAppConfig(folder) {
+    try {
+        return (await stat(join(folder, "driggsby.json"))).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function folderCount(reads) {
+    const folders = [];
+    for (const read of reads) {
+        if (!folders.some((folder) => sameFolder(folder, read.state.folder))) {
+            folders.push(read.state.folder);
+        }
+    }
+    return folders.length;
+}
+function unconfirmed(folder) {
+    return 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 record is a leftover.", 1);
+}
+// One line per folder, the ones that did not answer marked as such.
+function runningFolders(reads) {
+    const lines = reads.map((read) => `  ${displayFolder(read.state.folder)}${read.status === "live" ? "" : " (not answering)"}`);
+    return [...new Set(lines)].join("\n");
+}
+function nothingRunningForThisApp(reads) {
+    return ("No driggsby dev is running for this app.\n\n" +
+        `Previews running for other apps, each stopped from its own folder:\n${runningFolders(reads)}\n\n` +
+        `Start one in this app's folder with:\n  ${DEV_START_COMMAND}\n`);
+}
+function severalRunning(reads) {
+    const apps = folderCount(reads) > 1 ? "more than one app" : "one app more than once";
+    const head = reads.some(isLive)
+        ? `driggsby dev is running for ${apps}, in:`
+        : `driggsby dev is recorded for ${apps}, and none answered:`;
+    return new CliError(`${head}\n${runningFolders(reads)}\n\n` +
+        `Nothing was stopped. Run this in the folder of the one to stop:\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/help.js

@@ -86,18 +86,20 @@ This runs the app locally, embedded the same way Driggsby embeds it after a
 deploy, so what you see here is what a deploy will show. Edits to the app's
 files reload the page on save.
 
+Previews for several apps can run at once; each prints its own addresses.
+
 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: 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.
+it when you're done: press Ctrl+C, or run npx driggsby@latest dev --stop
+in the app's folder. 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 [--stop]
 
 Options:
-      --stop  Stop the driggsby dev running on this machine.
+      --stop  Stop this app's driggsby dev, or the only one running.
   -h, --help  Print help
 `;
 export const DEPLOY_HELP = `Deploy the app in this directory to Driggsby.

package/dist/init/templates.js

@@ -96,9 +96,10 @@ export const APP_JS = `// Your app's code. Edit anything — driggsby dev reload
 // These are the tools an app can watch — read-only, nothing else responds:
 //
 //   get_overview                 money rollups + every linked account
-//   get_history                  balances, holdings, or debts over time
-//                                (history_type is required: "account_balances",
-//                                "investment_holdings", or "liabilities")
+//   get_history                  balances, holdings, debts, or manual items
+//                                over time (history_type is required:
+//                                "account_balances", "investment_holdings",
+//                                "liabilities", or "custom_items")
 //   list_accounts                current balances per linked account
 //   list_assets_and_liabilities  the full balance sheet, incl. manual items
 //   list_findings                issues Driggsby has flagged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driggsby",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Set up and build on Driggsby, the MCP server for personal finance.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@driggsby/deploy": "0.4.1",
-    "@driggsby/sdk": "0.4.1"
+    "@driggsby/deploy": "0.5.1",
+    "@driggsby/sdk": "0.5.1"
   }
 }