@monster-orange/den 0.2.3 → 0.2.4

package/src/shared/read-cache.ts

@@ -0,0 +1,77 @@
+/**
+ * A short-lived cache for the web server's repeated reads (manifests, the
+ * edge config, the derived graph), so a request does not re-stat and
+ * re-read the same files dozens of times, and polls a few seconds apart
+ * share one read.
+ *
+ * Off unless the web server enables it: a CLI command and the tests read
+ * fresh every time, as before. The server clears it on every mutating
+ * request, so a write made through the UI is seen by the very next read;
+ * an edit made outside the server (an editor, the CLI) is seen within the
+ * TTL. Values are cloned on the way out, so a caller that mutates its copy
+ * never changes what the next caller gets.
+ */
+
+let ttlMs = 0;
+const entries = new Map<string, { at: number; value: unknown }>();
+/** cachedReadStale's values: kept across a clear, only marked stale. */
+const stale = new Map<string, { at: number; value: unknown }>();
+const refreshing = new Set<string>();
+
+/** Turn the cache on (web server only). */
+export function enableReadCache(ms: number): void {
+  ttlMs = ms;
+}
+
+/** Drop every cached read (after a mutation, or in tests). */
+export function clearReadCache(): void {
+  entries.clear();
+  for (const e of stale.values()) e.at = 0;
+}
+
+function copy<T>(v: T): T {
+  return v !== null && typeof v === "object" ? structuredClone(v) : v;
+}
+
+/** `load()`'s value for `key`, reused for the TTL when the cache is on. */
+export function cachedRead<T>(key: string, load: () => T): T {
+  if (ttlMs <= 0) return load();
+  const hit = entries.get(key);
+  if (hit && Date.now() - hit.at < ttlMs) return copy(hit.value as T);
+  const value = load();
+  entries.set(key, { at: Date.now(), value });
+  return copy(value);
+}
+
+/**
+ * Like cachedRead, but past the TTL it still answers with the last value at
+ * once and recomputes after the current request (setImmediate), so no
+ * request waits on the recompute. For expensive, slow-changing results
+ * (the derived dependency graph) whose staleness only affects ordering.
+ */
+export function cachedReadStale<T>(
+  key: string,
+  maxAgeMs: number,
+  load: () => T,
+): T {
+  if (ttlMs <= 0) return load();
+  const hit = stale.get(key);
+  if (!hit) {
+    const value = load();
+    stale.set(key, { at: Date.now(), value });
+    return copy(value);
+  }
+  if (Date.now() - hit.at >= maxAgeMs && !refreshing.has(key)) {
+    refreshing.add(key);
+    setImmediate(() => {
+      try {
+        stale.set(key, { at: Date.now(), value: load() });
+      } catch {
+        /* keep the last good value */
+      } finally {
+        refreshing.delete(key);
+      }
+    });
+  }
+  return copy(hit.value as T);
+}

package/src/shared/stacks/status.ts

@@ -3,13 +3,18 @@
  * The CLI prints it; the web server serves it at /api/stacks (and through it
  * the MCP `stacks` tool).
  */
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { readCatalog } from "../environment-manager/catalog.js";
 import { readEdgeConfig } from "../edge/config.js";
 import { routeUrl } from "../edge/render.js";
 import {
   getFocusedWorkspaceName,
   getWorkspaceByName,
+  listWorkspaceServices,
 } from "../environment-manager/workspaces.js";
-import { readStacks } from "./config.js";
+import { readManifestStacks, readStacks } from "./config.js";
 import { projectName, stackWorkspace } from "./render.js";
 import { stackHealth, type StackContext } from "./runtime.js";
 
@@ -97,3 +102,106 @@ export function stackStatuses(
     return status;
   });
 }
+
+/** A running Compose project started from one of a workspace's repos. */
+export interface WorkspaceStack {
+  /** The Den stack name, or the project name for a stack the repo runs. */
+  name: string;
+  repo: string;
+  project: string;
+}
+
+/** A running Compose project and the directory it was started from. */
+export interface RunningProject {
+  project: string;
+  /** `com.docker.compose.project.working_dir`; "" when unlabelled. */
+  workingDir: string;
+}
+
+/**
+ * The Compose projects with running containers, from one `docker ps`; null
+ * when docker can't be asked (not installed, daemon down, too slow).
+ */
+export function runningComposeProjects(): RunningProject[] | null {
+  const r = spawnSync(
+    "docker",
+    [
+      "ps",
+      "--format",
+      '{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.project.working_dir"}}',
+    ],
+    { encoding: "utf-8", timeout: 5_000, stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (r.error || r.status !== 0) return null;
+  const seen = new Map<string, RunningProject>();
+  for (const line of (r.stdout ?? "").split("\n")) {
+    const [project = "", workingDir = ""] = line.trim().split("\t");
+    if (project && !seen.has(project))
+      seen.set(project, { project, workingDir: workingDir.trim() });
+  }
+  return [...seen.values()];
+}
+
+/** `p` and its realpath (compose may record either form). */
+function pathForms(p: string): string[] {
+  try {
+    const real = fs.realpathSync(p);
+    return real === p ? [p] : [p, real];
+  } catch {
+    return [p];
+  }
+}
+
+/**
+ * `workspace`'s running compose stacks: what `workspace deactivate` leaves
+ * up, since it releases only the daemons Den tracks. A project counts when
+ * it is a Den stack one of the workspace's repos declares (`compose:`, named
+ * by projectName), or when Compose started it from inside one of the
+ * workspace's checkouts (its working_dir label): the stacks a repo runs
+ * itself, e.g. from `make up`. Null when docker could not be asked.
+ */
+export function runningWorkspaceStacks(
+  workspace: string,
+  running: () => RunningProject[] | null = runningComposeProjects,
+): WorkspaceStack[] | null {
+  const ws = getWorkspaceByName(workspace);
+  if (!ws) return [];
+  const denStacks = new Map<string, { name: string; repo: string }>();
+  const checkouts: { repo: string; forms: string[] }[] = [];
+  try {
+    const { stackWorkspace: suffix } = resolveStackWorkspaces(workspace);
+    for (const s of Object.values(readManifestStacks(workspace)))
+      denStacks.set(projectName(s.name, suffix), {
+        name: s.name,
+        repo: s.repo,
+      });
+    const seen = new Set<string>();
+    for (const svc of listWorkspaceServices(ws.config, readCatalog(), ws.name))
+      if (svc.repoPath && !seen.has(svc.repoPath)) {
+        seen.add(svc.repoPath);
+        checkouts.push({ repo: svc.repoName, forms: pathForms(svc.repoPath) });
+      }
+  } catch {
+    return null; // an unreadable manifest or workspace name: can't tell
+  }
+  if (denStacks.size === 0 && checkouts.length === 0) return [];
+  const up = running();
+  if (!up) return null;
+  const inside = (dir: string, root: string): boolean =>
+    dir === root || dir.startsWith(`${root}${path.sep}`);
+  const out: WorkspaceStack[] = [];
+  for (const { project, workingDir } of up) {
+    const den = denStacks.get(project);
+    if (den) {
+      out.push({ ...den, project });
+      continue;
+    }
+    if (!workingDir) continue;
+    const dirs = pathForms(workingDir);
+    const owner = checkouts.find((c) =>
+      c.forms.some((root) => dirs.some((d) => inside(d, root))),
+    );
+    if (owner) out.push({ name: project, repo: owner.repo, project });
+  }
+  return out;
+}

package/src/ui/cli/index.ts

@@ -5,6 +5,11 @@
  * Main entry point for the interactive CLI
  */
 
+import { composeStacksNotice } from "./workspace-notes.js";
+import {
+  runningComposeProjects,
+  runningWorkspaceStacks,
+} from "../../shared/stacks/status.js";
 import { isNamedTarget } from "./named-target.js";
 import chalk from "chalk";
 import oraSpinner from "ora";
@@ -46,7 +51,9 @@ import {
   isWorkspaceActive,
   activateWorkspace,
   deactivateWorkspace,
+  getActiveWorkspaces,
   setActiveWorkspace,
+  setFocusedWorkspace,
   createWorkspace,
   deleteWorkspaceConfig,
   parseAddress,
@@ -195,6 +202,58 @@ const DEN_HELP_DESCRIPTION = `  ${product().title} - local-first test, service,
  * Concise `<command> -h` help for commands without a dedicated help renderer.
  * Flag-heavy commands (up, graph, use-local, use-managed) have richer handlers.
  */
+/** `workspace` subcommands, for `workspace --help` and `workspace <sub> --help`. */
+const WORKSPACE_SUBCOMMANDS: {
+  name: string;
+  usage: string;
+  lines: string[];
+}[] = [
+  {
+    name: "list",
+    usage: "list",
+    lines: ["every workspace, the active set and the focus"],
+  },
+  {
+    name: "activate",
+    usage: "activate <n>",
+    lines: ["add a workspace to the active set"],
+  },
+  {
+    name: "deactivate",
+    usage: "deactivate <n>",
+    lines: [
+      "remove it from the active set and stop the services",
+      "only it owns. Only services {cli} tracks: compose",
+      "stacks keep running; stop them with `{cli} down <repo>`",
+    ],
+  },
+  {
+    name: "focus",
+    usage: "focus <n>",
+    lines: ["make an active workspace the default for commands"],
+  },
+  {
+    name: "use",
+    usage: "use <n>",
+    lines: ["activate and focus a workspace"],
+  },
+  {
+    name: "create",
+    usage: "create [n]",
+    lines: ["create an empty workspace"],
+  },
+  {
+    name: "delete",
+    usage: "delete <n>",
+    lines: ["delete a workspace (and its directory)"],
+  },
+  {
+    name: "code",
+    usage: "code [n]",
+    lines: ["open it in your editor (VS Code: a .code-workspace)"],
+  },
+];
+
 const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   down: {
     usage: "down [repo] [flags]",
@@ -252,8 +311,16 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     lines: ["Check managed repos for upstream updates and offer to pull."],
   },
   workspace: {
-    usage: "workspace <list|use|create|delete|code> [name]",
-    lines: ["Manage workspaces (named sets of services + their modes)."],
+    usage: `workspace <${WORKSPACE_SUBCOMMANDS.map((c) => c.name).join("|")}> [name]`,
+    lines: [
+      "Manage workspaces (named sets of services + their modes).",
+      "",
+      ...WORKSPACE_SUBCOMMANDS.flatMap((c) =>
+        c.lines.map(
+          (line, i) => `  ${(i === 0 ? c.usage : "").padEnd(16)}  ${line}`,
+        ),
+      ),
+    ],
   },
   run: {
     usage: "run [options]",
@@ -583,7 +650,7 @@ class DenCLI {
       !["-h", "--help", "-v", "--version"].includes(command) &&
       (ownArgs.includes("-h") || ownArgs.includes("--help"))
     ) {
-      this.printCommandHelp(command);
+      this.printCommandHelp(command, ownArgs[1]);
       return;
     }
 
@@ -2375,7 +2442,19 @@ class DenCLI {
   }
 
   /** Help for `<command> -h`: dedicated renderer for flag-heavy commands, else the table. */
-  private printCommandHelp(command: string): void {
+  private printCommandHelp(command: string, sub?: string): void {
+    // `workspace <sub> --help`: that subcommand only.
+    const wsSub =
+      command === "workspace"
+        ? WORKSPACE_SUBCOMMANDS.find((c) => c.name === sub)
+        : undefined;
+    if (wsSub) {
+      console.log(`\n  ${product().cli} workspace ${wsSub.usage}\n`);
+      for (const line of wsSub.lines)
+        console.log(`  ${line.replaceAll("{cli}", product().cli)}`);
+      console.log();
+      return;
+    }
     switch (command) {
       case "up":
         return this.printUpHelp();
@@ -2398,7 +2477,8 @@ class DenCLI {
       return;
     }
     console.log(`\n  ${product().cli} ${entry.usage}\n`);
-    for (const line of entry.lines) console.log(`  ${line}`);
+    for (const line of entry.lines)
+      console.log(`  ${line.replaceAll("{cli}", product().cli)}`.trimEnd());
     console.log();
   }
 
@@ -3501,9 +3581,36 @@ class DenCLI {
             }
           }
         }
+        // Deactivate releases tracked daemons only; say what it left up.
+        // One docker ps for this workspace and every other active one.
+        let up: ReturnType<typeof runningComposeProjects> | undefined;
+        const running = () =>
+          up === undefined ? (up = runningComposeProjects()) : up;
+        const stacks = runningWorkspaceStacks(name, running);
+        const heldBy = new Map<string, string[]>();
+        if (stacks?.length)
+          for (const other of getActiveWorkspaces())
+            for (const s of runningWorkspaceStacks(other, running) ?? [])
+              heldBy.set(s.project, [...(heldBy.get(s.project) ?? []), other]);
+        const stacksNote = composeStacksNotice(product().cli, stacks, heldBy);
+        if (stacksNote) console.log(chalk.yellow(`    ${stacksNote}`));
         console.log("");
         break;
       }
+      case "focus": {
+        const name = args[1];
+        if (!name) {
+          console.log(
+            chalk.red(`Usage: ${product().cli} workspace focus <name>`),
+          );
+          return;
+        }
+        setFocusedWorkspace(name);
+        console.log(
+          chalk.green(`\n  ✓ Focused workspace: ${chalk.bold(name)}\n`),
+        );
+        break;
+      }
       case "use": {
         const name = args[1];
         if (!name) {
@@ -3611,7 +3718,7 @@ class DenCLI {
       default:
         console.log(
           chalk.gray(
-            `Usage: ${product().cli} workspace <list|activate|deactivate|use|create|delete|code> [name]`,
+            `Usage: ${product().cli} workspace <list|activate|deactivate|focus|use|create|delete|code> [name]`,
           ),
         );
     }
@@ -3871,7 +3978,6 @@ class DenCLI {
       "  service install      Run the web UI as a launchd service (status, print, uninstall)",
     );
     console.log();
-    console.log("  workspace list       List workspaces");
     console.log(
       "  workspace list           List workspaces (active set + focus)",
     );
@@ -3879,11 +3985,14 @@ class DenCLI {
     console.log(
       "  workspace deactivate <n> Remove workspace from the active set",
     );
+    console.log(
+      "  workspace focus <n>      Focus an active workspace (the default)",
+    );
     console.log("  workspace use <n>        Activate and focus a workspace");
-    console.log("  workspace create [n] Create a new workspace");
-    console.log("  workspace delete <n> Delete a workspace");
+    console.log("  workspace create [n]     Create a new workspace");
+    console.log("  workspace delete <n>     Delete a workspace");
     console.log(
-      "  workspace code [n]   Open workspace in VS Code (generates .code-workspace)",
+      "  workspace code [n]       Open workspace in VS Code (generates .code-workspace)",
     );
     console.log("\nTest commands:");
     console.log(

package/src/ui/cli/mcp-connect.ts

@@ -25,7 +25,7 @@ import { product } from "../../shared/product.js";
 import { getDistRoot } from "../../shared/paths.js";
 import { readWebPort } from "../../shared/edge/config.js";
 import { DEFAULT_PORT } from "../../shared/constants.js";
-import { readMcpConfig } from "../../shared/den-config.js";
+import { readDenConfig, readMcpConfig } from "../../shared/den-config.js";
 
 export const MCP_CONNECT_SUBCOMMANDS = [
   "connect",
@@ -199,6 +199,78 @@ function status(
     : chalk.gray("not connected");
 }
 
+/** How long `mcp connect` waits for /api/server-info before giving up. */
+export const WEB_PROBE_TIMEOUT_MS = 1500;
+
+/** What a probe of the web server's /api/server-info found. */
+export type WebProbe =
+  | { kind: "up"; version?: string }
+  /** Something accepted the connection but sent no answer in time. */
+  | { kind: "timeout" }
+  /** Nothing answered: connection refused, or not the web server. */
+  | { kind: "down" };
+
+export async function probeWebServer(
+  url: string,
+  timeoutMs: number = WEB_PROBE_TIMEOUT_MS,
+  fetchImpl: typeof fetch = fetch,
+): Promise<WebProbe> {
+  try {
+    const r = await fetchImpl(`${url}/api/server-info`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const info = (await r.json()) as { version?: string };
+    return { kind: "up", version: info.version };
+  } catch (e) {
+    return (e as Error).name === "TimeoutError"
+      ? { kind: "timeout" }
+      : { kind: "down" };
+  }
+}
+
+/** Whether the org config runs the web UI as a service (`web.service`). */
+function webRunsAsService(): boolean {
+  try {
+    return readDenConfig().web?.service !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The status line for a probe. A server that is up but slow is "not
+ * answering", never "not running"; and when the web UI runs as a service
+ * (`web.service`), the advice is the service's status, not `web up`.
+ */
+export function webServerMessage(
+  probe: WebProbe,
+  url: string,
+  opts: { cli: string; asService: boolean; timeoutMs?: number },
+): string {
+  if (probe.kind === "up")
+    return (
+      chalk.green(`web server up at ${url}`) +
+      (probe.version ? chalk.gray(` (Den ${probe.version})`) : "")
+    );
+  const svc = `\`${opts.cli} service status\``;
+  if (probe.kind === "timeout") {
+    const secs = (opts.timeoutMs ?? WEB_PROBE_TIMEOUT_MS) / 1000;
+    return chalk.yellow(
+      `web server at ${url} is not answering within ${secs}s (busy or stuck): ` +
+        `agents' reads wait on it too; if it stays slow, ` +
+        (opts.asService
+          ? `check ${svc}`
+          : `restart it with \`${opts.cli} web restart\``),
+    );
+  }
+  return chalk.yellow(
+    `web server not running at ${url}: agents get read errors until ` +
+      (opts.asService
+        ? `the service is up (check ${svc})`
+        : `\`${opts.cli} web up\``),
+  );
+}
+
 async function webServerLine(port?: number): Promise<string> {
   let p = port;
   if (p === undefined) {
@@ -209,20 +281,10 @@ async function webServerLine(port?: number): Promise<string> {
     }
   }
   const url = `http://localhost:${p}`;
-  try {
-    const r = await fetch(`${url}/api/server-info`, {
-      signal: AbortSignal.timeout(1500),
-    });
-    const info = (await r.json()) as { version?: string };
-    return (
-      chalk.green(`web server up at ${url}`) +
-      (info.version ? chalk.gray(` (Den ${info.version})`) : "")
-    );
-  } catch {
-    return chalk.yellow(
-      `web server not running at ${url}: agents get read errors until \`${product().cli} web up\``,
-    );
-  }
+  return webServerMessage(await probeWebServer(url), url, {
+    cli: product().cli,
+    asService: webRunsAsService(),
+  });
 }
 
 function usage(): string {

package/src/ui/cli/workspace-notes.ts

@@ -0,0 +1,43 @@
+/**
+ * What `<cli> workspace deactivate` says about what it leaves running: it
+ * releases only the daemons Den tracks, so a compose stack started from one
+ * of the workspace's repos keeps running until `<cli> down <repo>`. A stack
+ * another active workspace still holds is named as in use, never with a
+ * command that would stop it.
+ */
+import type { WorkspaceStack } from "../../shared/stacks/status.js";
+
+/**
+ * The note for `stacks`: the running ones (null when docker could not be
+ * asked, so it is said generically), or nothing when none is running.
+ * `heldBy` maps a Compose project to the other active workspaces that hold
+ * it.
+ */
+export function composeStacksNotice(
+  cli: string,
+  stacks: WorkspaceStack[] | null,
+  heldBy: ReadonlyMap<string, string[]> = new Map(),
+): string | null {
+  if (stacks === null)
+    return `compose stacks keep running: stop them with \`${cli} down <repo>\``;
+  if (stacks.length === 0) return null;
+  const held = stacks.filter((s) => heldBy.get(s.project)?.length);
+  // `down <repo>` stops all of a repo's stacks: never suggest it for a repo
+  // with a stack still in use.
+  const heldRepos = new Set(held.map((s) => s.repo));
+  const free = stacks.filter((s) => !heldRepos.has(s.repo));
+  const inUse = held.map(
+    (s) => `${s.project} (still in ${heldBy.get(s.project)!.join(", ")})`,
+  );
+  const parts: string[] = [];
+  if (free.length) {
+    const repos = [...new Set(free.map((s) => s.repo))];
+    parts.push(
+      `compose stacks keep running (${free.map((s) => s.project).join(", ")}): ` +
+        `stop them with ${repos.map((r) => `\`${cli} down ${r}\``).join(", ")}`,
+    );
+  }
+  if (inUse.length)
+    parts.push(`in use by another workspace: ${inUse.join(", ")}`);
+  return parts.join("; ");
+}

package/src/ui/server/graph-order.ts

@@ -0,0 +1,22 @@
+/**
+ * The dependency graph's top-down repo order (entry repo first, infra last),
+ * which the health row and /api/services rank by.
+ *
+ * Deriving the graph walks every repo's sources (fingerprints, scans), so it
+ * is far too slow to redo on each 5s poll. In the web server it is kept for
+ * 30s and then recomputed after the request that noticed, never inside it
+ * (read-cache.ts); a stale order only means a briefly stale sort.
+ */
+import { deriveGraph } from "../../shared/environment-manager/derivation/derive-graph.js";
+import { orderForDown } from "../../shared/environment-manager/derivation/derived-up.js";
+import { cachedReadStale } from "../../shared/read-cache.js";
+
+const GRAPH_ORDER_MAX_AGE_MS = 30_000;
+
+export function graphOrder(workspace: string | undefined): string[] {
+  return cachedReadStale(
+    `graph-order:${workspace ?? ""}`,
+    GRAPH_ORDER_MAX_AGE_MS,
+    () => orderForDown(deriveGraph({ scope: "all", workspace })),
+  );
+}