@monster-orange/den 0.2.5 → 0.2.7

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

@@ -0,0 +1,264 @@
+/**
+ * Which work org a workspace belongs to (ORG-1a, ORG-SPEC §2).
+ *
+ * An org is a key of `orgs:` or a GitHub owner. ORG-1a keeps today's model:
+ * an org with no `sources` is the GitHub owner of the same name, and
+ * `github_org` is the default org. A workspace's org resolves through this
+ * chain, first match wins:
+ *
+ *   1. `org:` on the workspace in workspaces.yml (per machine)
+ *   2. `org:` on the same-named blueprint workspace (`defaults.workspaces`)
+ *   3. the single non-empty catalog owner of its repos (case-insensitive)
+ *   4. `github_org`
+ *
+ * Computed on read and never written back to workspaces.yml, so an inferred
+ * org never looks like an explicit one. Every rule broken here is a warning,
+ * never an error (C1): an old config resolves as before, to `github_org`.
+ */
+import {
+  readDenConfig,
+  readWorkspaceBlueprints,
+  requireGithubOrg,
+  type DenConfig,
+  type ResolvedWorkspaceBlueprint,
+} from "../den-config.js";
+import { readCatalog } from "./catalog.js";
+import { parseAddress, readWorkspacesFile } from "./workspaces.js";
+import { orgOf } from "../manifest/service-links.js";
+import { cachedRead } from "../read-cache.js";
+import type {
+  ServiceCatalog,
+  WorkspaceConfig,
+  WorkspacesFile,
+} from "../types/index.js";
+
+/** Which step of the chain gave the org. */
+export type OrgSource = "workspace" | "blueprint" | "catalog" | "default";
+
+export interface WorkspaceOrg {
+  workspace: string;
+  /** The resolved org id (the `orgs:` key's spelling when one matches), or null. */
+  org: string | null;
+  source: OrgSource | null;
+  /** Each broken org rule, as a sentence (C1: warnings, never errors). */
+  warnings: string[];
+}
+
+export interface OrgContext {
+  config: DenConfig;
+  catalog: ServiceCatalog;
+  file: WorkspacesFile;
+  blueprints: ResolvedWorkspaceBlueprint[];
+}
+
+const lower = (s: string): string => s.toLowerCase();
+
+/** The current config, catalog, workspaces.yml and blueprint. */
+export function readOrgContext(): OrgContext {
+  const config = readDenConfig();
+  let blueprints: ResolvedWorkspaceBlueprint[] = [];
+  try {
+    blueprints = readWorkspaceBlueprints(config).workspaces;
+  } catch {
+    // A malformed blueprint is reported where seeding reads it; it must not
+    // turn an org listing into a failure (C1).
+  }
+  return {
+    config,
+    catalog: readCatalog(),
+    file: readWorkspacesFile(),
+    blueprints,
+  };
+}
+
+/** `id` spelled as its `orgs:` key when one matches case-insensitively. */
+export function canonicalOrg(id: string, config: DenConfig): string {
+  const key = Object.keys(config.orgs ?? {}).find(
+    (k) => lower(k) === lower(id),
+  );
+  return key ?? id;
+}
+
+/** The default org: `github_org`, or null when unset. */
+export function defaultOrg(config: DenConfig): string | null {
+  const d = config.github_org?.trim();
+  return d ? canonicalOrg(d, config) : null;
+}
+
+/** The repos a workspace holds; a workspace not set up yet holds its blueprint's. */
+function workspaceRepos(
+  ws: WorkspaceConfig | undefined,
+  bp: ResolvedWorkspaceBlueprint | undefined,
+  catalog: ServiceCatalog,
+): string[] {
+  const held = [
+    ...Object.keys(ws?.services ?? {}).map(
+      (k) => parseAddress(k, catalog).repoName,
+    ),
+    ...Object.keys(ws?.repos ?? {}),
+  ];
+  return [...new Set(held.length > 0 ? held : (bp?.repos ?? []))];
+}
+
+/** Owners Den knows of: `orgs:` keys, catalog owners and `github_org`. */
+function knownOrgs(ctx: OrgContext): Set<string> {
+  const ids = new Set(Object.keys(ctx.config.orgs ?? {}).map(lower));
+  for (const repo of Object.keys(ctx.catalog)) {
+    const o = orgOf(repo, ctx.catalog);
+    if (o) ids.add(lower(o));
+  }
+  const d = ctx.config.github_org?.trim();
+  if (d) ids.add(lower(d));
+  return ids;
+}
+
+/** Resolve one workspace's org through the chain. */
+export function resolveWorkspaceOrg(
+  name: string,
+  ctx: OrgContext,
+): WorkspaceOrg {
+  const warnings: string[] = [];
+  const ws = ctx.file.workspaces[name];
+  const bp = ctx.blueprints.find((b) => b.name === name);
+  const rawWsOrg = ws?.org as unknown;
+  const wsOrg =
+    typeof rawWsOrg === "string" && rawWsOrg.trim()
+      ? rawWsOrg.trim()
+      : undefined;
+  if (rawWsOrg !== undefined && rawWsOrg !== null && !wsOrg)
+    warnings.push(
+      `workspace ${name}: org in workspaces.yml is not an org id; ignored`,
+    );
+
+  const repos = workspaceRepos(ws, bp, ctx.catalog);
+  const owners = new Map<string, string>(); // lowercased → first spelling
+  for (const repo of repos) {
+    const o = orgOf(repo, ctx.catalog);
+    if (o && !owners.has(lower(o))) owners.set(lower(o), o);
+  }
+
+  let org: string | null = null;
+  let source: OrgSource | null = null;
+  if (wsOrg) {
+    org = wsOrg;
+    source = "workspace";
+    if (bp?.org && lower(bp.org) !== lower(wsOrg))
+      warnings.push(
+        `workspace ${name}: org ${wsOrg} in workspaces.yml overrides the blueprint's org ${bp.org}`,
+      );
+  } else if (bp?.org) {
+    org = bp.org;
+    source = "blueprint";
+  } else if (owners.size === 1) {
+    org = [...owners.values()][0];
+    source = "catalog";
+  } else {
+    org = ctx.config.github_org?.trim() || null;
+    source = org ? "default" : null;
+    if (owners.size > 1)
+      warnings.push(
+        `workspace ${name}: its repos belong to several owners (${[...owners.values()].join(", ")}); ` +
+          `using ${org ?? "no org"}. Set org: on the workspace to choose one`,
+      );
+  }
+  if (org) org = canonicalOrg(org, ctx.config);
+
+  if (
+    org &&
+    (source === "workspace" || source === "blueprint") &&
+    !knownOrgs(ctx).has(lower(org))
+  )
+    warnings.push(
+      `workspace ${name}: org ${org} is not in orgs:, the catalog or github_org`,
+    );
+
+  // A repo in another owner than its workspace's org. A mixed workspace with
+  // no org of its own already said so above.
+  if (
+    org &&
+    (owners.size <= 1 || source === "workspace" || source === "blueprint")
+  )
+    for (const repo of repos) {
+      const o = orgOf(repo, ctx.catalog);
+      if (o && lower(o) !== lower(org))
+        warnings.push(
+          `workspace ${name}: repo ${repo} belongs to ${o}, not the workspace's org ${org}`,
+        );
+    }
+
+  return { workspace: name, org, source, warnings };
+}
+
+/** Every workspace on this machine, then blueprint workspaces not set up yet. */
+function workspaceNames(ctx: OrgContext): string[] {
+  return [
+    ...new Set([
+      ...Object.keys(ctx.file.workspaces),
+      ...ctx.blueprints.map((b) => b.name),
+    ]),
+  ];
+}
+
+/** Every workspace's resolved org (cached for the web server's read TTL). */
+export function resolveAllWorkspaceOrgs(ctx?: OrgContext): WorkspaceOrg[] {
+  const compute = (c: OrgContext) =>
+    workspaceNames(c).map((n) => resolveWorkspaceOrg(n, c));
+  if (ctx) return compute(ctx);
+  return cachedRead("workspace-orgs", () => compute(readOrgContext()));
+}
+
+/**
+ * The GitHub owner to clone and register a workspace's repos under: its
+ * resolved org. With none at all (no org anywhere and no `github_org`) this
+ * throws exactly as requireGithubOrg does, so an old config fails as before.
+ */
+export function githubOrgFor(workspace: string, ctx?: OrgContext): string {
+  const hit = ctx
+    ? resolveWorkspaceOrg(workspace, ctx)
+    : (resolveAllWorkspaceOrgs().find((w) => w.workspace === workspace) ??
+      resolveWorkspaceOrg(workspace, readOrgContext()));
+  if (hit.org) return hit.org;
+  return requireGithubOrg(ctx?.config);
+}
+
+export interface OrgEntry {
+  id: string;
+  label: string;
+  color?: string;
+}
+
+/**
+ * The org listing with `default` and `workspaces` added to each entry and
+ * nothing else changed (C3): same entries, same order, same fields. Only
+ * workspaces on this machine (workspaces.yml) are listed.
+ */
+export function withOrgMembership<T extends OrgEntry>(
+  orgs: T[],
+  resolved: WorkspaceOrg[],
+  file: WorkspacesFile,
+  config: DenConfig,
+): Array<T & { default: boolean; workspaces: string[] }> {
+  // The listing can hold one owner twice in different case (catalog owners
+  // are listed as spelled); an org lands on the entry spelled exactly like
+  // it, else the first that matches case-insensitively.
+  const entryFor = (id: string): number => {
+    const exact = orgs.findIndex((o) => o.id === id);
+    return exact !== -1
+      ? exact
+      : orgs.findIndex((o) => lower(o.id) === lower(id));
+  };
+  const d = defaultOrg(config);
+  const defaultAt = d === null ? -1 : entryFor(d);
+  const members = orgs.map((): string[] => []);
+  const local = new Set(Object.keys(file.workspaces));
+  for (const w of resolved) {
+    if (!w.org || !local.has(w.workspace)) continue;
+    const at = entryFor(w.org);
+    if (at !== -1) members[at].push(w.workspace);
+  }
+  return orgs.map((o, i) => ({
+    ...o,
+    default: i === defaultAt,
+    workspaces: members[i],
+  }));
+}

package/src/shared/manifest/placement.ts

@@ -52,7 +52,7 @@ export type IsProduction = (env: string) => boolean;
 const LOCAL = "local";
 
 function isHttp(h: ServiceHealthConfig | undefined): h is { url: string } {
-  return !!h && h.type !== "shell" && typeof h.url === "string";
+  return !!h && "url" in h && typeof h.url === "string";
 }
 
 function hasCommands(

package/src/shared/manifest/schema.ts

@@ -32,7 +32,54 @@ const commandDef = z.union([
 //   { url: "http://..." }                         — implicit HTTP
 //   { type: "http", url: "http://..." }           — explicit HTTP
 //   { type: "shell", cmd: "pg_isready ..." }      — shell
+//   { type: "container", project, service }       — a compose container
+//   { type: "container", container_name }         — a container by name
+const CONTAINER_HEALTH_KEYS = new Set([
+  "type",
+  "project",
+  "service",
+  "container_name",
+  "label",
+]);
+export const CONTAINER_HEALTH_SHAPE =
+  'container checks need "project" and "service" (compose labels), or "container_name"';
+const containerHealth = z
+  .object({
+    type: z.literal("container"),
+    project: z.string().min(1).optional(),
+    service: z.string().min(1).optional(),
+    container_name: z.string().min(1).optional(),
+    label: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((h, ctx) => {
+    const unknown = Object.keys(h).filter((k) => !CONTAINER_HEALTH_KEYS.has(k));
+    if (unknown.length)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")} in a container check: ${CONTAINER_HEALTH_SHAPE}`,
+      });
+    const byLabels = h.project !== undefined || h.service !== undefined;
+    const byName = h.container_name !== undefined;
+    if (byLabels && byName)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `a container check matches by "project"/"service" or by "container_name", not both`,
+      });
+    else if (byLabels && (h.project === undefined || h.service === undefined))
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `a container check by compose labels needs both "project" and "service"`,
+      });
+    else if (!byLabels && !byName)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: CONTAINER_HEALTH_SHAPE,
+      });
+  });
+
 const healthConfig = z.union([
+  containerHealth,
   // Shell health check — must have cmd
   z.object({
     type: z.literal("shell"),

package/src/shared/manifest/service-links.ts

@@ -47,7 +47,7 @@ export function openUrlFor(
   const declared = httpUrl(svc.urls?.[env]);
   if (declared) return declared;
   const health = svc.health?.[env];
-  if (!health || ("type" in health && health.type === "shell")) return null;
+  if (!health || !("url" in health)) return null;
   return httpOrigin((health as { url?: string }).url);
 }
 

package/src/shared/manifest/validate-manifest.ts

@@ -57,7 +57,7 @@ function suggestionFor(issue: z.ZodIssue): string | undefined {
 
   // health with missing url/cmd
   if (pathStr.includes("health")) {
-    return 'HTTP checks need "url"; shell checks need "type: shell" and "cmd"';
+    return 'HTTP checks need "url"; shell checks need "type: shell" and "cmd"; container checks need "type: container" and "project" + "service", or "container_name"';
   }
 
   return undefined;

package/src/shared/plural.ts

@@ -0,0 +1,13 @@
+/**
+ * Counts in output: "1 repo", "3 repos", never "1 repos" or "repo(s)".
+ */
+
+/** `word` in the form `n` takes: "repo" for 1, "repos" (or `many`) otherwise. */
+export function noun(n: number, word: string, many = `${word}s`): string {
+  return n === 1 ? word : many;
+}
+
+/** `n` and its noun: plural(1, "repo") → "1 repo", plural(2, "repo") → "2 repos". */
+export function plural(n: number, word: string, many?: string): string {
+  return `${n} ${noun(n, word, many)}`;
+}

package/src/shared/service-url.ts

@@ -24,11 +24,8 @@ function healthUrlForConfig(healthConfig?: ServiceHealthConfig): string | null {
     return null;
   }
 
-  if ("type" in healthConfig && healthConfig.type === "shell") {
-    return null;
-  }
-
-  return healthConfig.url;
+  // Shell and container checks have no URL.
+  return "url" in healthConfig ? healthConfig.url : null;
 }
 
 function normalizeServiceBaseUrl(

package/src/shared/stacks/compose-health.ts

@@ -58,13 +58,19 @@ export function composeHealthTarget(
 /** Budget for the shared listing; past it the checks are pending. */
 export const COMPOSE_LISTING_TIMEOUT_MS = 5_000;
 
-type Listing = { rows: ComposeRow[] } | { error: string; pending?: boolean };
+/** The shared listing: every container, or why docker could not answer. */
+export type ComposeListing =
+  | { rows: ComposeRow[] }
+  | { error: string; pending?: boolean };
+type Listing = ComposeListing;
 
 let inFlight: Promise<Listing> | null = null;
 
 /**
- * Every compose container, from one `docker ps -a`. Concurrent callers share
- * the call in flight, so a health cycle lists once however many checks it has.
+ * Every container, from one `docker ps -a`. Concurrent callers share the
+ * call in flight, so a health cycle lists once however many checks it has
+ * (compose checks and `type: container` checks alike). Not filtered to
+ * compose containers: a container check may name a plain container.
  */
 export function composeListing(): Promise<Listing> {
   return (inFlight ??= listOnce().finally(() => {
@@ -96,10 +102,8 @@ function listOnce(): Promise<Listing> {
       [
         "ps",
         "-a",
-        "--filter",
-        "label=com.docker.compose.project",
         "--format",
-        '{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.service"}}\t{{.State}}\t{{.Status}}',
+        '{{.Label "com.docker.compose.project"}}\t{{.Label "com.docker.compose.service"}}\t{{.State}}\t{{.Status}}\t{{.Names}}',
       ],
       {
         encoding: "utf-8",
@@ -125,9 +129,14 @@ function listOnce(): Promise<Listing> {
           .split("\n")
           .filter(Boolean)
           .map((line) => {
-            const [project = "", service = "", state = "", status = ""] =
-              line.split("\t");
-            return { project, service, state, status };
+            const [
+              project = "",
+              service = "",
+              state = "",
+              status = "",
+              name = "",
+            ] = line.split("\t");
+            return { project, service, state, status, name };
           });
         resolve({ rows });
       },
@@ -135,16 +144,99 @@ function listOnce(): Promise<Listing> {
   });
 }
 
+/**
+ * The verdict when docker gave no listing, shared by compose and container
+ * checks so the two cannot drift: container state unknown is not "not
+ * running" (`ok: null`, never down, however often it repeats). Only a
+ * listing past its budget is `pending` (no answer in time), which, like any
+ * timeout, is down when it repeats on the next cycle.
+ */
+export function unknownListingVerdict(listing: {
+  error: string;
+  pending?: boolean;
+}): ComposeVerdict {
+  return {
+    ok: null,
+    detail: `container state unknown: ${listing.error}`,
+    ...(listing.pending ? { pending: true } : {}),
+  };
+}
+
 /** The health of one Den-generated compose check, from the shared listing. */
 export async function composeHealth(
   target: ComposeHealthTarget,
 ): Promise<ComposeVerdict> {
   const listing = await composeListing();
-  if ("error" in listing)
+  if ("error" in listing) return unknownListingVerdict(listing);
+  return judgeStackRows(listing.rows, target.project, target.service);
+}
+
+// ── `health: { type: container }` ───────────────────────────────────────────
+
+/**
+ * A declared container check: a compose container by its project and service
+ * labels, or any container by name (`container_name`).
+ */
+export type ContainerHealthTarget =
+  | { project: string; service: string; container_name?: undefined }
+  | { container_name: string; project?: undefined; service?: undefined };
+
+/** What a container check shows as its check: `container <project>/<service>`. */
+export function containerCheckLabel(t: ContainerHealthTarget): string {
+  return `container ${containerTargetName(t)}`;
+}
+
+function containerTargetName(t: ContainerHealthTarget): string {
+  return t.container_name ?? `${t.project}/${t.service}`;
+}
+
+function matchesTarget(r: ComposeRow, t: ContainerHealthTarget): boolean {
+  if (t.container_name)
+    return (r.name ?? "")
+      .split(",")
+      .map((n) => n.trim().replace(/^\//, ""))
+      .includes(t.container_name);
+  return r.project === t.project && r.service === t.service;
+}
+
+/** One container's verdict: its healthcheck when it has one, else running. */
+function rowVerdict(r: ComposeRow): ComposeVerdict & { rank: number } {
+  const what = `${r.name || `${r.project}/${r.service}`}\t${r.state}\t${r.status}`;
+  if (r.state !== "running") return { ok: false, detail: what, rank: 4 };
+  if (/\(unhealthy\)/.test(r.status))
+    return { ok: false, detail: what, rank: 3 };
+  // Starting is pending, but not "no answer": it never turns down on repeat.
+  if (/\(health: starting\)/.test(r.status))
+    return { ok: null, detail: what, rank: 2 };
+  if (/\(healthy\)/.test(r.status)) return { ok: true, detail: what, rank: 0 };
+  return { ok: true, detail: what, rank: 1 };
+}
+
+/**
+ * The verdict of a container check over the shared listing. More than one
+ * match: the best one (healthy, then running). No match: down. No listing:
+ * as a compose check (unknownListingVerdict), the reason in `detail`.
+ */
+export function judgeContainerListing(
+  listing: ComposeListing,
+  target: ContainerHealthTarget,
+): ComposeVerdict {
+  if ("error" in listing) return unknownListingVerdict(listing);
+  const best = listing.rows
+    .filter((r) => matchesTarget(r, target))
+    .map(rowVerdict)
+    .sort((a, b) => a.rank - b.rank)[0];
+  if (!best)
     return {
-      ok: null,
-      detail: `container state unknown: ${listing.error}`,
-      ...(listing.pending ? { pending: true } : {}),
+      ok: false,
+      detail: `${containerTargetName(target)}: no container`,
     };
-  return judgeStackRows(listing.rows, target.project, target.service);
+  return { ok: best.ok, detail: best.detail };
+}
+
+/** The health of a declared container check, from the shared listing. */
+export async function containerHealth(
+  target: ContainerHealthTarget,
+): Promise<ComposeVerdict> {
+  return judgeContainerListing(await composeListing(), target);
 }

package/src/shared/stacks/runtime.ts

@@ -413,6 +413,8 @@ export interface ComposeRow {
   service: string;
   state: string;
   status: string;
+  /** The container's name(s), comma-separated as docker lists them. */
+  name?: string;
 }
 
 /**

package/src/shared/types/index.ts

@@ -210,10 +210,22 @@ export type LogSource =
  *   type: shell
  *   cmd: "docker exec $(docker ps --filter ancestor=postgres:16 --format '{{.ID}}' | head -1) pg_isready -U postgres"
  *   label: "postgres"   # optional — shown in UI instead of cmd
+ *
+ * Container (answered from the one `docker ps` a health cycle shares):
+ *   type: container
+ *   project: shop-main     # com.docker.compose.project label
+ *   service: db            # com.docker.compose.service label
+ *   -- or, for a container not run by compose --
+ *   type: container
+ *   container_name: shop-db
  */
 export type ServiceHealthConfig =
   | { type?: "http"; url: string; label?: string }
-  | { type: "shell"; cmd: string; label?: string };
+  | { type: "shell"; cmd: string; label?: string }
+  | ({ type: "container"; label?: string } & (
+      | { project: string; service: string; container_name?: undefined }
+      | { container_name: string; project?: undefined; service?: undefined }
+    ));
 
 /**
  * A command can be a plain shell string (detached by default) or an object
@@ -674,6 +686,13 @@ export interface WorkspaceConfig {
    * newly JOIN the blueprint are added.
    */
   seeded_repos?: string[];
+  /**
+   * The org this workspace belongs to (ORG-1a), set per machine. Wins over
+   * the blueprint's `org:`; when neither is set the org is inferred from the
+   * repos' catalog owners, then `github_org`. Never written by Den: the
+   * resolved org is computed on read (see workspace-org.ts).
+   */
+  org?: string;
 }
 
 export interface WorkspacesFile {