@monster-orange/den 0.2.4 → 0.2.6

package/src/shared/den-config.ts

@@ -255,24 +255,35 @@ export interface DenConfig {
    * `default-workspace.ts`.
    */
   defaults?: {
-    workspace?: {
-      /** Branch managed clones track (default "main"). */
-      branch?: string;
-      /** Repo-system names to seed, all as managed clones. */
-      repos?: string[];
+    workspace?: WorkspaceBlueprint & {
       /** The entry repo the seed's dependency walk starts from (listed first). */
       entry?: string;
-      /**
-       * Seeded repos that get `autostart: false` stamped on their workspace
-       * entry — the team default for systems a fresh clone should not start
-       * with workspace up (e.g. billing-api's `make up` opens an interactive
-       * Stripe tab). Personal thereafter: toggle per system in the web ⋮ menu.
-       */
-      autostart_off?: string[];
     };
+    /**
+     * Multi-workspace blueprint: `{ <name>: { repos, focus?, branch?,
+     * autostart_off? } }`. On a genuine fresh setup each workspace is created
+     * with its repos (managed), all are activated, and the one marked
+     * `focus: true` (else the first) is focused. Exclusive with `workspace`.
+     */
+    workspaces?: Record<string, WorkspaceBlueprint & { focus?: boolean }>;
   };
 }
 
+/** One workspace's blueprint: the repo entries a fresh setup seeds it with. */
+export interface WorkspaceBlueprint {
+  /** Branch managed clones track (default "main"). */
+  branch?: string;
+  /** Repo-system names to seed, all as managed clones. */
+  repos?: string[];
+  /**
+   * Seeded repos that get `autostart: false` stamped on their workspace
+   * entry — the team default for systems a fresh clone should not start
+   * with workspace up (e.g. billing-api's `make up` opens an interactive
+   * Stripe tab). Personal thereafter: toggle per system in the web ⋮ menu.
+   */
+  autostart_off?: string[];
+}
+
 /**
  * Per-engineer preferences stored in config/local/user.yml (gitignored).
  * Only affects settings that should differ between engineers on the same team.
@@ -618,6 +629,113 @@ export interface WebConfig {
   service?: { label?: string; logs?: string };
 }
 
+/** A validated workspace blueprint with its defaults applied. */
+export interface ResolvedWorkspaceBlueprint {
+  name: string;
+  repos: string[];
+  branch: string;
+  autostartOff: string[];
+  focus: boolean;
+}
+
+/** Which blueprint shape the distribution uses, and its workspaces. */
+export interface WorkspaceBlueprints {
+  shape: "none" | "single" | "multi";
+  workspaces: ResolvedWorkspaceBlueprint[];
+}
+
+const BLUEPRINT_KEYS = ["branch", "repos", "autostart_off"];
+
+function blueprintStrings(where: string, key: string, v: unknown): string[] {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || v.some((r) => typeof r !== "string" || !r.trim()))
+    throw new Error(`${where}.${key} must be a list of repo names`);
+  return v as string[];
+}
+
+function resolveBlueprint(
+  where: string,
+  name: string,
+  raw: unknown,
+  /** Extra keys allowed; null skips the unknown-key check (legacy shape). */
+  extraKeys: string[] | null,
+): ResolvedWorkspaceBlueprint {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error(`${where} must be a map: { repos: [...] }`);
+  const bp = raw as Record<string, unknown>;
+  const known = [...BLUEPRINT_KEYS, ...(extraKeys ?? [])];
+  for (const key of Object.keys(bp))
+    if (extraKeys && !known.includes(key))
+      throw new Error(
+        `${where}: unknown key "${key}" (known: ${known.join(", ")})`,
+      );
+  const branch = bp.branch ?? "main";
+  if (typeof branch !== "string" || !branch.trim())
+    throw new Error(`${where}.branch must be a branch name`);
+  if (bp.focus !== undefined && typeof bp.focus !== "boolean")
+    throw new Error(`${where}.focus must be true or false`);
+  return {
+    name,
+    repos: blueprintStrings(where, "repos", bp.repos),
+    branch,
+    autostartOff: blueprintStrings(where, "autostart_off", bp.autostart_off),
+    focus: bp.focus === true,
+  };
+}
+
+/**
+ * The distribution's workspace blueprint, validated: `defaults.workspace`
+ * (one workspace, `default`) or `defaults.workspaces` (named workspaces).
+ * Empty when neither is set. Both at once, or a malformed value, throws.
+ */
+export function readWorkspaceBlueprints(
+  config: DenConfig = readDenConfig(),
+): WorkspaceBlueprints {
+  const none: WorkspaceBlueprints = { shape: "none", workspaces: [] };
+  const defaults: unknown = config.defaults;
+  if (defaults === undefined || defaults === null) return none;
+  if (typeof defaults !== "object" || Array.isArray(defaults))
+    throw new Error(`defaults in ${DEN_CONFIG_PATH} must be a map`);
+  const { workspace, workspaces } = defaults as Record<string, unknown>;
+  if (workspace != null && workspaces != null)
+    throw new Error(
+      `${DEN_CONFIG_PATH} sets both defaults.workspace and defaults.workspaces: ` +
+        "use defaults.workspaces alone (name the default workspace `default` in it), " +
+        "or defaults.workspace alone for a single default workspace",
+    );
+  if (workspaces != null) {
+    if (typeof workspaces !== "object" || Array.isArray(workspaces))
+      throw new Error(
+        "defaults.workspaces must be a map: { <name>: { repos: [...], focus?: true } }",
+      );
+    const resolved = Object.entries(workspaces as Record<string, unknown>).map(
+      ([name, raw]) => {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+          throw new Error(
+            `defaults.workspaces: "${name}" is not a valid workspace name (letters, digits, dots, dashes, underscores)`,
+          );
+        return resolveBlueprint(`defaults.workspaces.${name}`, name, raw, [
+          "focus",
+        ]);
+      },
+    );
+    const focused = resolved.filter((b) => b.focus);
+    if (focused.length > 1)
+      throw new Error(
+        `defaults.workspaces: only one workspace may set focus: true (got ${focused.map((b) => b.name).join(", ")})`,
+      );
+    return { shape: "multi", workspaces: resolved };
+  }
+  if (workspace != null)
+    return {
+      shape: "single",
+      workspaces: [
+        resolveBlueprint("defaults.workspace", "default", workspace, null),
+      ],
+    };
+  return none;
+}
+
 /** `web.service` with its defaults applied. */
 export interface ResolvedWebService {
   /** launchd label; also the plist's name in ~/Library/LaunchAgents. */

package/src/shared/engine.ts

@@ -37,6 +37,24 @@ export function engineBin(name: string, engineRoot = getEngineRoot()): string {
   }
 }
 
+/**
+ * A file inside a package Den depends on (e.g. "tsx/dist/loader.mjs"): the
+ * nearest node_modules/<rel> at or above the engine root, or null.
+ */
+export function engineModuleFile(
+  rel: string,
+  engineRoot = getEngineRoot(),
+): string | null {
+  let dir = path.resolve(engineRoot);
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", rel);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 /** The tsx binary that runs Den's TypeScript sources. */
 export function tsxBin(): string {
   return engineBin("tsx");

package/src/shared/environment-manager/default-workspace.ts

@@ -14,63 +14,174 @@ import {
   writeWorkspacesFile,
 } from "./workspaces.js";
 import { readCatalog, writeCatalog } from "./catalog.js";
-import { readDenConfig, requireGithubOrg } from "../den-config.js";
-import type { WorkspaceServiceEntry } from "../types/index.js";
-
-const DEFAULT_BRANCH = "main";
+import {
+  readWorkspaceBlueprints,
+  requireGithubOrg,
+  type ResolvedWorkspaceBlueprint,
+} from "../den-config.js";
+import type {
+  ServiceCatalog,
+  WorkspaceConfig,
+  WorkspaceServiceEntry,
+  WorkspacesFile,
+} from "../types/index.js";
 
-export function defaultWorkspaceRepos(): string[] {
-  return readDenConfig().defaults?.workspace?.repos ?? [];
+/** The single-workspace blueprint (`defaults.workspace`), or null. */
+function singleBlueprint(): ResolvedWorkspaceBlueprint | null {
+  const bps = readWorkspaceBlueprints();
+  return bps.shape === "single" ? bps.workspaces[0] : null;
 }
 
-function defaultBranch(): string {
-  return readDenConfig().defaults?.workspace?.branch ?? DEFAULT_BRANCH;
+/** True when the distribution uses `defaults.workspaces` (named workspaces). */
+export function isMultiBlueprint(): boolean {
+  return readWorkspaceBlueprints().shape === "multi";
 }
 
-function org(): string {
-  return requireGithubOrg();
+/** The workspaces a fresh setup would seed, each with at least one repo. */
+export function blueprintWorkspaces(): ResolvedWorkspaceBlueprint[] {
+  return readWorkspaceBlueprints().workspaces.filter((b) => b.repos.length > 0);
 }
 
-/** True on a fresh clone: a blueprint exists but the `default` workspace is empty. */
-export function defaultWorkspaceNeedsSeeding(): boolean {
-  if (defaultWorkspaceRepos().length === 0) return false;
-  const def = readWorkspacesFile().workspaces["default"];
-  return !def || Object.keys(def.services ?? {}).length === 0;
+/** `defaults.workspace.repos` — the single blueprint's repos (empty for the multi shape). */
+export function defaultWorkspaceRepos(): string[] {
+  return singleBlueprint()?.repos ?? [];
 }
 
-/** Whether the `default` workspace already has services (so seeding would reset it). */
-export function defaultWorkspaceHasServices(): boolean {
-  const def = readWorkspacesFile().workspaces["default"];
-  return !!def && Object.keys(def.services ?? {}).length > 0;
+function org(): string {
+  return requireGithubOrg();
 }
 
-/**
- * Seed (or reset) the `default` workspace from the blueprint — every repo as a
- * bare, first-class managed entry on `branch` — and ensure the catalog has
- * clone URLs (`<org>/<repo>`, only filled where missing). Returns the seeded repos.
- */
-export function seedDefaultWorkspace(): string[] {
-  const repos = defaultWorkspaceRepos();
-  const branch = defaultBranch();
+function blueprintServices(
+  bp: ResolvedWorkspaceBlueprint,
+  repos: string[] = bp.repos,
+): Record<string, WorkspaceServiceEntry> {
   // Team default for systems a fresh workspace should NOT auto-start (e.g.
   // billing-api's `make up` opens an interactive Stripe tab). Personal after
   // seeding — toggled per system in the web ⋮ menu.
-  const autostartOff = new Set(
-    readDenConfig().defaults?.workspace?.autostart_off ?? [],
-  );
+  const autostartOff = new Set(bp.autostartOff);
   const services: Record<string, WorkspaceServiceEntry> = {};
   for (const repo of repos) {
     services[repo] = {
       mode: "managed",
-      branch,
+      branch: bp.branch,
       ...(autostartOff.has(repo) ? { autostart: false } : {}),
     };
   }
+  return services;
+}
+
+function fillCatalog(
+  repos: string[],
+  catalog: ServiceCatalog = readCatalog(),
+): void {
+  const o = org();
+  for (const repo of repos) {
+    if (!catalog[repo]?.gh) catalog[repo] = { gh: `${o}/${repo}` };
+  }
+  writeCatalog(catalog);
+}
+
+/**
+ * A genuine fresh setup: no workspace but `default` exists, `default` holds no
+ * services, and no blueprint was ever applied to it (`seeded_repos` unset —
+ * seeding, top-up and a declined offer all record it). An emptied `default`,
+ * or one next to other workspaces, is the user's deliberate state.
+ */
+export function isFreshWorkspaceSetup(
+  file: WorkspacesFile = readWorkspacesFile(),
+): boolean {
+  const names = Object.keys(file.workspaces);
+  if (names.some((n) => n !== "default")) return false;
+  const def = file.workspaces["default"];
+  if (!def) return true;
+  return (
+    Object.keys(def.services ?? {}).length === 0 &&
+    def.seeded_repos === undefined
+  );
+}
+
+/** True on a genuine fresh setup with a non-empty blueprint (single or multi). */
+export function defaultWorkspaceNeedsSeeding(): boolean {
+  if (blueprintWorkspaces().length === 0) return false;
+  return isFreshWorkspaceSetup();
+}
+
+/** Whether a workspace the blueprint seeds already has services (so seeding would reset it). */
+export function defaultWorkspaceHasServices(): boolean {
+  const file = readWorkspacesFile();
+  const names = isMultiBlueprint()
+    ? blueprintWorkspaces().map((b) => b.name)
+    : ["default"];
+  return names.some(
+    (n) => Object.keys(file.workspaces[n]?.services ?? {}).length > 0,
+  );
+}
+
+function sameEntry(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+  const ka = Object.keys(a).sort();
+  const kb = Object.keys(b).sort();
+  return (
+    ka.length === kb.length &&
+    ka.every(
+      (k, i) =>
+        k === kb[i] &&
+        sameEntry(
+          (a as Record<string, unknown>)[k],
+          (b as Record<string, unknown>)[k],
+        ),
+    )
+  );
+}
+
+/**
+ * Whether seeding now would change nothing: every workspace the blueprint
+ * seeds holds exactly what seeding writes (same repos, all managed on the
+ * blueprint's branch, same autostart defaults), records the blueprint as
+ * applied, and (multi blueprint) is active. A workspace the user changed
+ * since (a repo switched to a local checkout, one added or removed) is not
+ * "already seeded": seeding would reset it.
+ */
+export function blueprintAlreadySeeded(
+  file: WorkspacesFile = readWorkspacesFile(),
+): boolean {
+  const bps = blueprintWorkspaces();
+  if (bps.length === 0) return false;
+  const multi = isMultiBlueprint();
+  return bps.every((bp) => {
+    const name = multi ? bp.name : "default";
+    const ws = file.workspaces[name];
+    if (!ws) return false;
+    if (multi && !(file.active ?? []).includes(name)) return false;
+    const applied = ws.seeded_repos ?? [];
+    if (
+      applied.length !== bp.repos.length ||
+      bp.repos.some((r, i) => applied[i] !== r)
+    )
+      return false;
+    return sameEntry(ws.services ?? {}, blueprintServices(bp));
+  });
+}
+
+/**
+ * Seed (or reset) the `default` workspace from the blueprint — every repo as a
+ * bare, first-class managed entry on `branch` — and ensure the catalog has
+ * clone URLs (`<org>/<repo>`, only filled where missing). Returns the seeded
+ * repos. With the multi blueprint (`defaults.workspaces`), seeds every named
+ * workspace instead (see seedBlueprintWorkspaces).
+ */
+export function seedDefaultWorkspace(): string[] {
+  if (isMultiBlueprint())
+    return seedBlueprintWorkspaces().flatMap((w) => w.repos);
+  const bp = singleBlueprint();
+  if (!bp) return [];
+  const repos = bp.repos;
 
   const file = readWorkspacesFile();
   file.workspaces.default = {
     ...(file.workspaces.default ?? {}),
-    services,
+    services: blueprintServices(bp),
     seeded_repos: [...repos],
   };
   if (!file.active?.length) {
@@ -78,27 +189,44 @@ export function seedDefaultWorkspace(): string[] {
     file.focus = "default";
   }
   writeWorkspacesFile(file);
-
-  const catalog = readCatalog();
-  const o = org();
-  for (const repo of repos) {
-    if (!catalog[repo]?.gh) catalog[repo] = { gh: `${o}/${repo}` };
-  }
-  writeCatalog(catalog);
-
+  fillCatalog(repos);
   return repos;
 }
 
 /**
- * Converge an EXISTING `default` workspace on the blueprint. Seeding is
- * one-shot, so a workspace seeded before a repo joined
- * `defaults.workspace.repos` (tasks-api, say) would never gain it on its own.
- * Adds each missing blueprint repo exactly as seeding would (bare
- * managed entry on `branch`, team autostart default, catalog clone URL
- * where absent) and returns the added names. No-op — and no file writes —
- * when already converged, or when the `default` workspace is empty/missing:
- * that state belongs to the seeding/declined flow, not top-up.
+ * Create (or reset) each workspace `defaults.workspaces` names with its repos,
+ * activate them all, and focus the one marked `focus: true` (else the first).
+ * Workspaces the blueprint does not name are left as they are. Returns what
+ * was seeded, in blueprint order.
  */
+export function seedBlueprintWorkspaces(): { name: string; repos: string[] }[] {
+  const bps = blueprintWorkspaces();
+  if (bps.length === 0) return [];
+  const file = readWorkspacesFile();
+  for (const bp of bps) {
+    const prev: WorkspaceConfig | undefined = file.workspaces[bp.name];
+    file.workspaces[bp.name] = {
+      ...(prev ?? {}),
+      services: blueprintServices(bp),
+      seeded_repos: [...bp.repos],
+    };
+  }
+  const names = bps.map((b) => b.name);
+  // The untouched placeholder `default` of a fresh file is not the user's:
+  // only the blueprint's workspaces are active.
+  const kept = (file.active ?? []).filter(
+    (n) =>
+      names.includes(n) ||
+      n !== "default" ||
+      Object.keys(file.workspaces[n]?.services ?? {}).length > 0,
+  );
+  file.active = [...names, ...kept.filter((n) => !names.includes(n))];
+  file.focus = (bps.find((b) => b.focus) ?? bps[0]).name;
+  writeWorkspacesFile(file);
+  fillCatalog([...new Set(bps.flatMap((b) => b.repos))]);
+  return bps.map((b) => ({ name: b.name, repos: [...b.repos] }));
+}
+
 /**
  * Converge an EXISTING `default` workspace on the blueprint. Seeding is
  * one-shot, so a workspace seeded before a repo joined
@@ -106,74 +234,88 @@ export function seedDefaultWorkspace(): string[] {
  *
  * Converges on blueprint DELTAS, not set difference: only repos that JOINED
  * the blueprint since it was last applied (`seeded_repos`) are candidates, so
- * a standard repo the user removed from the workspace stays removed. Presence
- * is checked at REPO level (workspace keys may be `repo/subsystem`
- * addresses), so a repo held as subsystem entries never gains a duplicate
- * bare entry. Added repos get exactly what seeding writes: bare
- * managed entry on `branch`, team autostart default, catalog clone
- * URL where absent. Returns the added names.
+ * a standard repo the user removed from the workspace stays removed. A
+ * candidate is skipped when any workspace already holds it, checked at REPO
+ * level (workspace keys may be `repo/subsystem` addresses). Added repos get
+ * exactly what seeding writes: bare managed entry on `branch`, team
+ * autostart default, catalog clone URL where absent. Returns the added names.
  *
- * No-op — and no file writes once converged — when the blueprint is empty or
- * the `default` workspace is empty/missing (that state belongs to the
- * seeding/declined flow). Workspaces from before `seeded_repos` existed
- * treat the whole blueprint as new once — the migration cannot distinguish
- * "removed" from "seeded before the repo joined"; afterwards removals stick.
+ * Never runs once the user has other workspaces: `default` is then one
+ * workspace among theirs, and repos they moved out must stay out. Also a
+ * no-op (no file writes once converged) for the multi blueprint, an empty
+ * blueprint, or an empty/missing `default` (that state belongs to the
+ * seeding flow). Workspaces from before `seeded_repos` existed treat the
+ * whole blueprint as new once; afterwards removals stick.
  */
 export function topUpDefaultWorkspace(): string[] {
-  const repos = defaultWorkspaceRepos();
-  if (repos.length === 0) return [];
+  const bp = singleBlueprint();
+  if (!bp || bp.repos.length === 0) return [];
+  const repos = bp.repos;
 
   const file = readWorkspacesFile();
+  if (Object.keys(file.workspaces).some((n) => n !== "default")) return [];
   const def = file.workspaces["default"];
   if (!def || Object.keys(def.services ?? {}).length === 0) return [];
 
   const applied = new Set(def.seeded_repos ?? []);
   const catalog = readCatalog();
   const present = new Set(
-    Object.keys(def.services).map((k) => parseAddress(k, catalog).repoName),
-  );
-  const branch = defaultBranch();
-  const autostartOff = new Set(
-    readDenConfig().defaults?.workspace?.autostart_off ?? [],
+    Object.values(file.workspaces).flatMap((ws) =>
+      Object.keys(ws.services ?? {}).map(
+        (k) => parseAddress(k, catalog).repoName,
+      ),
+    ),
   );
 
-  const added: string[] = [];
-  for (const repo of repos) {
-    if (applied.has(repo) || present.has(repo)) continue;
-    def.services[repo] = {
-      mode: "managed",
-      branch,
-      ...(autostartOff.has(repo) ? { autostart: false } : {}),
-    };
-    added.push(repo);
-  }
+  const missing = repos.filter((r) => !applied.has(r) && !present.has(r));
+  Object.assign(def.services, blueprintServices(bp, missing));
 
   const blueprintChanged =
     def.seeded_repos?.length !== repos.length ||
     repos.some((r, i) => def.seeded_repos?.[i] !== r);
-  if (added.length === 0 && !blueprintChanged) return [];
+  if (missing.length === 0 && !blueprintChanged) return [];
 
   def.seeded_repos = [...repos];
   writeWorkspacesFile(file);
+  if (missing.length > 0) fillCatalog(missing, catalog);
+  return missing;
+}
 
-  if (added.length > 0) {
-    const o = org();
-    for (const repo of added) {
-      if (!catalog[repo]?.gh) catalog[repo] = { gh: `${o}/${repo}` };
-    }
-    writeCatalog(catalog);
+/**
+ * Record that the user removed `repoName` from workspace `wsName`, so top-up
+ * never re-adds it. Only the `default` workspace is topped up, and only a
+ * blueprint repo could come back; `seeded_repos` already covers repos the
+ * blueprint applied. This closes the gap for a `default` from before
+ * `seeded_repos` existed, which top-up would otherwise migrate by re-adding
+ * the whole blueprint. Mutates `file` in place; the caller writes it.
+ */
+export function recordRemovedFromWorkspace(
+  file: WorkspacesFile,
+  wsName: string,
+  repoName: string,
+): void {
+  if (wsName !== "default") return;
+  const def = file.workspaces["default"];
+  if (!def) return;
+  let blueprint: string[] = [];
+  try {
+    blueprint = defaultWorkspaceRepos();
+  } catch {
+    return; // a malformed blueprint is reported where seeding reads it
   }
-
-  return added;
+  if (!blueprint.includes(repoName)) return;
+  const seeded = def.seeded_repos ?? [];
+  if (!seeded.includes(repoName)) def.seeded_repos = [...seeded, repoName];
 }
 
 /**
- * Persist an empty `default` workspace so the one-time auto-seed prompt isn't
- * asked again after the user declines it.
+ * Persist an empty `default` workspace, with an empty `seeded_repos`, so the
+ * one-time auto-seed prompt isn't asked again after the user declines it.
  */
 export function markDefaultWorkspaceDeclined(): void {
   const file = readWorkspacesFile();
   file.workspaces.default = file.workspaces.default ?? { services: {} };
+  file.workspaces.default.seeded_repos ??= [];
   if (!file.active?.length) {
     file.active = ["default"];
     file.focus = "default";