@zuzuucodes/cli 1.3.0 → 1.3.1

package/bin/zuzuu.mjs

@@ -61,7 +61,9 @@ function help() {
 usage: zuzuu <command> [options]
 
   code [dir]                launch OpenCode as the bundled default host (faculty home + capture + gate + digest)
-  web [dir]                 launch the visual workbench (installs @zuzuucodes/web on demand)
+  web [dir] [--stop|--status]
+                            launch the visual workbench (reuses a running one;
+                            --stop ends it, --status reports it)
   init                      scaffold the faculty home (.zuzuu/) — git-style, idempotent
   status                    detected hosts + recorded sessions
   capture [--host NAME]     capture a session → .zuzuu/.traces + .zuzuu/sessions.json
@@ -108,7 +110,7 @@ const args = parseArgs(rest);
 
 switch (cmd) {
   case 'code': process.exit(code(args)); break;
-  case 'web': web(args); break;
+  case 'web': await web(args); break;
   case 'init': init(args); break;
   case 'remember': remember(args); break;
   case 'recall': await recall(args); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "private": false,
   "publishConfig": {
     "access": "public"

package/web-app/dist/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import crypto from "node:crypto";
 import { WebcodeServer } from "./server.js";
 import { addRecent } from "./config.js";
+import { writeInstanceFile, removeInstanceFile } from "./instance-file.js";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_PORT = 7770;
 function parseArgs(argv) {
@@ -147,14 +148,32 @@ async function main() {
         console.log(`\n  zuzuu-web v${pkg.version}`);
         console.log(`  workspace  ${root}`);
         console.log(`  url        ${url}\n`);
+        // Singleton contract: record this instance so `zuzuu web` can reuse it
+        // instead of spawning a duplicate (never in hosted mode; never fatal).
+        if (!hosted) {
+            writeInstanceFile({
+                root,
+                port: boundPort,
+                pid: process.pid,
+                token,
+                startedAt: new Date().toISOString(),
+                version: pkg.version,
+            });
+        }
         if (args.open)
             openBrowser(url);
     });
     const shutdown = () => {
+        if (!hosted)
+            removeInstanceFile(root);
         server.stop();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
+    process.on("exit", () => {
+        if (!hosted)
+            removeInstanceFile(root); // best-effort; idempotent after shutdown()
+    });
 }
 void main();

package/web-app/dist/instance-file.js

@@ -0,0 +1,62 @@
+// Per-workspace daemon instance state — the singleton contract with `zuzuu web`.
+//
+// After a successful listen the daemon writes
+//   ~/.webcode/instances/<sha256(realpath-root).slice(0,16)>.json
+// and removes it on clean shutdown. The zuzuu CLI computes the same path for a
+// workspace to discover (and reuse / stop) an already-running daemon instead of
+// spawning a fresh one — so the port + token stay stable across `zuzuu web` runs.
+//
+// Security note: the file contains the auth token. That's acceptable here —
+// it's 0600 in the user's own home directory, and the same token already
+// appears in the daemon's own stdout URL. Hosted mode never writes this file.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function instancesDir() {
+    return path.join(os.homedir(), ".webcode", "instances");
+}
+/** Deterministic per-workspace file path. `root` must already be realpath'd. */
+export function instancePath(root, dir = instancesDir()) {
+    const id = crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+    return path.join(dir, `${id}.json`);
+}
+/** Write the instance file (0600). Never throws — a failed write only costs reuse. */
+export function writeInstanceFile(info, dir = instancesDir()) {
+    const file = instancePath(info.root, dir);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(info, null, 2) + "\n", { mode: 0o600 });
+        fs.chmodSync(file, 0o600); // mode option only applies on create; enforce on overwrite too
+        return file;
+    }
+    catch (err) {
+        console.warn(`zuzuu-web: could not write instance state (${String(err)}) — continuing without it`);
+        return null;
+    }
+}
+/** Best-effort read; null on missing/corrupt. */
+export function readInstanceFile(root, dir = instancesDir()) {
+    try {
+        return JSON.parse(fs.readFileSync(instancePath(root, dir), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort removal on shutdown. Only removes the file if it still belongs
+ * to `pid` — if another daemon raced us and overwrote it, leave theirs alone.
+ */
+export function removeInstanceFile(root, pid = process.pid, dir = instancesDir()) {
+    const file = instancePath(root, dir);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed.pid === "number" && parsed.pid !== pid)
+            return; // not ours anymore
+        fs.unlinkSync(file);
+    }
+    catch {
+        /* already gone or unreadable — nothing to do */
+    }
+}

package/zuzuu/commands/web.mjs

@@ -11,14 +11,27 @@
 // the workbench, never the CLI. `--omit=optional` installs skip the deps; this
 // command then explains how to repair.
 //
+// Singleton-per-workspace (2026-06-12): the daemon records itself in
+// ~/.webcode/instances/<sha256(realpath-root).slice(0,16)>.json after listen
+// and removes it on clean shutdown (daemon src/instance-file.ts — the path
+// scheme here MUST stay in sync with it). Before spawning we check that file:
+// a live instance (pid alive + HTTP listener answering) is REUSED — same port,
+// same token, old browser tabs keep working; a stale file is deleted and we
+// spawn fresh. `--stop` / `--status` manage the running instance.
+// (The file carries the auth token: 0600, user's own machine, and the token
+// already appears in the daemon's stdout — acceptable.)
+//
 // Resolution order:
 //   1. the bundled web-app/dist next to this package (installed OR repo after build:web)
 //   2. the nested dev project's built daemon (web/packages/daemon, repo checkout)
 //   3. a standalone `zuzuu-web` on PATH (legacy/manual installs)
 //   4. none → repair hint (reinstall, or `npm run build:web` in a checkout)
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, unlinkSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -45,25 +58,108 @@ const realLaunch = ({ cwd, entryScript }) => {
   if (entryScript) spawn(process.execPath, [entryScript, cwd], { detached: true, stdio: 'ignore' }).unref();
   else spawn('zuzuu-web', [cwd], { detached: true, stdio: 'ignore' }).unref();
 };
+// Same scheme as the daemon's instance-file.ts: sha256 of the realpath'd root.
+const realInstancePathFor = (dir) => {
+  let real = dir;
+  try { real = realpathSync(dir); } catch { /* missing dir → daemon will refuse anyway */ }
+  const id = createHash('sha256').update(real).digest('hex').slice(0, 16);
+  return join(homedir(), '.webcode', 'instances', `${id}.json`);
+};
+const realReadInstance = (file) => {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+};
+const realRemoveFile = (file) => { try { unlinkSync(file); } catch { /* gone already */ } };
+const realPidAlive = (pid) => {
+  try { process.kill(pid, 0); return true; }
+  catch (err) { return err?.code === 'EPERM'; } // EPERM = alive, just not ours
+};
+const realKillPid = (pid, signal) => { try { process.kill(pid, signal); } catch { /* gone */ } };
+// Connectivity probe only — ANY HTTP answer (even 401) means a listener is there.
+const realProbe = (port) => new Promise((done) => {
+  const req = http.get({ host: '127.0.0.1', port, path: '/api/health', timeout: 1000 }, (res) => {
+    res.resume();
+    done(true);
+  });
+  req.on('timeout', () => { req.destroy(); done(false); });
+  req.on('error', () => done(false));
+});
+const realOpenBrowser = (url) => { // fail-soft: a missing opener never breaks the command
+  try {
+    const cmd = process.platform === 'darwin' ? 'open'
+      : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+  } catch { /* ignore */ }
+};
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const urlOf = (inst) => `http://127.0.0.1:${inst.port}/?token=${inst.token}`;
 
 /**
- * `zuzuu web [dir]`
- * Launch the visual workbench for the given directory (default: cwd).
+ * `zuzuu web [dir] [--stop|--status]`
+ * Launch the visual workbench for the given directory (default: cwd) —
+ * reusing an already-running daemon for that workspace when there is one.
  * Bundled-first; never installs anything — the workbench ships in this package.
  */
-export function web(args = {}, deps = {}) {
+export async function web(args = {}, deps = {}) {
   const d = {
     resolveBundled: realResolveBundled,
     detectPath: realDetectPath,
     launch: realLaunch,
+    instancePathFor: realInstancePathFor,
+    readInstance: realReadInstance,
+    removeFile: realRemoveFile,
+    pidAlive: realPidAlive,
+    killPid: realKillPid,
+    probe: realProbe,
+    openBrowser: realOpenBrowser,
+    sleep: realSleep,
     log: (...m) => console.log(...m),
     ...deps,
   };
 
-  // 1. resolve the target directory
+  // 1. resolve the target directory + its instance state
   const dir = args._?.[0] ? resolve(String(args._[0])) : process.cwd();
+  const instanceFile = d.instancePathFor(dir);
+  const inst = d.readInstance(instanceFile);
+  const isAlive = async (i) =>
+    !!(i && Number.isInteger(i.pid) && d.pidAlive(i.pid) && await d.probe(i.port));
+
+  // --stop: terminate the running daemon for this workspace
+  if (args.stop) {
+    if (!inst) { d.log(`no workbench running for ${dir}`); return; }
+    if (d.pidAlive(inst.pid)) {
+      d.killPid(inst.pid, 'SIGTERM');
+      for (let i = 0; i < 15 && d.pidAlive(inst.pid); i++) await d.sleep(200); // ~3s grace
+      if (d.pidAlive(inst.pid)) d.log(`workbench (pid ${inst.pid}) hasn't exited yet — still shutting down.`);
+      else d.log(`stopped workbench for ${dir} (pid ${inst.pid})`);
+    } else {
+      d.log(`workbench for ${dir} was not running — cleaned up stale state.`);
+    }
+    d.removeFile(instanceFile); // daemon removes it itself on SIGTERM; this is belt-and-braces
+    return;
+  }
 
-  // 2. find the workbench: bundled → PATH → repair hint
+  // --status: report without side effects
+  if (args.status) {
+    if (await isAlive(inst)) {
+      d.log(`workbench running for ${dir}`);
+      d.log(`  pid ${inst.pid} → ${urlOf(inst)}`);
+    } else {
+      d.log(`no workbench running for ${dir}`);
+    }
+    return;
+  }
+
+  // 2. reuse a live instance: same port + token, old tabs stay valid
+  if (await isAlive(inst)) {
+    d.log(`workbench already running for ${dir}`);
+    d.log(`  → ${urlOf(inst)}`);
+    d.openBrowser(urlOf(inst));
+    return;
+  }
+  if (inst) d.removeFile(instanceFile); // stale (dead pid / no listener) → spawn fresh
+
+  // 3. find the workbench: bundled → PATH → repair hint
   const entryScript = d.resolveBundled();
   if (!entryScript && !d.detectPath()) {
     d.log('the workbench is not available in this install.');
@@ -72,8 +168,17 @@ export function web(args = {}, deps = {}) {
     return;
   }
 
-  // 3. launch — the workbench opens the browser and prints its URL
+  // 4. launch — the daemon opens the browser itself on fresh boot, so we only
+  // wait for its instance file to surface the URL here (don't double-open).
   d.log(`zuzuu web → launching visual workbench in ${dir} …`);
-  d.log('  it will open your browser and print its URL.');
   d.launch({ cwd: dir, entryScript });
+  for (let i = 0; i < 30; i++) { // ~6s
+    await d.sleep(200);
+    const fresh = d.readInstance(instanceFile);
+    if (fresh && d.pidAlive(fresh.pid)) {
+      d.log(`  → ${urlOf(fresh)}`);
+      return;
+    }
+  }
+  d.log('  it will open your browser and print its URL.');
 }