directionallylocal 0.7.0 → 0.8.1

package/README.md

@@ -11,7 +11,7 @@ dl
 
 `dl` asks where your agents should run:
 
-- **On this computer** — start now, nothing to rent, pauses when this computer sleeps.
+- **On this computer** — start now, nothing to rent, pauses when this computer sleeps. macOS and Linux; not offered on Windows yet (connect a server, or run `dl` inside WSL 2, which takes the Linux path).
 - **On my own server** — keeps going when your laptop is closed; needs SSH access.
 
 For a server, `dl` lists the hosts in `~/.ssh/config` (or takes `user@host[:port]`), checks it over SSH, installs itself there, and pairs this laptop. Nothing is exposed on the server: `dl` reaches it through an SSH tunnel.
@@ -71,6 +71,7 @@ The "fits ~N agents" figure is a conservative estimate: memory left after the ho
 | `dl runs` | Your tasks and their pull requests. `--json` for scripts. |
 | `dl watch ID` / `dl cancel ID` | Follow a task, or stop one. |
 | `dl pull ID` | Check out a task's branch here. |
+| `dl preview ID` | Deploy a task's Workers branch on the server with Serverless Objects and open it here, over the SSH tunnel. |
 | `dl servers` | Where agents run. `dl servers rename OLD NEW`, `dl servers remove NAME`. |
 | `dl use [NAME]` | Where tasks go without `--server`. With no name, shows it. |
 | `dl keys [openrouter\|github]` | Which keys are set, or replace one. `--server NAME` picks the server. |
@@ -93,6 +94,8 @@ Run these as root. `dl` on its own shows what this is, whether it's healthy, the
 | `dl laptops` | Connected laptops. `dl laptops remove NAME` disconnects one. |
 | `dl runs` | Tasks running or done, with their pull requests. |
 | `dl logs [hotcell\|autopilot] [-f]` | The services' logs. |
+| `dl preview ID [--remove]` | Deploy a task's branch as a preview, or stop it. Needs `DL_PREVIEWS_BUCKET`. |
+| `dl previews` | Live previews: task, port, branch. |
 | `dl doctor` | Check every part, with a fix for each failure. |
 | `dl keys [set openrouter\|github]` | Which keys are set, or replace one (hidden input). |
 | `dl status` | Show the installed versions and where to reach the server. |

package/dist/cli.js

@@ -9,6 +9,7 @@ import { loadRemotes } from "./laptop/config.js";
 import { keys } from "./laptop/keys.js";
 import { model } from "./laptop/settings.js";
 import { projectSession } from "./laptop/session.js";
+import { preview as laptopPreview } from "./laptop/preview.js";
 import { setup } from "./laptop/setup.js";
 import { realSshExec } from "./laptop/ssh.js";
 import { update } from "./laptop/update.js";
@@ -19,6 +20,7 @@ import { readState } from "./state.js";
 import { DryRunSystem, RealSystem } from "./system.js";
 import { uninstall } from "./uninstall.js";
 import { JsonUi, PlainUi, TerminalUi, palette } from "./ui.js";
+import { previewCommand, previewsCommand } from "./preview.js";
 import { needs, parseAccessMode, parseProvidedAnswers, up } from "./up.js";
 const HELP = `Directionally Local: coding agents that run on this computer or on your own server.
 Send a task; it runs in its own sandbox and comes back as a pull request.
@@ -36,6 +38,7 @@ On your laptop:
   dl runs                 your tasks and their pull requests
   dl watch ID             follow a task      dl cancel ID   stop one
   dl pull ID              check out a task's branch here
+  dl preview ID           deploy a task's Workers branch on the server and open it here
   dl servers              where agents run (dl servers remove NAME · dl servers rename OLD NEW)
   dl use [NAME]           where tasks go without --server (no NAME: show it)
   dl keys [openrouter|github]   which keys are set, or replace one (--server NAME)
@@ -53,6 +56,8 @@ On the server:
   dl connect-laptop CODE  approve the code a laptop shows
   dl laptops              connected laptops (dl laptops remove NAME to disconnect one)
   dl runs                 tasks running or done, with their pull requests
+  dl preview ID [--remove]   deploy a task's branch with Serverless Objects, or stop it
+  dl previews             live previews: task, port, branch
   dl logs [hotcell|autopilot] [-f]   the services' logs
   dl doctor               check every part, with a fix for each problem
   dl keys [set openrouter|github]   which keys are set, or replace one (hidden input)
@@ -305,6 +310,34 @@ export async function main(argv, io = {
                 io.err(`  dl new starts a fresh conversation from inside a GitHub repository (with something set up: dl setup).\n`);
                 return 1;
             }
+            case "preview": {
+                const id = parsed.positionals[1];
+                if (!id) {
+                    io.err(`  Usage: dl preview ID   ${colors.dim("(from dl runs)")}\n`);
+                    return 2;
+                }
+                // On a server, deploy it; on a laptop, ask the server to and tunnel to the result.
+                if (await readState(system)) {
+                    if (!isRoot()) {
+                        io.err(`  Run it as root: sudo dl preview ${id}\n`);
+                        return 1;
+                    }
+                    return await previewCommand(system, parsed.positionals.slice(1), { json: Boolean(values.json) }, io.out, colors);
+                }
+                return await laptopPreview({ id, ...(values.server ? { server: values.server } : {}) }, {}, laptopIO);
+            }
+            case "previews": {
+                const state = await readState(system);
+                if (!state) {
+                    io.out(NOT_A_SERVER(colors));
+                    return 1;
+                }
+                if (!isRoot()) {
+                    io.err("  Run it as root: sudo dl previews\n");
+                    return 1;
+                }
+                return await previewsCommand(system, io.out, colors);
+            }
             case "servers":
                 return await servers(parsed.positionals.slice(1), laptopIO);
             case "use":

package/dist/home.js

@@ -3,6 +3,7 @@ import { AUTOPILOT_PORT, CELL_MEMORY_MB, SERVICES } from "./layout.js";
 import { approvePairing, createLaptopCredential, listLaptops, listServerRuns, ownerLink, pendingPairings, revokeLaptop } from "./server-api.js";
 import { describeAccess, readState } from "./state.js";
 import { palette } from "./ui.js";
+import { readPreviews } from "./preview.js";
 import { nextSteps } from "./up.js";
 const ABOUT = "Background coding agents on your own server: send a task from your laptop, get a pull request back.";
 /** Quick health for the home screen and the login line: services up and the API answering. */
@@ -21,8 +22,8 @@ async function health(system) {
 }
 /** `dl` on a server: what this is, whether it's healthy, who's connected, what's running, what to do. */
 export async function serverHome(system, state, write, c) {
-    const [status, laptops, runs, pending, facts] = await Promise.all([
-        health(system), listLaptops(system), listServerRuns(system), pendingPairings(system), detectHost(system),
+    const [status, laptops, runs, pending, facts, previews] = await Promise.all([
+        health(system), listLaptops(system), listServerRuns(system), pendingPairings(system), detectHost(system), readPreviews(system),
     ]);
     const verdict = status.ok ? c.green("● healthy") : c.red(`● ${status.problems.join(", ")}`);
     const week = Date.now() - 7 * 24 * 60 * 60 * 1000;
@@ -33,6 +34,9 @@ export async function serverHome(system, state, write, c) {
     write(row("Laptops", laptops === undefined ? c.dim("unknown (run dl up to update)") : laptops.length === 0 ? "none connected yet" : `${laptops.length} connected · ${laptops.map((laptop) => laptop.name).join(", ")}`, "dl laptops"));
     write(row("Runs", runs === undefined ? c.dim("unknown (run dl up to update)") : `${running} running · ${doneThisWeek} this week`, "dl runs"));
     write(row("Capacity", `~${agentCapacity(facts, CELL_MEMORY_MB)} agents at once (estimate)`));
+    if (previews.previews.length > 0) {
+        write(row("Previews", `${previews.previews.length} live · ${previews.previews.map((preview) => preview.id).join(", ")}`, "dl previews"));
+    }
     if (pending.length > 0) {
         write(`\n  ${c.yellow("!")} Waiting for approval: ${pending.map((entry) => `${c.bold(entry.code)} (${entry.name})`).join(", ")}   ${c.dim("dl connect-laptop <code>")}\n`);
     }

package/dist/laptop/preview.js

@@ -0,0 +1,60 @@
+import { palette } from "../ui.js";
+import { resolveRemote } from "./config.js";
+import { openBrowser } from "./open-browser.js";
+import { checkServer, realSshExec, shellQuote } from "./ssh.js";
+import { createForwarder } from "./tunnel.js";
+/** Non-root users run the server commands with sudo; checkServer made sure it needs no password. */
+function sudo(facts) {
+    return facts.root ? "" : "sudo -n ";
+}
+export async function preview(input, deps, io) {
+    const c = palette(io.color === true);
+    const remote = await resolveRemote(input.server);
+    if (!remote.ssh) {
+        io.err(`\n  ${c.red("✗")} ${remote.name} wasn't set up over SSH, so this laptop can't reach a preview on it.\n  On the server: ${c.bold(`dl preview ${input.id}`)}\n\n`);
+        return 1;
+    }
+    const ssh = deps.ssh ?? realSshExec;
+    const facts = await checkServer(remote.ssh, ssh, remote.name);
+    io.err(`  ${c.cyan("·")} Deploying ${input.id} on ${remote.name}…\n`);
+    const result = await ssh(remote.ssh, `${sudo(facts)}dl preview ${shellQuote(input.id)} --json`);
+    const answer = lastJson(result.stdout);
+    if (result.code !== 0 || typeof answer?.port !== "number") {
+        const detail = lastLine(result.stderr) || lastLine(result.stdout) || `dl preview exited with ${result.code}`;
+        io.err(`\n  ${c.red("✗")} ${detail}\n\n`);
+        return 1;
+    }
+    const forward = deps.forward ?? createForwarder();
+    const endpoint = await forward(remote.ssh, answer.port, remote.name);
+    const id = typeof answer.id === "string" ? answer.id : input.id;
+    io.out(`\n  ${c.green("✓")} ${id} is live at ${c.bold(endpoint.url)}\n`);
+    io.out(`  ${c.dim("Ctrl-C closes the tunnel; the preview keeps running (dl preview " + id + " --remove stops it).")}\n\n`);
+    if ((deps.openBrowser ?? openBrowser)(endpoint.url))
+        io.out(`  ${c.dim("(opened it for you)")}\n\n`);
+    try {
+        await (deps.hold ?? holdUntilInterrupted)();
+    }
+    finally {
+        await endpoint.close();
+    }
+    return 0;
+}
+function holdUntilInterrupted() {
+    return new Promise((resolve) => {
+        process.once("SIGINT", () => resolve());
+    });
+}
+function lastJson(text) {
+    for (const line of text.trim().split("\n").reverse()) {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            // keep looking: a banner or warning may come before the JSON
+        }
+    }
+    return undefined;
+}
+function lastLine(text) {
+    return text.trim().split("\n").at(-1)?.trim() ?? "";
+}

package/dist/laptop/session.js

@@ -55,7 +55,7 @@ export async function projectSession(input, io) {
         note(describeError(error));
         return undefined;
     }
-    const { remote } = target;
+    const { remote, reason } = target;
     const key = { place: remote.name, repository, root };
     const file = input.sessionsFile ?? sessionsPath();
     const autopilot = await (input.autopilot ?? findAutopilot)();
@@ -142,7 +142,12 @@ export async function projectSession(input, io) {
                 // `dl new`: the old conversation keeps running on the place (dl runs lists it).
                 if (input.fresh)
                     await forgetSession(key, file);
-                io.err(`\n  ${c.cyan("·")} Connecting to ${c.bold(remote.name)} · ${repository} …  ${c.dim(`(${detail})`)}\n`);
+                // The place is on the Connecting line already; with more than one set up, also why this
+                // one and how to pick another, as `dl run` does (a place named with --server needs neither).
+                const chosen = reason === "default" || reason === "last used";
+                io.err(`\n  ${c.cyan("·")} Connecting to ${c.bold(remote.name)}${chosen ? ` ${c.dim(`(${reason})`)}` : ""} · ${repository} …  ${c.dim(`(${detail})`)}\n`);
+                if (chosen)
+                    io.err(`    ${c.dim("dl use NAME to change where dl runs")}\n`);
                 // The token goes in the environment only: argv is visible to every user on the machine.
                 const env = { ...process.env, AUTOPILOT_REMOTE_URL: client.baseUrl, AUTOPILOT_REMOTE_TOKEN: remote.token };
                 let saved = remembered?.conversationId;

package/dist/laptop/settings.js

@@ -37,7 +37,10 @@ export async function loadSettings(path = settingsPath()) {
     }
     try {
         const parsed = JSON.parse(raw);
-        return typeof parsed.model === "string" && parsed.model.trim() ? { model: parsed.model.trim() } : {};
+        return {
+            ...(typeof parsed.model === "string" && parsed.model.trim() ? { model: parsed.model.trim() } : {}),
+            ...(parsed.askedLocalDefault === true ? { askedLocalDefault: true } : {}),
+        };
     }
     catch {
         // A damaged file only loses the saved model; the next save rewrites it.
@@ -45,7 +48,11 @@ export async function loadSettings(path = settingsPath()) {
     }
 }
 export async function saveModel(model, path = settingsPath()) {
-    const settings = { ...(await loadSettings(path)), model };
+    await saveSettings({ model }, path);
+}
+/** Merges into dl's settings, keeping what's already there. */
+export async function saveSettings(changes, path = settingsPath()) {
+    const settings = { ...(await loadSettings(path)), ...changes };
     await mkdir(dirname(path), { recursive: true });
     const temp = `${path}.${process.pid}.tmp`;
     await writeFile(temp, `${JSON.stringify({ version: 1, ...settings }, null, 2)}\n`, { mode: 0o600 });

package/dist/laptop/setup.js

@@ -5,11 +5,12 @@ import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { PromptCancelled, TtyPrompter } from "../prompt.js";
 import { palette, PlainUi, TerminalUi } from "../ui.js";
-import { loadRemotes, loadRemotesFile, normalizeServerUrl, REMOTE_NAME_RE, remotesPath, saveRemote, setDefaultRemote } from "./config.js";
+import { localUnsupported } from "../local/check.js";
+import { loadRemotes, loadRemotesFile, normalizeServerUrl, REMOTE_NAME_RE, remotesPath, resolveTarget, saveRemote, setDefaultRemote } from "./config.js";
 import { confirm, gatherKeys } from "./credentials.js";
 import { bootstrap, INSTALL_URL, installOnServer, pairLaptop, serverNeeds } from "./remote-install.js";
 import { checkServer, describeHost, discoverKeys, hostOf, parseSshConfig, parseTarget, realSshExec, SshAuthError } from "./ssh.js";
-import { askModel, DEFAULT_MODEL, loadSettings, modelPrices, readAutopilotModel, saveModel } from "./settings.js";
+import { askModel, DEFAULT_MODEL, loadSettings, modelPrices, readAutopilotModel, saveModel, saveSettings } from "./settings.js";
 import { openRemote, withConnections } from "./tunnel.js";
 const RUN_EXAMPLE = 'dl run "fix the flaky checkout test"';
 const PLACES = [
@@ -20,6 +21,13 @@ export async function setupWizard(deps) {
     const c = palette(deps.color);
     deps.write(`\n  ${c.bold("Directionally Local")}\n  Background coding agents. Where should they run?\n\n`);
     const ui = deps.newUi();
+    // Where this computer can't run agents (Windows), the list would hold one real choice: say why, and go on.
+    const unsupported = localUnsupported(deps.platform ?? process.platform);
+    if (unsupported) {
+        ui.line("info", "On this computer", unsupported);
+        ui.answered("Where", "On my own server");
+        return setUpServer(deps);
+    }
     let where = (await deps.prompter.select(ui.prompt("Where"), PLACES, 0)).value;
     ui.answered("Where", where === "local" ? "On this computer" : "On my own server");
     if (where === "local" && !deps.localSetup) {
@@ -39,8 +47,7 @@ export async function setupWizard(deps) {
         const remotesFile = deps.remotesFile ?? remotesPath();
         const isNew = !(await loadRemotes(remotesFile)).some((entry) => entry.name === remote.name);
         await saveRemote(remote, remotesFile);
-        if (isNew)
-            await chooseDefault(deps, remote, remotesFile);
+        await offerThisComputer(deps, remote, remotesFile, isNew);
         await chooseModel(deps);
         finishScreen(deps.newUi(), capacity);
         return remote;
@@ -142,7 +149,7 @@ async function chooseServer(deps, hosts) {
 }
 /**
  * With two or more places set up, where `dl run` sends tasks unless told otherwise. Asked
- * only when setup adds a place, with the new one preselected; the first place becomes the
+ * only when setup adds a server, with the new one preselected (this computer: offerThisComputer); the first place becomes the
  * default by itself (saveRemote).
  */
 async function chooseDefault(deps, added, remotesFile) {
@@ -158,6 +165,36 @@ async function chooseDefault(deps, added, remotesFile) {
     ui.answered("Default", value);
     ui.finish();
 }
+/**
+ * After "on this computer", when commands would still go somewhere else (a server set up
+ * first stays the default, saveRemote): asks once, at a terminal, whether this computer
+ * should be the default instead. Asked again only when this computer is newly added.
+ * Otherwise (no terminal, already asked, or "no") it says where things go and how to change it.
+ */
+async function offerThisComputer(deps, local, remotesFile, isNew) {
+    const { remotes } = await loadRemotesFile(remotesFile);
+    if (remotes.length < 2)
+        return;
+    const current = await resolveTarget(undefined, remotesFile).then((target) => target.remote.name, () => undefined);
+    if (current === local.name)
+        return;
+    const hint = `dl use ${local.name}`;
+    const ui = deps.newUi();
+    deps.write("\n");
+    if (deps.interactive !== false && (isNew || !(await loadSettings(deps.settingsFile)).askedLocalDefault)) {
+        const question = current ? `Make this computer the default? Tasks and sessions go to ${current} now` : "Make this computer the default for tasks and sessions?";
+        const yes = await confirm(ui, deps.prompter, question);
+        await saveSettings({ askedLocalDefault: true }, deps.settingsFile);
+        if (yes) {
+            await setDefaultRemote(local.name, remotesFile);
+            ui.answered("Default", "this computer");
+            ui.finish();
+            return;
+        }
+    }
+    ui.line("info", "Default", current ? `still ${current} · ${hint} to run here instead` : `none yet · ${hint} to run here`);
+    ui.finish();
+}
 /**
  * Which model tasks and sessions use, asked once: setup skips it when dl already has one
  * (dl model changes it). Autopilot's own default is preselected for people who have one.
@@ -335,6 +372,7 @@ export async function setup(options) {
             installUrl: process.env.DL_INSTALL_URL || INSTALL_URL,
             ...(options.localSetup ? { localSetup: options.localSetup } : {}),
             ...(identityFile ? { identityFile } : {}),
+            interactive: terminal && process.stdin.isTTY === true,
         });
     }
     catch (error) {

package/dist/laptop/tunnel.js

@@ -7,17 +7,13 @@ const realSpawn = (args) => spawn("ssh", args, { stdio: ["ignore", "ignore", "pi
 export function tunnelArgs(access, localPort, remotePort) {
     return ["-N", "-o", "ExitOnForwardFailure=yes", ...sshOptions(access), "-L", `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`, access.target];
 }
-export function createOpener(options = {}) {
+export function createForwarder(options = {}) {
     const spawnTunnel = options.spawn ?? realSpawn;
     const freePort = options.freePort ?? pickFreePort;
     const accepts = options.accepts ?? acceptsConnections;
     const timeoutMs = options.timeoutMs ?? 20_000;
     const pollMs = options.pollMs ?? 100;
-    return async (remote) => {
-        if (!remote.ssh)
-            return { url: remote.url, close: async () => { } };
-        const access = remote.ssh;
-        const remotePort = Number(new URL(remote.url).port || 80);
+    return async (access, remotePort, display = access.target) => {
         const port = await freePort();
         const child = spawnTunnel(tunnelArgs(access, port, remotePort));
         let stderr = "";
@@ -44,18 +40,26 @@ export function createOpener(options = {}) {
             if (exited) {
                 await close();
                 const detail = stderr.trim().split("\n").at(-1)?.trim();
-                throw new Error(`Couldn't open an SSH tunnel to ${remote.name} (${access.target})${detail ? `: ${detail}` : ""}\n  Check that this works: ${sshCommandLine(access)}`);
+                throw new Error(`Couldn't open an SSH tunnel to ${display} (${access.target})${detail ? `: ${detail}` : ""}\n  Check that this works: ${sshCommandLine(access)}`);
             }
             if (await accepts(port))
                 return { url: `http://127.0.0.1:${port}`, close };
             if (Date.now() >= deadline) {
                 await close();
-                throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s opening an SSH tunnel to ${remote.name} (${access.target}).\n  Check that this works: ${sshCommandLine(access)}`);
+                throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s opening an SSH tunnel to ${display} (${access.target}).\n  Check that this works: ${sshCommandLine(access)}`);
             }
             await new Promise((resolve) => setTimeout(resolve, pollMs));
         }
     };
 }
+export function createOpener(options = {}) {
+    const forward = createForwarder(options);
+    return async (remote) => {
+        if (!remote.ssh)
+            return { url: remote.url, close: async () => { } };
+        return forward(remote.ssh, Number(new URL(remote.url).port || 80), remote.name);
+    };
+}
 export const openRemote = createOpener();
 /**
  * For an interactive session: ssh in its own process group, so Ctrl-C typed into the agent's

package/dist/layout.js

@@ -17,6 +17,9 @@ export const PATHS = {
     autopilotHome: "/var/lib/autopilot",
     workspace: "/var/lib/autopilot/workspaces/default",
     units: "/etc/systemd/system",
+    /** One checkout and one Serverless Objects node per preview (docs/plans/preview-deploys.md). */
+    previews: "/var/lib/directionallylocal/previews",
+    previewsState: "/var/lib/directionallylocal/previews.json",
 };
 /** Lets Ubuntu's unattended-upgrades install Node.js fixes from NodeSource, like its own packages. */
 export const NODE_AUTO_UPDATES = "/etc/apt/apt.conf.d/52directionallylocal-nodejs";

package/dist/local/check.js

@@ -41,9 +41,9 @@ export async function checkComputer(system, options) {
 /** What stops setup before it changes anything, each with how to fix it. */
 export function computerProblems(facts) {
     const problems = [];
-    if (facts.platform !== "darwin" && facts.platform !== "linux") {
-        return [`Running agents on this computer works on macOS and Linux, not ${facts.platform}. Set up a server instead: curl -fsSL https://directionallylocal.run | sh`];
-    }
+    const unsupported = localUnsupported(facts.platform);
+    if (unsupported)
+        return [unsupported];
     if (facts.platform === "linux" && !facts.systemdUser) {
         problems.push("A systemd user session is needed to keep the agents running (systemctl --user). Log in to a desktop session, or set up a server instead.");
     }
@@ -79,6 +79,20 @@ function dockerFix(facts) {
 export function localCapacity(docker) {
     return agentCapacity({ memoryMb: docker.memoryMb, cpus: docker.cpus }, LOCAL_CELL_MEMORY_MB);
 }
+/**
+ * Why agents can't run on this computer's platform, or undefined on macOS and Linux. The
+ * local setup is POSIX throughout (sh, launchd or systemd --user, unix sockets), so other
+ * platforms are refused before anything runs. WSL reports "linux" and takes the Linux path.
+ */
+export function localUnsupported(platform) {
+    if (supportedPlatform(platform))
+        return undefined;
+    if (platform === "win32") {
+        return "Running on this computer isn't supported on Windows yet; connect a server instead (dl setup, then \"On my own server\"). "
+            + "Inside WSL 2, dl runs as on Linux (it needs systemd and Docker there).";
+    }
+    return `Running agents on this computer works on macOS and Linux, not ${platform}. Connect a server instead: dl setup, then "On my own server".`;
+}
 export function supportedPlatform(platform) {
     return platform === "darwin" || platform === "linux" ? platform : undefined;
 }

package/dist/local/keys.js

@@ -8,7 +8,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { checkKey, githubListing, hotcellKeyListed, KeyRejectedError } from "../keys.js";
 import { RealSystem } from "../system.js";
-import { supportedPlatform } from "./check.js";
+import { localUnsupported, supportedPlatform } from "./check.js";
 import { LOCAL_SERVICES, localGithubEnv, localHotcellBin, localPaths, parseLocalEnvFile, serviceFile } from "./layout.js";
 import { httpStatus } from "./probes.js";
 import { userId } from "./services.js";
@@ -16,9 +16,10 @@ import { hotcellCliEnv } from "./setup.js";
 import { readLocalState } from "./state.js";
 async function installed(options) {
     const home = options.home ?? homedir();
-    const platform = supportedPlatform(options.platform ?? process.platform);
+    const raw = options.platform ?? process.platform;
+    const platform = supportedPlatform(raw);
     if (!platform)
-        throw new Error("Agents run on this computer only on macOS and Linux.");
+        throw new Error(localUnsupported(raw));
     const system = options.system ?? new RealSystem(() => { });
     const paths = localPaths(home, platform);
     const state = await readLocalState(system, paths);

package/dist/local/setup.js

@@ -26,7 +26,7 @@ import { join } from "node:path";
 import { cellDockerfile, cellImage } from "../layout.js";
 import { removeRemote } from "../laptop/config.js";
 import { RealSystem } from "../system.js";
-import { checkComputer, computerProblems, localCapacity, servicePath, supportedPlatform } from "./check.js";
+import { checkComputer, computerProblems, localCapacity, localUnsupported, servicePath, supportedPlatform } from "./check.js";
 import { LOCAL_SERVICES, PAIRED_NAME, PREFERRED_PORTS, autopilotXdg, localAsterConfig, localAutopilotBin, localAutopilotEnv, localGithubEnv, localHotcellBin, localHotcellEnv, localPaths, parseLocalEnvFile, serviceSpecs, } from "./layout.js";
 import { fileMtime, modelPricesHealth, refreshModelPrices } from "../model-prices.js";
 import { httpStatus, portFree } from "./probes.js";
@@ -37,10 +37,16 @@ const SETUP_LOG = "setup.log";
 export function localSetupLog(home = homedir()) {
     return join(home, ".directionallylocal", "logs", SETUP_LOG);
 }
+/** Stops on a platform the local setup can't run on (Windows), before any command runs. */
+export function assertLocalSupported(platform = process.platform) {
+    const unsupported = localUnsupported(platform);
+    if (unsupported)
+        throw new Error(unsupported);
+}
 function context(options, logName) {
     const home = options.home ?? homedir();
     const rawPlatform = options.platform ?? process.platform;
-    // Unsupported platforms still get paths (for a clear refusal); nothing is written there.
+    // Callers refuse unsupported platforms first (assertLocalSupported); this only keeps types simple.
     const platform = supportedPlatform(rawPlatform) ?? "linux";
     return {
         // Other tools' output goes to a log file (or nowhere), never the screen.
@@ -54,12 +60,15 @@ function context(options, logName) {
 }
 /** Checks this computer without changing anything, e.g. before the wizard asks for keys. */
 export async function checkThisComputer(options = {}) {
+    assertLocalSupported(options.platform);
     const ctx = context(options);
     const facts = await checkComputer(ctx.system, checkOptions(ctx, options));
     return { facts, problems: computerProblems(facts) };
 }
 export async function setUpOnThisComputer(input) {
     const { ui } = input;
+    // Before the checklist: on Windows nothing here (sh, launchd/systemd, unix sockets) works.
+    assertLocalSupported(input.platform);
     const ctx = context(input, SETUP_LOG);
     const { system, paths, platform } = ctx;
     const now = () => (input.now ?? (() => new Date()))().toISOString();
@@ -84,9 +93,6 @@ export async function setUpOnThisComputer(input) {
     };
     const { facts, uid } = await step("check", async () => {
         let facts = await checkComputer(system, checkOptions(ctx, input));
-        const unsupported = computerProblems(facts);
-        if (ctx.rawPlatform !== "darwin" && ctx.rawPlatform !== "linux")
-            throw new Error(unsupported[0]);
         const uid = await userId(system);
         if (!facts.docker && facts.dockerApp && platform === "darwin") {
             ui.start("check", `opening ${facts.dockerApp}`);
@@ -231,6 +237,7 @@ export async function setUpOnThisComputer(input) {
  */
 export async function uninstallFromThisComputer(input) {
     const { ui } = input;
+    assertLocalSupported(input.platform);
     const ctx = context(input, "uninstall.log");
     const { system, paths, platform } = ctx;
     const state = await readLocalState(system, paths);
@@ -284,6 +291,7 @@ export async function uninstallFromThisComputer(input) {
 }
 /** `dl local status`: is it running, where, and how much fits. Read-only. */
 export async function localStatus(options = {}) {
+    assertLocalSupported(options.platform);
     const ctx = context(options);
     const { system, paths, platform } = ctx;
     const state = await readLocalState(system, paths);

package/dist/preview.js

@@ -0,0 +1,219 @@
+import { join } from "node:path";
+import { parseEnvFile, PATHS, USERS } from "./layout.js";
+import { listServerRuns } from "./server-api.js";
+import { palette } from "./ui.js";
+/**
+ * `dl preview`: deploy an agent's Workers branch on this server with Serverless Objects and
+ * reach it over the laptop's SSH tunnel. Design: docs/plans/preview-deploys.md.
+ *
+ * Serverless Objects is pre-alpha, so a preview failing is expected rather than exceptional:
+ * it never fails the task or its pull request, and it is reported in `dl previews`.
+ */
+export const MAX_PREVIEWS = 3;
+export const PREVIEW_PORT_FIRST = 8090;
+export const PREVIEW_PORT_LAST = 8099;
+/** Root only: a monorepo with several Wrangler projects is out of scope for Phase 1. */
+const WRANGLER_CONFIGS = /^wrangler\.(json|jsonc|toml)$/;
+export function previewId(conversationId) {
+    return conversationId.slice(0, 8);
+}
+/** A branch is previewable when its root has a Wrangler config (design §3). */
+export function isWranglerProject(files) {
+    return files.some((name) => WRANGLER_CONFIGS.test(name));
+}
+/** The first free port in the range, or undefined when every slot is taken. */
+export function freePort(previews) {
+    const used = new Set(previews.map((preview) => preview.port));
+    for (let port = PREVIEW_PORT_FIRST; port <= PREVIEW_PORT_LAST; port++)
+        if (!used.has(port))
+            return port;
+    return undefined;
+}
+/** The preview's own node config (design §2.3): its own port and its own bucket prefix. */
+export function sobjectsToml(input) {
+    return `[celld]\nbucket = ${JSON.stringify(input.bucket)}\nlisten = "127.0.0.1:${input.port}"\n`;
+}
+export function bucketFor(prefix, id) {
+    return `${prefix.replace(/\/+$/, "")}/${id}`;
+}
+/**
+ * The token reaches git through the environment, never argv: `ps` would show it there.
+ * The helper string itself holds no secret.
+ */
+const CREDENTIAL_HELPER = 'credential.helper=!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f';
+export function cloneArgs(repository, branch, directory) {
+    return ["-c", CREDENTIAL_HELPER, "clone", "--depth", "1", "--branch", branch, `https://github.com/${repository}.git`, directory];
+}
+export function fetchArgs(branch) {
+    return ["-c", CREDENTIAL_HELPER, "fetch", "--depth", "1", "origin", branch];
+}
+export async function readPreviews(system) {
+    const raw = await system.readFile(PATHS.previewsState);
+    if (!raw)
+        return { version: 1, previews: [] };
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed.version === 1 && Array.isArray(parsed.previews) ? { version: 1, previews: parsed.previews } : { version: 1, previews: [] };
+    }
+    catch {
+        return { version: 1, previews: [] };
+    }
+}
+export async function writePreviews(system, state) {
+    await system.writeFile(PATHS.previewsState, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o644 });
+}
+/** The server's GitHub token, for a read-only clone as the autopilot user (design §2.5). */
+export async function githubToken(system) {
+    const token = parseEnvFile(await system.readFile(PATHS.githubEnv)).GITHUB_TOKEN;
+    return token || undefined;
+}
+/** Deploys (or redeploys) one run's branch, keeping its port and URL stable. */
+export async function deployPreview(run, deps) {
+    const { system } = deps;
+    const { repository, branch } = run;
+    if (!repository || !branch)
+        throw new Error("That task has no branch to preview yet; it pushes one when it finishes a step.");
+    const id = previewId(run.conversationId);
+    const directory = join(PATHS.previews, id);
+    const state = await readPreviews(system);
+    const existing = state.previews.find((preview) => preview.id === id);
+    const port = existing?.port ?? freePort(state.previews);
+    if (port === undefined)
+        throw new Error(`All ${MAX_PREVIEWS} preview slots are in use. Remove one: dl preview <id> --remove`);
+    await syncCheckout(system, { repository, branch, directory }, deps.token);
+    if (!(await isWranglerCheckout(system, directory))) {
+        throw new Error(`${repository} at ${branch} has no wrangler.json, wrangler.jsonc or wrangler.toml at its root, so there's nothing to preview.`);
+    }
+    await system.writeFile(join(directory, "sobjects.toml"), sobjectsToml({ bucket: bucketFor(deps.bucket, id), port }), {
+        mode: 0o644,
+        owner: `${USERS.autopilot}:${USERS.autopilot}`,
+    });
+    const env = { SOBJECTS_STATE_DIR: join(directory, "state") };
+    await system.run("sobjects", ["deploy", directory], { env, describe: `sobjects deploy ${id}` });
+    await system.run("sobjects", ["up", "--detach"], { env, cwd: directory, describe: `sobjects up ${id}` });
+    const wait = deps.waitForPort ?? ((target) => waitForPort(system, target));
+    if (!(await wait(port)))
+        throw new Error(`The preview started but nothing answered on 127.0.0.1:${port}. Check its log: dl logs`);
+    const preview = {
+        id,
+        conversationId: run.conversationId,
+        repository,
+        branch,
+        port,
+        directory,
+        createdAt: (deps.now?.() ?? new Date()).toISOString(),
+    };
+    await writePreviews(system, { version: 1, previews: [...state.previews.filter((entry) => entry.id !== id), preview] });
+    return preview;
+}
+/** Stops a preview's node and deletes its checkout and state. */
+export async function removePreview(id, system) {
+    const state = await readPreviews(system);
+    const preview = state.previews.find((entry) => entry.id === id);
+    if (!preview)
+        return false;
+    await system.run("sobjects", ["down"], {
+        cwd: preview.directory,
+        env: { SOBJECTS_STATE_DIR: join(preview.directory, "state") },
+        allowFailure: true,
+        describe: `sobjects down ${id}`,
+    });
+    await system.remove(preview.directory);
+    await writePreviews(system, { version: 1, previews: state.previews.filter((entry) => entry.id !== id) });
+    return true;
+}
+async function syncCheckout(system, input, token) {
+    const owner = `${USERS.autopilot}:${USERS.autopilot}`;
+    const env = { GITHUB_TOKEN: token };
+    if (!(await system.exists(input.directory))) {
+        await system.mkdir(PATHS.previews, { owner });
+        await system.run("runuser", ["-u", USERS.autopilot, "--", "git", ...cloneArgs(input.repository, input.branch, input.directory)], {
+            env,
+            describe: `clone ${input.repository}`,
+        });
+        return;
+    }
+    await system.run("runuser", ["-u", USERS.autopilot, "--", "git", "-C", input.directory, ...fetchArgs(input.branch)], {
+        env,
+        describe: `fetch ${input.branch}`,
+    });
+    await system.run("runuser", ["-u", USERS.autopilot, "--", "git", "-C", input.directory, "reset", "--hard", "FETCH_HEAD"], {
+        describe: `reset ${input.branch}`,
+    });
+}
+async function isWranglerCheckout(system, directory) {
+    const listing = await system.probe("ls", ["-1", directory]);
+    return listing.code === 0 && isWranglerProject(listing.stdout.split("\n").map((line) => line.trim()).filter(Boolean));
+}
+async function waitForPort(system, port, attempts = 30) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const answer = await system.probe("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", "2", `http://127.0.0.1:${port}/`]);
+        const code = answer.stdout.trim();
+        if (answer.code === 0 && code !== "" && code !== "000")
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+    }
+    return false;
+}
+/** `dl preview <id> [--remove] [--json]`: deploy a run's branch, or stop its preview. */
+export async function previewCommand(system, args, options, write, c) {
+    const id = args.find((arg) => !arg.startsWith("-"));
+    if (!id) {
+        write(`  Usage: dl preview <id>   ${c.dim("(from dl runs)")}   ${c.dim("--remove stops it")}\n`);
+        return 2;
+    }
+    if (args.includes("--remove")) {
+        const removed = await removePreview(id, system);
+        if (options.json)
+            write(`${JSON.stringify({ id, removed })}\n`);
+        else
+            write(`\n  ${removed ? c.green("✓") : c.red("✗")} ${removed ? `Removed the preview for ${id}` : `No preview for ${id}`}\n\n`);
+        return removed ? 0 : 1;
+    }
+    const runs = await listServerRuns(system, 200);
+    if (runs === undefined) {
+        write(`\n  ${c.red("✗")} Couldn't list runs; run ${c.bold("dl up")} to update this server.\n\n`);
+        return 1;
+    }
+    const matches = runs.filter((run) => run.conversationId.startsWith(id));
+    if (matches.length === 0) {
+        write(`\n  ${c.red("✗")} No task ${id}. ${c.dim("dl runs")} lists them.\n\n`);
+        return 1;
+    }
+    if (matches.length > 1) {
+        write(`\n  ${c.red("✗")} ${id} matches several tasks; use more characters.\n\n`);
+        return 1;
+    }
+    const token = await githubToken(system);
+    if (!token) {
+        write(`\n  ${c.red("✗")} This server has no GitHub token, so it can't clone the branch. Set one: ${c.bold("dl keys set github")}\n\n`);
+        return 1;
+    }
+    const bucket = options.bucket ?? process.env.DL_PREVIEWS_BUCKET;
+    if (!bucket) {
+        write(`\n  ${c.red("✗")} Previews need a bucket for their state. Set ${c.bold("DL_PREVIEWS_BUCKET")} in ${c.dim(PATHS.autopilotEnv)} (e.g. s3://my-previews).\n\n`);
+        return 1;
+    }
+    const preview = await deployPreview(matches[0], { system, bucket, token });
+    if (options.json) {
+        write(`${JSON.stringify({ id: preview.id, port: preview.port, url: `http://127.0.0.1:${preview.port}` })}\n`);
+        return 0;
+    }
+    write(`\n  ${c.green("✓")} ${preview.id} is live at ${c.bold(`http://127.0.0.1:${preview.port}`)}\n`);
+    write(`  ${c.dim("From your laptop:")} dl preview ${preview.id}   ${c.dim("Stop it:")} dl preview ${preview.id} --remove\n\n`);
+    return 0;
+}
+/** `dl previews`: the live previews, newest first. */
+export async function previewsCommand(system, write, c) {
+    const { previews } = await readPreviews(system);
+    if (previews.length === 0) {
+        write(`\n  No previews. From a task's branch:  ${c.bold("dl preview <id>")}\n\n`);
+        return 0;
+    }
+    write("\n");
+    for (const preview of [...previews].sort((a, b) => b.createdAt.localeCompare(a.createdAt))) {
+        write(`  ${c.green("●")} ${preview.id}  ${c.dim(`:${preview.port}`)}  ${(preview.repository ?? "").padEnd(28)} ${c.dim(preview.branch)}\n`);
+    }
+    write(`\n  ${c.dim("Open one from your laptop:")} dl preview <id>   ${c.dim("Stop one:")} dl preview <id> --remove\n\n`);
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "directionallylocal",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Directionally Local: background coding agents on your own server. One-line server install, and the dl command for your server and laptop.",
   "license": "Apache-2.0",
   "homepage": "https://directionallylocal.com",