@monster-orange/den 0.2.7 → 0.3.0

package/src/ui/cli/index.ts

@@ -11,6 +11,7 @@ import {
   runningWorkspaceStacks,
 } from "../../shared/stacks/status.js";
 import { isNamedTarget } from "./named-target.js";
+import { isNotice, printNotice } from "./notice.js";
 import chalk from "chalk";
 import { noun, plural } from "../../shared/plural.js";
 // Spinners: progress on stderr (a terminal) or stdout (piped); plain lines
@@ -32,10 +33,12 @@ import { moduleScanner } from "../../shared/test-discovery/module-scanner.js";
 import { resolvePerformanceModules } from "./module-selection.js";
 import {
   readCatalog,
-  resolveRepoGhSlug,
+  needsGhRepair,
+  resolveRepoCloneSource,
   upsertCatalogEntry,
 } from "../../shared/environment-manager/catalog.js";
 import { seedSecretsFromSibling } from "../../shared/environment-manager/secrets-check.js";
+import { upNeedsTarget } from "./up-args.js";
 import {
   readWorkspacesFile,
   writeWorkspacesFile,
@@ -56,6 +59,13 @@ import {
   DEN_SERVICES_DIR,
   DEN_WORKSPACES_DIR,
 } from "../../shared/environment-manager/workspaces.js";
+import {
+  ownersSuffix,
+  parseScope,
+  scopeLine,
+  scopeView,
+  takeScopeFlag,
+} from "../../shared/environment-manager/scope.js";
 import {
   deleteWorkspaceDirectory,
   checkBehindCount,
@@ -68,9 +78,11 @@ import {
   markSetupSucceeded,
   fetchAndFastForward,
 } from "../../shared/environment-manager/workspace-manager.js";
+import { stackNamespaceRows } from "../../shared/stacks/namespace.js";
 import {
   runServiceCommand,
   claimHealthyService,
+  daemonsOutsideWorkspaces,
   getWorkspaceServices,
   ensureDaemonRegistryLoaded,
   hasRunningOpctlContainers,
@@ -102,13 +114,18 @@ import { waitForReady } from "../../shared/environment-manager/readiness.js";
 import {
   canonicalServiceAddress,
   previewServiceCommand,
+  previewUpSettle,
   previewServiceSecretEnv,
   prepareServiceSecretEnv,
   resolveService,
+  type DownOutcome,
   type ServiceCommandPreview,
 } from "../../shared/environment-manager/service-runner.js";
 import { getGitHubCoords } from "../../shared/smoke/git-remote.js";
+import { isConfigError } from "../../shared/config-error.js";
 import {
+  assertDenConfigValid,
+  waiveInvalidOrgs,
   getReposRoot,
   mergeUserConfig,
   readDenConfig,
@@ -123,6 +140,11 @@ import {
   deriveStartTargets,
 } from "../../shared/environment-manager/derivation/derived-up.js";
 import type { DerivedGraph } from "../../shared/environment-manager/derivation/types.js";
+import {
+  repoOfAddress,
+  resolveUpTargets,
+  type UpTargets,
+} from "../../shared/environment-manager/up-targets.js";
 import { loadAliasResolver } from "../../shared/environment-manager/derivation/load-alias.js";
 import {
   cmdApps,
@@ -170,8 +192,11 @@ import {
 import { cleanupStaleTabs } from "../../shared/cli-tabs.js";
 import { cmdConfig } from "./config-command.js";
 import { cmdEdge } from "./edge-command.js";
+import { cmdDoctor } from "./doctor-command.js";
 import { cmdService } from "./service-command.js";
 import { cmdStack } from "./stack-command.js";
+import { cmdTheme } from "./theme-command.js";
+import { cmdPlugin } from "./plugin-command.js";
 import {
   cmdOrg,
   orgFlag,
@@ -191,6 +216,7 @@ import { cmdGraph } from "./graph-command.js";
 import { resolveLogsTarget, tailServiceLogs } from "./logs-command.js";
 import {
   parseCliArgs,
+  takeWorkspaceFlags,
   unknownCommandFlags,
   workspaceFlagRequiresActive,
   type ParsedCliArgs,
@@ -205,6 +231,9 @@ import {
   formatHealthDot,
   formatHealthLabel,
   formatHealthReason,
+  formatRollupLabel,
+  healthReasonText,
+  rollupReasonText,
 } from "./health-display.js";
 import { DEN_BANNER_LINES, DEN_DIVIDER } from "../../shared/banner.js";
 
@@ -296,9 +325,12 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     ],
   },
   status: {
-    usage: "status [-A <app>]",
+    usage: "status [-A <app>] [--scope <all|workspace>] [--verbose]",
     lines: [
-      "Show service health for the active workspace (or one application).",
+      "Show service health for what is in view: every active workspace by",
+      "default (the web UI's scope), or --scope <workspace> for one. A",
+      "service several workspaces share is listed once, with its owners.",
+      "--verbose (or --all) shows one row per service instead of per repo.",
     ],
   },
   logs: {
@@ -315,15 +347,26 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     lines: ["List all registered services in the catalog."],
   },
   register: {
-    usage: "register [path] [--org <id>]",
+    usage: "register [path] [-w <workspace>] [--org <id>]",
     lines: [
       "With a path: add that checkout (dev-managed) under its manifest name.",
       "Without one: pick the repo interactively. A managed clone is picked",
       "from the focused workspace's org; --org <id> picks from another.",
+      "-w writes that workspace (active or not) and leaves focus alone.",
+    ],
+  },
+  relocate: {
+    usage: "relocate <repo> <path> [--dry-run] [--force] [-w <workspace>]",
+    lines: [
+      "Point every workspace's dev-managed entries for <repo> at <path>.",
+      "Refuses a path that is missing, holds a different repo, or has",
+      "neither a manifest nor a remote naming this one (unless --force).",
+      "-w limits it to that workspace; focus never changes.",
     ],
   },
   setup: {
-    usage: "setup [service...] [--force|-f] [--plan]",
+    usage:
+      "setup [service...] [--force|-f] [--plan [-w <workspace>]... [--all-active]]",
     lines: [
       "Run 'make setup' once per system (clones missing managed repos first).",
       "Default targets MANAGED clones only — setup's codegen/installs",
@@ -331,6 +374,8 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
       "--force (-f) includes dev-managed repos; naming a service always works.",
       "--plan prints each repo's org and clone URL and stops: nothing is",
       "cloned, seeded or written (on a fresh machine: the blueprint's plan).",
+      "It plans the focused workspace; -w <workspace> (repeatable) plans those,",
+      "--all-active every active one. Repos only other workspaces hold are named.",
     ],
   },
   org: {
@@ -409,7 +454,33 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   edge: {
     usage: "edge [up|down|status|trust|untrust|routes]",
     lines: [
-      "This org's HTTPS edge: own CA + cert, routes at <name>.<edge.domain>.",
+      "This org's edge: routes at <name>.<edge.domain>, TLS as edge.tls says",
+      "(none | mkcert | files). trust/untrust exist only under mkcert.",
+    ],
+  },
+  doctor: {
+    usage: "doctor",
+    lines: [
+      "Each strategy kind (secrets, tls): the one selected, whether it was implicit,",
+      "and whether it can work here (a PATH check; nothing is run or prompted).",
+    ],
+  },
+  plugin: {
+    usage:
+      "plugin [list] | validate [dir] | add <repo>[/<subpath>]@<ref> [--track] [--yes] | update <id> @<ref> | remove <id>",
+    lines: [
+      "Plugins (den.plugin/v1) in plugins/<id>/: local (the distribution's own, no lock entry)",
+      "or added (vendored at an exact ref, pinned in plugins.lock.json). list checks each",
+      "against the lock; validate checks every manifest. add refuses file:// sources.",
+    ],
+  },
+  theme: {
+    usage:
+      "theme [list] | validate [dir] | new <id> | add <repo>[/<subpath>]@<ref> | remove <id>",
+    lines: [
+      "Web UI themes (den.theme/v1). add fetches one at an exact ref, validates it",
+      "(schema, contrast in both modes, files) and vendors it into plugins/<id>/",
+      "with a plugins.lock.json entry; commit both. list checks them against the lock.",
     ],
   },
   mcp: {
@@ -430,7 +501,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   "local-dev": {
     usage: "local-dev [on|off]",
     lines: [
-      "Toggle the local-dev experience (web Local Dev section + service mgmt).",
+      "Toggle the local-dev experience (web Workspaces page + service mgmt).",
     ],
   },
   menu: {
@@ -458,6 +529,7 @@ function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
 const TELEMETRY_COMMANDS = new Set<string>([
   "run",
   "view-results",
+  "down",
   "menu",
   "web",
   "up",
@@ -468,6 +540,7 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "services",
   "graph",
   "register",
+  "relocate",
   "use-local",
   `use-managed`,
   "setup",
@@ -480,13 +553,40 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "local-dev",
   "config",
   "edge",
+  "doctor",
   "stack",
   "apps",
   "applications",
   "mcp",
   "service",
+  "theme",
+  "plugin",
+]);
+
+/**
+ * Commands that run with a config that fails validation: the web and MCP
+ * servers (each route or tool reports it), and those that read neither orgs,
+ * the catalog nor clones (manifest validate, create, the per-engineer
+ * config and local-dev toggles, saved results), and `down` (0.3.0-dev.40:
+ * stopping is never stranded by a config that fails; it stops from the
+ * daemon records and compose projects, reading no org data). Every other
+ * registered command checks the config first.
+ */
+const CONFIG_FREE_COMMANDS = new Set<string>([
+  "web",
+  "mcp",
+  "validate",
+  "create",
+  "config",
+  "local-dev",
+  "view-results",
+  "down",
 ]);
 
+function configCheckedCommand(command: string): boolean {
+  return TELEMETRY_COMMANDS.has(command) && !CONFIG_FREE_COMMANDS.has(command);
+}
+
 /** Map a raw command token to a PII-safe, registered telemetry command name. */
 function telemetryCommandName(command?: string): string {
   if (!command) return "none";
@@ -709,6 +809,28 @@ class DenCLI {
     }
 
     try {
+      // A config that fails validation stops every command that touches
+      // orgs, the catalog, clones or releases before it reads or writes
+      // anything: some (sync over existing clones, register, workspace
+      // create) never read `orgs:` and used to carry on (ORG-1d).
+      if (command && configCheckedCommand(command)) assertDenConfigValid();
+      // `down` is never stranded by an invalid config (0.3.0-dev.40): it
+      // says so and stops from the daemon records and compose projects,
+      // reading the config without its org data.
+      if (command === "down") {
+        try {
+          assertDenConfigValid();
+        } catch (e) {
+          if (!isConfigError(e)) throw e;
+          console.log(
+            chalk.yellow(
+              `\n  ⚠ ${e.message}\n  Stopping anyway, without the config's org data. Fix it, then \`${product().cli} validate\`.`,
+            ),
+          );
+          waiveInvalidOrgs();
+        }
+      }
+
       switch (command) {
         case "run":
           await this.runTestsCommand(args.slice(1));
@@ -763,6 +885,10 @@ class DenCLI {
           await this.cmdRegister(args.slice(1));
           break;
 
+        case "relocate":
+          await this.cmdRelocate(args.slice(1));
+          break;
+
         case "use-local":
           await this.cmdUseMode(args.slice(1), "dev-managed");
           break;
@@ -837,6 +963,10 @@ class DenCLI {
           await cmdEdge(args.slice(1));
           break;
 
+        case "doctor":
+          process.exitCode = cmdDoctor(args.slice(1));
+          break;
+
         case "service":
           process.exitCode = await cmdService(args.slice(1));
           break;
@@ -845,6 +975,14 @@ class DenCLI {
           await cmdStack(args.slice(1));
           break;
 
+        case "theme":
+          process.exitCode = await cmdTheme(args.slice(1));
+          break;
+
+        case "plugin":
+          process.exitCode = await cmdPlugin(args.slice(1));
+          break;
+
         case "apps":
         case "applications":
           await this.ensureWorkspaceSeeded();
@@ -1142,10 +1280,11 @@ class DenCLI {
       try {
         // An entry with `gh: ""` clones from the workspace's org, as `up`
         // does (and `setup --plan` says), instead of failing on an empty slug.
-        const ghSlug = resolveRepoGhSlug(repoName, catalog, () =>
+        // ORG-1d: a repo with no source and a `remote:` clones from it.
+        const ghSlug = resolveRepoCloneSource(repoName, catalog, () =>
           githubOrgFor(ws.name),
         );
-        if (!catalogEntry.gh?.trim())
+        if (needsGhRepair(catalogEntry, ghSlug))
           upsertCatalogEntry(repoName, { ...catalogEntry, gh: ghSlug });
         ensureManagedServiceClone(repoName, ghSlug, branch);
       } catch (err) {
@@ -1248,10 +1387,12 @@ class DenCLI {
       // Catalog entries written by the dev-managed add flow carry `gh: ""`, so
       // an entry can exist yet be unclonable. Derive the conventional slug and
       // persist the repair rather than cloning from an empty URL.
-      const ghSlug = resolveRepoGhSlug(repoName, catalog, () =>
+      // ORG-1d: a repo with no source and a `remote:` clones from it.
+      const ghSlug = resolveRepoCloneSource(repoName, catalog, () =>
         githubOrgFor(ws.name),
       );
-      if (!catalog[repoName]?.gh) upsertCatalogEntry(repoName, { gh: ghSlug });
+      if (needsGhRepair(catalog[repoName], ghSlug))
+        upsertCatalogEntry(repoName, { ...catalog[repoName], gh: ghSlug });
       try {
         // runSetup=false: clone only — setup is run below, hidden + non-interactive.
         ensureManagedServiceClone(repoName, ghSlug, branch, false);
@@ -1488,6 +1629,8 @@ class DenCLI {
        * in order, and run nothing. Read-only on every path.
        */
       dryRun?: boolean;
+      /** `--plan`: a preview that would run nothing exits 1. */
+      plan?: boolean;
     },
   ): Promise<void> {
     // How long to show startup output before handing control back to the menu
@@ -1557,7 +1700,15 @@ class DenCLI {
       // The same lookup a real run makes, so the dry run says what it does.
       const previews = ordered.map((a): ServiceCommandPreview => {
         const remote = remoteRefusal(a);
-        if (!remote) return previewServiceCommand(a, command, workspace);
+        if (!remote) {
+          const p = previewServiceCommand(a, command, workspace);
+          // What up does first about a pre-dev.37 record or a held port.
+          return (
+            (command === "up" && p.kind === "run"
+              ? previewUpSettle(a, workspace)
+              : null) ?? p
+          );
+        }
         // As the loop below: a named remote target fails, any other is
         // said and skipped.
         return isNamedTarget(a, opts?.named ?? [])
@@ -1580,7 +1731,7 @@ class DenCLI {
         ),
       );
       for (const p of previews) {
-        if (p.kind === "via-repo" || p.kind === "nothing")
+        if (p.kind !== "error" && p.note)
           console.log(chalk.gray(`  ${p.note}`));
         if (p.kind === "error") console.log(chalk.red(`  ✗ ${p.note}`));
       }
@@ -1599,6 +1750,7 @@ class DenCLI {
         );
       }
       if (previews.some((p) => p.kind === "error")) process.exitCode = 1;
+      if (opts?.plan && runs.length === 0) process.exitCode = 1;
       console.log(chalk.gray(`  (--dry-run: not ${doing} anything)\n`));
       return;
     }
@@ -1657,12 +1809,27 @@ class DenCLI {
         const resolved = resolveService(address, workspace);
         if (resolved) {
           const health = await checkServiceHealth(resolved, "local");
-          if (health.health === "ok") {
+          // `conflict`: a shared stack namespace runs another checkout's
+          // project; the real up below refuses it, naming both.
+          const claim =
+            health.health === "ok" && workspace
+              ? claimHealthyService(resolved, workspace, printNotice)
+              : "untracked";
+          // Healthy, but another process answers on its port: said (above),
+          // never claimed, and nothing is started on top of it.
+          if (health.health === "ok" && claim === "busy") {
+            console.log(
+              chalk.red(
+                `  ✗ ${chalk.bold(address)} not started: its port is in use by a process ${product().cli} won't adopt`,
+              ),
+            );
+            // A dependency only warns; the service you named failed.
+            if (isNamedTarget(address, opts?.named ?? [])) process.exitCode = 1;
+            continue;
+          }
+          if (health.health === "ok" && claim !== "conflict") {
             // Skipping must not lose the refcount — this workspace is an owner
             // of what's running, whether den tracked it or not.
-            const claim = workspace
-              ? claimHealthyService(resolved, workspace)
-              : "untracked";
             const suffix =
               claim === "adopted"
                 ? " (adopted its running containers)"
@@ -1763,6 +1930,8 @@ class DenCLI {
         let result: ReturnType<typeof runServiceCommand> | null = null;
         let detachable = false;
         let interactive = false;
+        // A down that found nothing to stop is said as such, never as ✔.
+        let downOutcome: DownOutcome | null = null;
 
         const settleFromClose = (exitCode: number): void => {
           if (settled) return;
@@ -1779,6 +1948,17 @@ class DenCLI {
                 ),
               );
             }
+          } else if (exitCode === 0 && downOutcome === "nothing-recorded") {
+            spinner.info(
+              `${command} ${chalk.bold(address)} ${chalk.gray("(nothing to stop)")}`,
+            );
+          } else if (exitCode === 0 && downOutcome === "unstoppable") {
+            spinner.warn(
+              `${command} ${chalk.bold(address)} ${chalk.yellow("(could not stop it)")}`,
+            );
+            for (const l of lastLines) {
+              console.log(chalk.gray(`      ${l}`));
+            }
           } else if (exitCode === 0) {
             spinner.succeed(`${command} ${chalk.bold(address)}`);
           } else {
@@ -1832,8 +2012,21 @@ class DenCLI {
           runtime,
           workspace,
           force: command === "down" ? force : false,
+          // Down fails when it cannot stop a service the user named; one
+          // reached as part of a workspace-wide down warns instead.
+          explicit: isNamedTarget(address, opts?.named ?? []),
+          onDownOutcome: (outcome) => {
+            downOutcome = outcome;
+          },
           secretEnv: secrets.secretEnv,
           onLine: (line) => {
+            // What Den decided about a record or a port is said, not
+            // only flashed in the spinner (0.3.0-dev.39).
+            if (isNotice(line)) {
+              spinner.clear();
+              printNotice(line);
+              if (spinner.isEnabled) spinner.render();
+            }
             spinner.text = `${command} ${chalk.bold(address)}: ${chalk.gray(line.slice(0, 80))}`;
             const trimmed = line.trim();
             if (trimmed) {
@@ -2042,6 +2235,7 @@ class DenCLI {
           `\n  ${chalk.bold(seed)} has no derived dependencies to start.\n`,
         ),
       );
+      if (plan) process.exitCode = 1;
       return;
     }
     // Systems the user toggled to auto-start OFF in this workspace are not
@@ -2088,11 +2282,15 @@ class DenCLI {
       this.renderUpClonePlan(rawOrder);
       return;
     }
+    // A repo with no up of its own starts its services, one with no up at
+    // all is skipped: the decision `up -a` makes (resolveUpTargets).
+    const targets = new Set(include ? [seed] : []);
     if (dryRun) {
+      const up = this.upTargets(order, targets, graph);
       await this.runServicesCommand(
-        order,
+        up.order,
         "up",
-        { order },
+        { order: up.order },
         { named, dryRun: true },
       );
       return;
@@ -2116,12 +2314,18 @@ class DenCLI {
       );
       return;
     }
+    const up = this.upTargets(order, targets, graph);
+    if (up.order.length === 0) {
+      console.log(chalk.yellow("  Nothing to start.\n"));
+      return;
+    }
     await this.runServicesCommand(
-      order,
+      up.order,
       "up",
       {
-        order,
-        waitDepsFor: (address) => hardDepsOf(graph, address),
+        order: up.order,
+        waitDepsFor: (address) =>
+          up.depsAs(hardDepsOf(graph, repoOfAddress(address))),
         failFast: true,
         skipHealthyAll: true,
       },
@@ -2129,6 +2333,37 @@ class DenCLI {
     );
   }
 
+  /**
+   * The start order `up` runs (`up <repo>` and `up -a` alike): a repo with
+   * no up of its own replaced by its services' ups, one with no up at all
+   * skipped (resolveUpTargets), said as it decides.
+   */
+  private upTargets(
+    order: string[],
+    targets: ReadonlySet<string>,
+    graph: DerivedGraph,
+  ): UpTargets {
+    const up = resolveUpTargets(order, this.focusedWs(), { targets, graph });
+    this.sayUpTargets(up);
+    return up;
+  }
+
+  /** What resolveUpTargets decided, in `up`'s words. */
+  private sayUpTargets(up: UpTargets): void {
+    for (const [repo, addrs] of up.expanded)
+      console.log(
+        chalk.gray(
+          `  ${repo} has no up of its own: starting ${addrs.join(", ")}`,
+        ),
+      );
+    if (up.skippedNoUp.length > 0)
+      console.log(
+        chalk.gray(
+          `  Skipping (no local up command): ${up.skippedNoUp.join(", ")}\n`,
+        ),
+      );
+  }
+
   /**
    * Stop the seed repo and the dependencies it was started with — the same
    * closure `den up <seed>` brings up, torn down in reverse (seed first,
@@ -2283,6 +2518,7 @@ class DenCLI {
           "\n  No services in the active workspace — nothing to start.\n",
         ),
       );
+      if (plan) process.exitCode = 1;
       return;
     }
     const { rawOrder, graph } = target;
@@ -2345,19 +2581,18 @@ class DenCLI {
     // is skipped, not fatal. `-a` starts independent peers — one unrunnable
     // repo must not strand the rest (runServiceCommand exits 1 on a missing
     // command, and a fail-fast would turn that into a full abort). Now that
-    // clones exist, the manifest lookup is meaningful.
-    const order: string[] = [];
-    const skippedNoUp: string[] = [];
-    for (const repo of candidates) {
-      const resolved = resolveService(repo);
-      const upDef = resolved
-        ? localCommandsFor(resolved, this.focusedWs())["up"]
-        : undefined;
-      (upDef ? order : skippedNoUp).push(repo);
-    }
+    // clones exist, the manifest lookup is meaningful. A repo with no up of
+    // its own but per-service ups starts those services: the same decision
+    // `up <repo>` makes for a dependency (upTargets).
+    const up = resolveUpTargets(candidates, this.focusedWs(), {
+      targets: new Set(candidates),
+      graph,
+    });
+    const order = up.order;
+    const systems = candidates.filter((r) => !up.skippedNoUp.includes(r));
     console.log(
       chalk.cyan(
-        `\n  ${only ? "Application" : "Workspace-wide"} up — ${chalk.bold(String(order.length))} ${noun(order.length, "system")}`,
+        `\n  ${only ? "Application" : "Workspace-wide"} up — ${chalk.bold(String(systems.length))} ${noun(systems.length, "system")}`,
       ),
     );
     console.log(chalk.gray(`  Order: ${order.join(" → ")}\n`));
@@ -2369,13 +2604,7 @@ class DenCLI {
         ),
       );
     }
-    if (skippedNoUp.length > 0) {
-      console.log(
-        chalk.gray(
-          `  Skipping (no local up command): ${skippedNoUp.join(", ")}\n`,
-        ),
-      );
-    }
+    this.sayUpTargets(up);
     if (order.length === 0) {
       console.log(chalk.yellow("  Nothing to start.\n"));
       return;
@@ -2385,13 +2614,17 @@ class DenCLI {
     // healthy-skip. Unlike runDerivedUp there is NO failFast on the start
     // loop: `-a`'s systems are independent peers — one failure must not
     // strand the rest (the web master button continues too).
-    const repoSet = new Set(order);
+    const repoSet = new Set(systems);
     await this.runServicesCommand(order, "up", {
       order,
       // Hard deps outside the workspace can't be waited on — filter to the set
       // we are actually starting.
       waitDepsFor: (address) =>
-        hardDepsOf(graph, address).filter((dep) => repoSet.has(dep)),
+        up.depsAs(
+          hardDepsOf(graph, repoOfAddress(address)).filter((dep) =>
+            repoSet.has(dep),
+          ),
+        ),
       skipHealthyAll: true,
     });
   }
@@ -2427,6 +2660,14 @@ class DenCLI {
       return;
     }
     await this.runServicesCommand(order, "down", { order }, { force });
+    // Records no workspace reaches: -a stops every workspace's services,
+    // not these. Said, and left alone (0.3.0-dev.39, a consumer's finding).
+    if (!only)
+      for (const d of daemonsOutsideWorkspaces())
+        printNotice(
+          `Warning: ${d.address} is recorded as running (${d.repoPath}) but is in no active workspace: ` +
+            `down -a left it alone. Stop it yourself if it still runs.`,
+        );
   }
 
   private printUpHelp(): void {
@@ -2714,10 +2955,10 @@ class DenCLI {
   }
 
   private async cmdServiceUp(args: string[]): Promise<void> {
-    await this.ensureWorkspaceSeeded();
     // Tokens after a `--` terminator belong to a child command — they must
     // never be read as up's own flags (`den up -- -a` is NOT `up -a`).
     const terminator = args.indexOf("--");
+    await this.ensureWorkspaceSeeded();
     const { app, rest } = takeAppFlag(
       terminator === -1 ? args : args.slice(0, terminator),
     );
@@ -2781,6 +3022,7 @@ class DenCLI {
     await this.cmdServiceUpManifest(
       ownArgs.filter((a) => !a.startsWith("-")),
       dryRun || plan,
+      plan,
     );
   }
 
@@ -2788,6 +3030,7 @@ class DenCLI {
   private async cmdServiceUpManifest(
     addresses: string[],
     dryRun = false,
+    plan = false,
   ): Promise<void> {
     // Resolve targets BEFORE the secrets preflight — otherwise running
     // `den up` from a non-service dir (e.g. the den repo root) triggers
@@ -2806,6 +3049,16 @@ class DenCLI {
                 `  or run \`${product().cli} graph\` to see the workspace.\n`,
             ),
         );
+      } else if (process.env.DEN_WORKSPACE_OVERRIDE) {
+        // `up -w <ws>` with nothing to start: -w picks the workspace, not
+        // what in it to start. A usage error, not an empty plan.
+        console.error(
+          chalk.red(
+            `\n  ${upNeedsTarget(product().cli, process.env.DEN_WORKSPACE_OVERRIDE, plan)}\n`,
+          ),
+        );
+        process.exitCode = 2;
+        return;
       } else {
         console.log(
           chalk.yellow(
@@ -2813,12 +3066,15 @@ class DenCLI {
           ),
         );
       }
+      // A plan that resolves nothing is a failed plan (scripts check it).
+      if (plan) process.exitCode = 1;
       return;
     }
     if (!dryRun) preflightSecrets();
     await this.runServicesCommand(targets, "up", undefined, {
       named: addresses,
       dryRun,
+      plan,
     });
   }
 
@@ -2935,15 +3191,49 @@ class DenCLI {
 
   private async cmdServiceStatus(argv: string[] = []): Promise<void> {
     await this.ensureWorkspaceSeeded();
-    const { app, rest: args } = takeAppFlag(argv);
+    const { app, rest: appRest } = takeAppFlag(argv);
+    // The view scope (as the web UI's): every active workspace by default,
+    // or `--scope <workspace>` for one. A view only: focus is unchanged.
+    const scoped = takeScopeFlag(appRest);
+    const args = scoped.rest;
+    const scopeArg =
+      scoped.scope === null
+        ? null
+        : parseScope(scoped.scope, getActiveWorkspaces());
+    if (scoped.error || (scopeArg && !scopeArg.ok)) {
+      console.log(
+        chalk.red(
+          `\n  ${scoped.error ?? (scopeArg && !scopeArg.ok ? scopeArg.error : "")}\n`,
+        ),
+      );
+      process.exit(1);
+    }
+    // `-w <workspace>` still means that workspace only (active or not).
+    const named = process.env.DEN_WORKSPACE_OVERRIDE
+      ? getActiveWorkspace()
+      : null;
+    const view =
+      named && !scopeArg
+        ? {
+            scope: named.name,
+            fellBack: false,
+            workspaces: [named],
+            focus: named.name,
+          }
+        : scopeView(scopeArg?.ok ? scopeArg.value : undefined);
     const only = app ? focusedAppRepos(app) : null;
     const verbose = args.includes("--verbose") || args.includes("--all");
     const spinner = ora("Checking service health...").start();
-    const raw = (await checkCatalogHealth()).filter(
-      (h) => !only || only.has(h.repoName),
-    );
-    // Roll multi-service repos up to their entrypoint so shared-infra sidecars
-    // (which read healthy off infra-stack) don't make a down app look up.
+    const raw = (
+      await checkCatalogHealth(
+        undefined,
+        "local",
+        view.workspaces.filter((w) => w.config),
+      )
+    ).filter((h) => !only || only.has(h.repoName));
+    // One row per repo, rolled up from every checked service by the rule the
+    // web UI's header and graph use: entry down → down, another checked
+    // service down → degraded; unchecked services never count.
     const rolled = verbose ? raw : rollupRepoHealth(raw);
     // Order top-down like the graph: entry repo first (shop-web) … foundation
     // last (infra-stack), subsystems grouped under their repo.
@@ -2961,10 +3251,7 @@ class DenCLI {
       return;
     }
 
-    const ws = getActiveWorkspace();
-    console.log(
-      chalk.cyan(`\n  Workspace: ${chalk.bold(ws?.name ?? "none")}\n`),
-    );
+    console.log(chalk.cyan(`\n  ${scopeLine(view)}\n`));
 
     const table = newTable({
       head: ["Service", "Mode", "Branch", "Health", "Reason"],
@@ -2972,8 +3259,20 @@ class DenCLI {
     });
 
     for (const r of results) {
-      const healthStr = formatHealthLabel(r.health);
-      const reasonStr = formatHealthReason(r);
+      const healthStr = r.rollup
+        ? formatRollupLabel(r.rollup)
+        : formatHealthLabel(r.health);
+      const rolledWhy = r.rollup ? rollupReasonText(r.rollup) : "";
+      const reasonStr =
+        r.rollup && r.rollup.state !== "unknown"
+          ? chalk.gray(
+              [r.rollup.state === "down" ? healthReasonText(r) : "", rolledWhy]
+                .filter(Boolean)
+                .join("; ")
+                .slice(0, 60),
+            )
+          : formatHealthReason(r) ||
+            (rolledWhy ? chalk.gray(rolledWhy.slice(0, 60)) : "");
       const placed = placementSuffix({
         runs: r.runs ?? "none",
         target: r.target ?? null,
@@ -2981,6 +3280,7 @@ class DenCLI {
 
       table.push([
         this.labelWithAutostart(r.address, noAutostart) +
+          chalk.gray(ownersSuffix(r.workspaces)) +
           (placed ? chalk.cyan(`  ${placed}`) : ""),
         r.mode === "dev-managed"
           ? chalk.blue("dev-managed")
@@ -3002,7 +3302,7 @@ class DenCLI {
     if (!verbose && raw.length !== results.length) {
       console.log(
         chalk.gray(
-          `  ▪ multi-service repos show entrypoint health — \`${product().cli} status --verbose\` for all subsystems`,
+          `  ▪ one row per repo, rolled up from its checked services — \`${product().cli} status --verbose\` for each`,
         ),
       );
     }
@@ -3173,15 +3473,32 @@ class DenCLI {
   private async cmdRegister(args: string[]): Promise<void> {
     if (args.includes("-h") || args.includes("--help")) {
       console.log(
-        `\n  ${product().cli} register [path] [--name <repo>] [--gh <owner/repo>]\n\n` +
+        `\n  ${product().cli} register [path] [--name <repo>] [--gh <owner/repo>] [-w <workspace>] [--org <id>]\n\n` +
           "  With a path: add that checkout to the catalog and the focused\n" +
           "  workspace as your own (dev-managed) copy, without prompts. The name\n" +
           "  defaults to the manifest's name, then the folder name; the GitHub\n" +
-          "  slug to the git remote.\n" +
-          "  Without a path: choose a local checkout or a managed clone interactively.\n",
+          "  slug to the git remote. -w writes that workspace (active or not)\n" +
+          "  and leaves focus alone.\n" +
+          "  Without a path: choose a local checkout or a managed clone interactively;\n" +
+          "  a managed clone comes from the workspace's org, or --org <id>.\n",
       );
       return;
     }
+    const repoPathArg = args.find(
+      (a, i) =>
+        !a.startsWith("-") && !/^--(name|gh|org)$/.test(args[i - 1] ?? ""),
+    );
+    // Without a path, register prompts: with no terminal (stdin closed or
+    // piped, where readline would throw ERR_USE_AFTER_CLOSE mid-prompt), say
+    // how to name one. Usage error: exit 2.
+    if (!repoPathArg && !process.stdin.isTTY) {
+      process.stderr.write(
+        `register needs a terminal (stdin is not a TTY); without one: ` +
+          `${product().cli} register <path> [--name <repo>] [--gh <owner/repo>] [-w <workspace>]\n`,
+      );
+      process.exitCode = 2;
+      return;
+    }
     const ws = getActiveWorkspace();
     if (!ws) {
       console.log(
@@ -3192,10 +3509,6 @@ class DenCLI {
       return;
     }
 
-    const repoPathArg = args.find(
-      (a, i) =>
-        !a.startsWith("-") && !/^--(name|gh|org)$/.test(args[i - 1] ?? ""),
-    );
     if (repoPathArg) {
       const flag = (n: string) => {
         const i = args.indexOf(n);
@@ -3214,7 +3527,157 @@ class DenCLI {
     }
   }
 
-  /** Non-interactive `register <path>`: a dev-managed entry in the focused workspace. */
+  /**
+   * `relocate <repo> <path>`: a checkout moved on disk. Rewrites the path of
+   * every dev-managed entry for <repo> (bare and `<repo>/<svc>` addresses) in
+   * every workspace, or only the `-w` one. Managed entries are Den's own
+   * clones and are left alone. Focus and the active set never change.
+   */
+  private async cmdRelocate(args: string[]): Promise<void> {
+    const usage = `${product().cli} relocate <repo> <path> [--dry-run] [--force] [-w <workspace>]`;
+    if (args.includes("-h") || args.includes("--help")) {
+      console.log(
+        `\n  ${usage}\n\n` +
+          "  A checkout moved: point every workspace's dev-managed entries for\n" +
+          "  <repo> at <path>. Refuses a missing path, one whose manifest\n" +
+          "  name or GitHub remote names a different repo, and one where\n" +
+          "  neither names this repo (--force accepts that last). --dry-run shows\n" +
+          "  the changes without writing. -w limits it to that workspace.\n" +
+          "  Focus and the active set never change.\n",
+      );
+      return;
+    }
+    const dryRun = args.includes("--dry-run") || args.includes("-n");
+    const force = args.includes("--force");
+    const unknown = args.find(
+      (a) => a.startsWith("-") && !["--dry-run", "-n", "--force"].includes(a),
+    );
+    const positional = args.filter((a) => !a.startsWith("-"));
+    if (unknown || positional.length !== 2) {
+      console.error(
+        chalk.red(
+          `\n  ❌ ${unknown ? `Unknown flag: ${unknown}` : "Need a repo and a path"}.\n     Usage: ${usage}\n`,
+        ),
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const [repoName, rawPath] = positional;
+    const { existsSync, statSync } = await import("fs");
+    const newPath = nodePath.resolve(rawPath);
+    const fail = (msg: string) => {
+      console.error(chalk.red(`\n  ❌ ${msg}\n`));
+      process.exitCode = 1;
+    };
+    const file = readWorkspacesFile();
+    const only = process.env.DEN_WORKSPACE_OVERRIDE;
+    const names = only ? [only] : Object.keys(file.workspaces);
+    const belongs = (key: string) =>
+      key === repoName || key.startsWith(`${repoName}/`);
+    if (
+      !names.some((ws) =>
+        Object.keys(file.workspaces[ws]?.services ?? {}).some(belongs),
+      )
+    ) {
+      fail(
+        `"${repoName}" is not in ${only ? `workspace "${only}"` : "any workspace"}.`,
+      );
+      return;
+    }
+    if (!existsSync(newPath) || !statSync(newPath).isDirectory()) {
+      fail(`Path does not exist: ${newPath}`);
+      return;
+    }
+
+    // The new path must hold this repo: its manifest name and GitHub remote,
+    // when present, must agree with the repo and its catalog entry.
+    const manifest = readManifest(newPath);
+    const leaf = repoName.split("/").pop() ?? repoName;
+    if (
+      manifest?.name &&
+      manifest.name !== repoName &&
+      manifest.name !== leaf
+    ) {
+      fail(
+        `${newPath} holds "${manifest.name}", not "${repoName}" (its manifest name).`,
+      );
+      return;
+    }
+    const catalogGh = readCatalog()[repoName]?.gh?.trim();
+    const coords = getGitHubCoords(newPath);
+    const remote = coords ? `${coords.owner}/${coords.repo}` : undefined;
+    if (
+      catalogGh &&
+      remote &&
+      catalogGh.toLowerCase() !== remote.toLowerCase()
+    ) {
+      fail(
+        `${newPath} is a checkout of ${remote}; the catalog has "${repoName}" as ${catalogGh}.`,
+      );
+      return;
+    }
+    // Not contradicting is not enough: an empty or unrelated folder has no
+    // manifest and no remote. Something must say this is the repo.
+    const identified =
+      manifest?.name === repoName ||
+      manifest?.name === leaf ||
+      (!!catalogGh &&
+        !!remote &&
+        catalogGh.toLowerCase() === remote.toLowerCase()) ||
+      (!catalogGh && coords?.repo.toLowerCase() === leaf.toLowerCase());
+    if (!identified && !force) {
+      fail(
+        `Nothing at ${newPath} says it is "${repoName}": no manifest named ` +
+          `"${leaf}" and no GitHub remote ${catalogGh || `…/${leaf}`}.\n` +
+          `     If it is, say so: ${product().cli} relocate ${repoName} ${rawPath} --force${dryRun ? " --dry-run" : ""}${only ? ` -w ${only}` : ""}`,
+      );
+      return;
+    }
+
+    const changes: { ws: string; addr: string; from: string }[] = [];
+    const managed: { ws: string; addr: string }[] = [];
+    for (const ws of names) {
+      const entries = file.workspaces[ws]?.services ?? {};
+      for (const [addr, entry] of Object.entries(entries)) {
+        if (!belongs(addr)) continue;
+        if (entry.mode !== "dev-managed") {
+          managed.push({ ws, addr });
+          continue;
+        }
+        if (entry.path && nodePath.resolve(entry.path) === newPath) continue;
+        changes.push({ ws, addr, from: entry.path ?? "(default)" });
+        if (!dryRun) entry.path = newPath;
+      }
+    }
+
+    if (changes.length > 0 && !dryRun) writeWorkspacesFile(file);
+
+    const verb = dryRun ? "Would point" : "Pointed";
+    if (changes.length === 0) {
+      console.log(
+        chalk.gray(
+          `\n  Nothing to change: "${repoName}" is already at ${newPath}.`,
+        ),
+      );
+    } else {
+      console.log(chalk.green(`\n  ✓ ${verb} at ${newPath}:\n`));
+      for (const c of changes) {
+        console.log(
+          `    ${chalk.bold(c.addr)}  ${chalk.gray(`${c.ws}   was ${c.from}`)}`,
+        );
+      }
+    }
+    for (const m of managed) {
+      console.log(
+        chalk.gray(
+          `    ${m.addr}  ${m.ws}   managed (Den's clone): left alone`,
+        ),
+      );
+    }
+    console.log();
+  }
+
+  /** Non-interactive `register <path>`: a dev-managed entry in the focused (or -w) workspace. */
   private async registerPath(
     ws: {
       name: string;
@@ -3306,7 +3769,8 @@ class DenCLI {
       console.log(
         chalk.red(
           `\n  ❌ No GitHub org to list: set github_org in ${product().configFile}, ` +
-            `org: on workspace ${ws.name}, or pass --org <id>\n`,
+            `org: on workspace ${ws.name}, or pass --org <id> ` +
+            `(an org with no GitHub source in orgs.<id>.sources has none)\n`,
         ),
       );
       return;
@@ -3559,18 +4023,38 @@ class DenCLI {
     console.log(chalk.gray(`    revert: ${revert}\n`));
   }
 
-  private async cmdSetup(args: string[]): Promise<void> {
+  private async cmdSetup(rawArgs: string[]): Promise<void> {
+    // `-w <ws>` (repeatable) and `--all-active` pick the workspaces to plan.
+    const { workspaces: planWs, rest: args } = takeWorkspaceFlags(rawArgs);
+    const allActive = args.includes("--all-active");
     const force = args.includes("--force") || args.includes("-f");
     const names = args.filter((a) => !a.startsWith("-"));
 
     // `--plan`: each repo's org and clone URL, then stop. Read-only.
     if (args.includes("--plan")) {
+      let plan: ReturnType<typeof buildSetupPlan>;
+      try {
+        plan = buildSetupPlan(names, { workspaces: planWs, allActive });
+      } catch (e) {
+        console.error(chalk.red(`\n  ${(e as Error).message}\n`));
+        process.exitCode = 1;
+        return;
+      }
       console.log(chalk.bold("\n  Setup plan (no changes will be made):\n"));
-      for (const line of renderClonePlan(buildSetupPlan(names), product().cli))
+      for (const line of renderClonePlan(plan, product().cli))
         console.log(`  ${line}`.trimEnd());
       console.log();
       return;
     }
+    if (planWs.length || allActive) {
+      console.error(
+        chalk.red(
+          `\n  -w and --all-active go with --plan: setup itself works on the focused workspace.\n`,
+        ),
+      );
+      process.exitCode = 1;
+      return;
+    }
 
     // Clone any managed repos that aren't on disk yet before reading manifests.
     this.cloneMissingManagedRepos();
@@ -3662,14 +4146,32 @@ class DenCLI {
         const only = orgFlag(args.slice(1));
         const { resolved, warnings } = orgListRows();
         const orgOfWs = new Map(resolved.map((w) => [w.workspace, w.org]));
-        const table = newTable({
-          head: ["Workspace", "Org", "Active", "Focus", "Services", "Type"],
-          style: { head: ["cyan"] },
-        });
         const shown = Object.entries(file.workspaces).filter(
           ([name]) => !only || sameOrg(orgOfWs.get(name) ?? null, only),
         );
+        // A Stacks column only when a shown workspace's stack namespace is
+        // not its default suffix (or is invalid): the list is otherwise as before.
+        const nsRows = new Map(
+          stackNamespaceRows(shown.map(([n]) => n)).map((r) => [
+            r.workspace,
+            r,
+          ]),
+        );
+        const nsCol = [...nsRows.values()].some((r) => r.differs || r.error);
+        const table = newTable({
+          head: [
+            "Workspace",
+            "Org",
+            "Active",
+            "Focus",
+            "Services",
+            "Type",
+            ...(nsCol ? ["Stacks"] : []),
+          ],
+          style: { head: ["cyan"] },
+        });
         for (const [name, cfg] of shown) {
+          const ns = nsRows.get(name);
           table.push([
             chalk.bold(name),
             orgOfWs.get(name) ?? chalk.gray("none"),
@@ -3677,9 +4179,23 @@ class DenCLI {
             name === focus ? chalk.cyan("●") : "",
             Object.keys(cfg.services).join(", ") || chalk.gray("none"),
             cfg.directory ? chalk.magenta("feature") : chalk.blue("default"),
+            ...(nsCol
+              ? [
+                  ns?.error
+                    ? chalk.red("invalid")
+                    : ns?.differs
+                      ? `${ns.stack_namespace} ${chalk.gray(`(${ns.source})`)}`
+                      : chalk.gray(ns?.default ?? ""),
+                ]
+              : []),
           ]);
         }
         console.log(table.toString());
+        printOrgWarnings(
+          [...nsRows.values()].flatMap((r) =>
+            r.error ? [`workspace ${r.workspace}: ${r.error}`] : r.warnings,
+          ),
+        );
         if (only && shown.length === 0)
           console.log(chalk.yellow(`  No workspace in org ${only}.`));
         const names = new Set(shown.map(([n]) => n));
@@ -3986,6 +4502,58 @@ class DenCLI {
   // ── den validate ────────────────────────────────────────────────────────
 
   private async cmdValidate(args: string[]): Promise<void> {
+    // The org config first (0.3.0-dev.40, a consumer's 0.2.8 nit: a
+    // ConfigError went unreported): each problem with its file and key
+    // path, a non-zero exit, and the manifests are still checked, reading
+    // the config without its org data.
+    try {
+      assertDenConfigValid();
+    } catch (e) {
+      if (!isConfigError(e)) throw e;
+      console.error(chalk.red(`\n  ✗ ${product().configFile} is invalid:`));
+      const issues = e.issues.length
+        ? e.issues
+        : [{ file: product().configFile, key: "", message: e.message }];
+      for (const i of issues)
+        console.error(
+          chalk.red(`  ✗ ${i.file}  ${chalk.bold(i.key)}  ${i.message}`),
+        );
+      process.exitCode = 1;
+      waiveInvalidOrgs();
+    }
+    // The distribution's secrets config, once: a 1password backend with no
+    // refs leaves the vault-backed features off (no built-in vault/item).
+    try {
+      const { secretsConfigWarnings } =
+        await import("../../shared/secrets/index.js");
+      for (const w of secretsConfigWarnings())
+        console.warn(chalk.yellow(`\n  ⚠  ${w.replace(/\n/g, "\n     ")}`));
+    } catch {
+      /* an unreadable config is reported elsewhere */
+    }
+    // The edge's TLS strategy, when there is an edge: its config, the
+    // implicit-mkcert warning (once), and detect() (mkcert on PATH).
+    {
+      const { hasEdgeBlock, readEdgeConfig } =
+        await import("../../shared/edge/config.js");
+      const { edgeTlsWarnings, tlsStrategyFor, warnImplicitTlsOnce } =
+        await import("../../shared/edge/tls.js");
+      let edge: ReturnType<typeof readEdgeConfig> | null = null;
+      try {
+        if (hasEdgeBlock()) edge = readEdgeConfig();
+      } catch (e) {
+        console.error(chalk.red(`\n  ✗  edge: ${(e as Error).message}`));
+        process.exitCode = 1;
+      }
+      if (edge) {
+        const warn = (w: string) => console.warn(chalk.yellow(`\n  ⚠  ${w}`));
+        warnImplicitTlsOnce(edge, warn);
+        for (const w of edgeTlsWarnings(edge))
+          if (edge.tlsFrom !== "implicit") warn(w);
+        const d = tlsStrategyFor(edge).detect();
+        if (!d.available) warn(`edge.tls ${edge.tls.strategy}: ${d.reason}`);
+      }
+    }
     const positional = args.filter((a) => !a.startsWith("-"));
     const held = args.includes("--held");
     // Bare `validate` in the distribution root (which has no manifest of its
@@ -4190,7 +4758,7 @@ class DenCLI {
       "  restart [service...] Restart services (-A <app> for a whole application)",
     );
     console.log(
-      "  status               Show service health for active workspace (-A <app>)",
+      "  status               Show service health for the view scope (-A <app>, --scope <ws>)",
     );
     console.log(
       "  apps                 Org > Application > Repo > Services (--json)",
@@ -4211,6 +4779,9 @@ class DenCLI {
     console.log(
       "  register [path]      Register a repo in the service catalog",
     );
+    console.log(
+      "  relocate <repo> <path>  Point a moved checkout's workspace entries at its new path",
+    );
     console.log();
     console.log(
       "  setup [service...]   Run make setup for services (--plan: orgs + clone URLs, no changes)",
@@ -4228,6 +4799,12 @@ class DenCLI {
     console.log(
       "  service install      Run the web UI as a launchd service (status, print, uninstall)",
     );
+    console.log(
+      "  theme add <repo>@<ref> Install a web UI theme (list, validate, remove)",
+    );
+    console.log(
+      "  plugin list          Local and added plugins, checked (validate, add, update, remove)",
+    );
     console.log();
     console.log(
       "  workspace list           List workspaces (active set + focus)",