@dylanpiercey/work 0.0.1

package/README.md

@@ -0,0 +1,99 @@
+# work
+
+A self-hosted web GUI for agentic dev workspaces — on desktop and as a mobile
+PWA. Spin up multi-repo worktree workspaces, run coding agents (Claude Code,
+Codex, Copilot, Cursor, Grok) or plain shells in real terminals, review diffs
+and send feedback to agents, and watch PR/CI status — from any device.
+
+- **Workspaces** — named directories of git worktrees (one per GitHub repo,
+  cloned from a shared bare-repo cache), all on a generated branch. Create,
+  add/remove repos, archive/restore, delete.
+- **Sessions** — real CLIs in tmux, mirrored to the browser over WebSocket
+  (xterm.js). Sessions survive server restarts and phone locks; agent hooks
+  surface working / waiting / idle state at a glance.
+- **Review** — a fast diff view across every repo in the workspace, with
+  line comments you can send straight into an agent session.
+- **Mobile-first PWA** — installable, with a touch-tuned terminal (sticky
+  keyboard toggle, d-pad for arrows/tab/ctrl-c, momentum scrolling).
+
+## Install (bare machine)
+
+One command on a fresh Linux or macOS box — installs the system tools
+(git, tmux, a compiler for node-pty), [mise](https://mise.jdx.dev) + node,
+the published package, and the background service (systemd/launchd):
+
+```sh
+curl -fsSL https://cdn.jsdelivr.net/npm/@dylanpiercey/work/install.sh | bash
+```
+
+Already have node (and git/tmux)? `npm i -g @dylanpiercey/work && work setup`
+does the same minus the system tools. Update later with `work update` (or
+re-run the installer).
+
+## Develop
+
+Requires Linux or macOS with `git`, `tmux`, `gh` (authenticated), and Node 22+.
+The bootstrap script installs everything via [mise](https://mise.jdx.dev),
+offers the agent CLIs, and runs `pnpm install`:
+
+```sh
+./scripts/bootstrap.sh
+```
+
+## Run
+
+```sh
+pnpm dev                  # http://localhost:7171
+```
+
+For a production build plus a background service (systemd on Linux, launchd on macOS):
+
+```sh
+./scripts/setup-prod.sh   # build + install + start the service
+./scripts/run-prod.sh     # or: build with --no-service and run manually
+./scripts/update.sh       # later: pull latest, rebuild, restart
+```
+
+To reach it from other devices, put it behind something that terminates TLS
+and authenticates — e.g. a Cloudflare Tunnel with Access, or Tailscale.
+Everything (pages, API, and the `/term` websockets) serves from the single
+app port, so route the whole hostname to it. Set
+`WORK_ALLOWED_HOSTS=your.domain` so the dev server accepts the hostname.
+
+> **Upgrading from the two-port layout:** older setups routed `/term/*` to a
+> separate terminal port (7172). That port no longer exists — remove the
+> `/term` rule from your tunnel/proxy config and send all traffic to the app
+> port, or terminals will fail to connect.
+
+## Configuration
+
+| Variable             | Default                 | Purpose                              |
+| -------------------- | ----------------------- | ------------------------------------ |
+| `WORK_ROOT`          | `~/work`                | Workspaces root (+ `.cache` bare repos) |
+| `WORK_DATA_DIR`      | `~/.local/share/work`   | sqlite db and server state           |
+| `WORK_APP_PORT`      | `7171`                  | HTTP server (app, assets, and `/term` websockets) |
+| `WORK_ALLOWED_HOSTS` | —                       | Extra dev-server hostnames (comma-separated) |
+| `WORK_USER` / `WORK_HOST` | current user/host  | Branch-name prefix parts             |
+| `WORK_BRANCH_PREFIX` | `<user>-<host>`         | Whole branch-name prefix, overriding the parts |
+
+Ports and paths can be exported before `scripts/setup-prod.sh` to bake them into
+the service. For settings that should outlive an update, put them in an untracked
+`.env.local` at the repo root instead — `scripts/run-prod.sh` reads it on every
+start (the dev server does not), only `WORK_*` names apply, and the
+surrounding environment still takes precedence:
+
+```sh
+WORK_BRANCH_PREFIX=rturnq
+```
+
+Optional: a `plan-usage` CLI on PATH enables the agent plan/quota usage panel.
+
+## Layout on disk
+
+- `~/work/<slug>-<id>/` — a workspace: one worktree per repo + generated
+  `AGENTS.md` (and `CLAUDE.md` symlink) encoding the conventions
+- `~/work/.cache/github.com/<owner>/<repo>.git` — shared bare-repo cache
+- `~/.local/share/work/work.db` — sqlite database (authoritative state)
+
+Terminals live in a dedicated tmux server (`tmux -L work`), kept alive by a
+transient systemd unit so app restarts never kill your sessions.

package/bin/work.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// work CLI — ships with the npm package (no dependencies; plain node).
+//
+//   work setup    install/refresh the background service (+ optional tunnel)
+//   work start    run the server in the foreground
+//   work update   upgrade the npm package and refresh the service
+//   work version  print the installed version
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+const distEntry = path.join(pkgRoot, "dist", "index.mjs");
+const appPort = process.env.WORK_APP_PORT || "7171";
+
+const log = (msg) => console.log(`==> ${msg}`);
+const warn = (msg) => console.warn(`warning: ${msg}`);
+const die = (msg) => {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+};
+const have = (cmd) =>
+  spawnSync(process.platform === "win32" ? "where" : "which", [cmd], {
+    stdio: "ignore",
+  }).status === 0;
+const sh = (cmd, args, opts = {}) =>
+  execFileSync(cmd, args, { stdio: "inherit", ...opts });
+
+const [, , command = "help", ...args] = process.argv;
+const yes = args.includes("--yes") || args.includes("-y");
+
+switch (command) {
+  case "start":
+    await start();
+    break;
+  case "setup":
+    await setup();
+    break;
+  case "update":
+    await update();
+    break;
+  case "version":
+  case "--version":
+  case "-v":
+    console.log(pkg.version);
+    break;
+  default:
+    console.log(
+      `work ${pkg.version}\n\nusage: work <setup|start|update|version>`,
+    );
+}
+
+async function start() {
+  if (!fs.existsSync(distEntry)) die(`missing ${distEntry}`);
+  process.env.PORT ||= appPort;
+  await import(distEntry);
+}
+
+async function setup() {
+  // Runtime tools. The curl installer normally provides these; a plain
+  // `npm i -g` user may be missing them.
+  for (const tool of ["git", "tmux"]) {
+    if (!have(tool)) die(`${tool} not found — install it and re-run (the curl installer does this automatically)`);
+  }
+
+  // Default toolset (mirrors DylanPiercey/start): gh for PR features plus
+  // the utilities agents reach for constantly. Static binaries via mise,
+  // each non-fatal, skipped when already on PATH.
+  if (have("mise")) {
+    const tools = [
+      "gh",
+      "ripgrep", // rg
+      "fd",
+      "jq",
+      "delta",
+      "ast-grep",
+      "hyperfine",
+      "fzf",
+      "bottom",
+      "pnpm",
+    ];
+    const binOf = { ripgrep: "rg", "ast-grep": "sg", bottom: "btm" };
+    for (const tool of tools) {
+      if (have(binOf[tool] || tool)) continue;
+      log(`installing ${tool} via mise`);
+      if (spawnSync("mise", ["use", "-g", "-y", `${tool}@latest`], { stdio: "inherit" }).status !== 0) {
+        warn(`${tool} install failed (non-fatal)`);
+      }
+    }
+  } else if (!have("gh")) {
+    warn("gh not found and mise unavailable — PR features need gh; install it and re-run");
+  }
+  if (have("gh") && spawnSync("gh", ["auth", "status"], { stdio: "ignore" }).status !== 0) {
+    if (process.env.GH_TOKEN || process.env.GITHUB_TOKEN) {
+      log("gh will use GH_TOKEN from the environment");
+    } else if (yes) {
+      warn("gh is not authenticated — run `gh auth login` later");
+    } else {
+      log("authenticating gh (GitHub PRs/clones)");
+      sh("gh", ["auth", "login"]);
+    }
+  }
+
+  // One-shot cleanups between versions.
+  const migrate = path.join(pkgRoot, "scripts", "migrate.mjs");
+  if (fs.existsSync(migrate)) {
+    spawnSync(process.execPath, [migrate], { stdio: "inherit" });
+  }
+
+  installService();
+  maybeTunnel();
+  log(`done — http://localhost:${appPort}`);
+}
+
+async function update() {
+  log("updating @dylanpiercey/work");
+  sh("npm", ["install", "-g", "@dylanpiercey/work@latest"]);
+  // Re-exec the (possibly new) CLI to finish with fresh code.
+  sh("work", ["setup", ...(yes ? ["--yes"] : [])]);
+}
+
+/** PATH baked into the service — it runs without a login shell. */
+function servicePath() {
+  const home = os.homedir();
+  return [
+    path.dirname(process.execPath),
+    `${home}/.local/share/mise/shims`,
+    `${home}/.local/bin`,
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+  ].join(":");
+}
+
+function serviceEnv() {
+  const env = { PATH: servicePath(), PORT: appPort };
+  for (const key of ["WORK_APP_PORT", "WORK_ROOT", "WORK_DATA_DIR", "WORK_ALLOWED_HOSTS", "WORK_BIND"]) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
+function installService() {
+  const cliPath = fileURLToPath(import.meta.url);
+  if (process.platform === "darwin") {
+    const plist = path.join(os.homedir(), "Library/LaunchAgents/dev.work.app.plist");
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.mkdirSync(path.join(os.homedir(), "Library/Logs"), { recursive: true });
+    const envXml = Object.entries(serviceEnv())
+      .map(([k, v]) => `    <key>${k}</key><string>${v}</string>`)
+      .join("\n");
+    fs.writeFileSync(
+      plist,
+      `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>dev.work.app</string>
+  <key>ProgramArguments</key>
+  <array><string>${process.execPath}</string><string>${cliPath}</string><string>start</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${os.homedir()}/Library/Logs/work.log</string>
+  <key>StandardErrorPath</key><string>${os.homedir()}/Library/Logs/work.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+</dict>
+</plist>
+`,
+    );
+    log("installing launchd agent");
+    const uid = process.getuid();
+    spawnSync("launchctl", ["bootout", `gui/${uid}/dev.work.app`], { stdio: "ignore" });
+    const boot = spawnSync("launchctl", ["bootstrap", `gui/${uid}`, plist], { stdio: "ignore" });
+    if (boot.status !== 0 && spawnSync("launchctl", ["load", "-w", plist], { stdio: "ignore" }).status !== 0) {
+      warn(`could not load the agent (no GUI launchd session?) — run from a local terminal: launchctl bootstrap gui/$UID ${plist}`);
+      warn("or start manually: work start");
+      return;
+    }
+    spawnSync("launchctl", ["kickstart", "-k", `gui/${uid}/dev.work.app`], { stdio: "ignore" });
+    log("manage with: launchctl {kickstart -k,print} gui/$UID/dev.work.app   (logs: ~/Library/Logs/work.log)");
+    return;
+  }
+
+  if (process.platform === "linux" && have("systemctl")) {
+    const unitDir = path.join(
+      process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
+      "systemd/user",
+    );
+    fs.mkdirSync(unitDir, { recursive: true });
+    const envLines = Object.entries(serviceEnv())
+      .map(([k, v]) => `Environment=${k}=${v}`)
+      .join("\n");
+    fs.writeFileSync(
+      path.join(unitDir, "work.service"),
+      `[Unit]
+Description=work — agentic dev workspace GUI
+
+[Service]
+ExecStart=${process.execPath} ${cliPath} start
+Restart=on-failure
+${envLines}
+
+[Install]
+WantedBy=default.target
+`,
+    );
+    log("installing systemd user service");
+    sh("systemctl", ["--user", "daemon-reload"]);
+    sh("systemctl", ["--user", "enable", "work.service"]);
+    sh("systemctl", ["--user", "restart", "work.service"]);
+    // Survive logout (best-effort; may need sudo on some systems).
+    spawnSync("loginctl", ["enable-linger", os.userInfo().username], { stdio: "ignore" });
+    log("manage with: systemctl --user {status,restart,stop} work.service");
+    return;
+  }
+
+  warn("no service manager found — start manually with: work start");
+}
+
+function maybeTunnel() {
+  if (yes || have("cloudflared")) return;
+  console.log(`
+To reach work from your phone or other devices, put it behind something
+that terminates TLS and authenticates — e.g. a Cloudflare Tunnel with
+Access (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
+pointing at http://localhost:${appPort}, or Tailscale. The server itself has
+no auth of its own.`);
+}