@monster-orange/den 0.0.0-stage → 0.1.0

package/src/shared/dev-metrics/emit.ts

@@ -0,0 +1,354 @@
+/**
+ * Dev-tooling telemetry emitter (native TypeScript).
+ *
+ * Den is a native consumer of common-iac's dev-metrics pipeline (like stack's
+ * Go `internal/devmetrics`): it emits the SAME telemetry contract in-process
+ * rather than shelling out to the vendored Python/bash emitters — see
+ * common-iac docs/guides/dev-metrics/README.md, "Appendix: per-tool
+ * differentiation".
+ *
+ * Contract (kept byte-compatible with dev_metrics.py — pinned by
+ * dev-metrics.emit.test.ts against golden envelopes captured via
+ * DEV_METRICS_ENVELOPE_OUT):
+ *   1. ALWAYS append one compact JSON line to <repoRoot>/.dev-metrics/events.jsonl.
+ *   2. THEN best-effort ship to Sentry (Tier-1 -> log item, Tier-2 -> event item).
+ *
+ * Guarantees: never throws, never blocks the caller (the Sentry ship is
+ * fire-and-forget, bounded to ~2s). CI=true / DEV_METRICS_DISABLED=1 suppress
+ * shipping but still buffer the JSONL locally.
+ *
+ * Tool differentiation: den emits `devtool.den.<event>` with a `tool=den`
+ * attribute. Per the appendix, event names are FIXED (`devtool.den.invocation`
+ * / `.failed`) and dimensions (command, surface, duration_ms, exit) ride as
+ * attributes — never per-command event names.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { createHash, randomUUID } from "crypto";
+import { getDistRoot } from "../paths.js";
+
+import { product } from "../product.js";
+const SERVICE = "dev-tooling";
+const ENVIRONMENT = "dev-tooling";
+
+/**
+ * Alertable events, hardcoded identically to dev_metrics.py's TIER2_EVENTS
+ * (v5.0.2). Keep in lockstep with common-iac — a divergence breaks the `tier`
+ * field's byte-compatibility. `devtool.den.*` are deliberately absent, so
+ * they ship as Tier-1 logs until common-iac adds them to its allowlist.
+ */
+const TIER2_EVENTS = new Set<string>([
+  "devtool.pin.drift_detected",
+  "devtool.install_fix.ran",
+  "devtool.file_link.leaked",
+  "devtool.setup.failed",
+  "devtool.install.failed",
+]);
+
+const GIT_TIMEOUT_MS = 2000;
+const SHIP_TIMEOUT_MS = 2000;
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function git(args: string[], cwd: string): string {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf-8",
+      timeout: GIT_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function repoRoot(): string {
+  return process.env.DEV_METRICS_REPO_ROOT || getDistRoot();
+}
+
+/** Stable-per-process common fields (repo/user never change); branch/sha re-read cheaply. */
+let _stable: { root: string; repo: string; user: string; pins: string } | null =
+  null;
+
+function stableFields(root: string): {
+  repo: string;
+  user: string;
+  pins: string;
+} {
+  if (_stable && _stable.root === root) return _stable;
+  const user =
+    git(["config", "user.name"], root) || process.env.USER || "unknown";
+  let pins = "";
+  try {
+    const data = fs.readFileSync(path.join(root, "api-dependencies.yml"));
+    // sha256[:12] — matches dev_metrics.py _pins_fingerprint.
+    pins = createHash("sha256").update(data).digest("hex").slice(0, 12);
+  } catch {
+    pins = "";
+  }
+  _stable = { root, repo: path.basename(root), user, pins };
+  return _stable;
+}
+
+function commonFields(event: string, root: string): Record<string, string> {
+  const { repo, user, pins } = stableFields(root);
+  return {
+    event,
+    tier: TIER2_EVENTS.has(event) ? "event" : "log",
+    service: SERVICE,
+    environment: ENVIRONMENT,
+    repo,
+    user,
+    branch: git(["rev-parse", "--abbrev-ref", "HEAD"], root),
+    sha: git(["rev-parse", "--short", "HEAD"], root),
+    pins,
+  };
+}
+
+function isoNoMillis(): string {
+  return new Date().toISOString().replace(/\.\d+Z$/, "Z");
+}
+
+function suppressShip(): boolean {
+  return process.env.CI === "true" || process.env.DEV_METRICS_DISABLED === "1";
+}
+
+function resolveDsn(root: string): string {
+  const env = process.env.DEV_METRICS_SENTRY_DSN;
+  if (env) return env;
+  try {
+    const cfg = fs.readFileSync(
+      path.join(
+        root,
+        ".stack",
+        "common-iac",
+        "scripts",
+        "lib",
+        "dev-metrics.config",
+      ),
+      "utf-8",
+    );
+    for (const line of cfg.split("\n")) {
+      if (line.startsWith("DEV_METRICS_SENTRY_DSN=")) {
+        return line
+          .slice("DEV_METRICS_SENTRY_DSN=".length)
+          .trim()
+          .replace(/^"|"$/g, "");
+      }
+    }
+  } catch {
+    /* not synced */
+  }
+  return "";
+}
+
+function parseDsn(
+  dsn: string,
+): { scheme: string; host: string; key: string; projectId: string } | null {
+  const m = dsn.match(/^(https?):\/\/([^@]+)@([^/]+)\/(.+)$/);
+  if (!m) return null;
+  const [, scheme, key, host, projectId] = m;
+  if (!scheme || !host || !key || !projectId) return null;
+  return { scheme, host, key, projectId };
+}
+
+// ── envelope builder (pure; byte-compatible with dev_metrics.py _build_envelope)
+
+/**
+ * Build the Sentry envelope text for one record. `record` is the shipped object
+ * (JSONL object minus `ts`), `epoch` is integer seconds, `id` is a 32-char hex.
+ * Exported so the byte-compat test can replay a golden record's epoch/id.
+ */
+export function buildEnvelope(
+  record: Record<string, string>,
+  epoch: number,
+  id: string,
+): string {
+  if (record.tier === "event") {
+    const body = {
+      event_id: id,
+      timestamp: epoch,
+      platform: "other",
+      logger: "dev-tooling",
+      level: "warning",
+      message: record.event,
+      environment: ENVIRONMENT,
+      tags: { ...record },
+    };
+    const payload = JSON.stringify(body);
+    const itemHeader = JSON.stringify({
+      type: "event",
+      content_type: "application/json",
+      length: Buffer.byteLength(payload, "utf8"),
+    });
+    const envHeader = JSON.stringify({ event_id: id });
+    return `${envHeader}\n${itemHeader}\n${payload}\n`;
+  }
+
+  const attributes: Record<string, { value: string | number; type: string }> =
+    {};
+  for (const [k, v] of Object.entries(record)) {
+    attributes[k] = { value: v, type: "string" };
+  }
+  attributes["sentry.severity_number"] = { value: 9, type: "integer" };
+  attributes["sentry.severity_text"] = { value: "info", type: "string" };
+  const logRecord = {
+    timestamp: epoch,
+    trace_id: id,
+    level: "info",
+    body: record.event,
+    attributes,
+  };
+  const payload = JSON.stringify({ version: 2, items: [logRecord] });
+  const itemHeader = JSON.stringify({
+    type: "log",
+    content_type: "application/vnd.sentry.items.log+json",
+    item_count: 1,
+    length: Buffer.byteLength(payload, "utf8"),
+  });
+  return `{}\n${itemHeader}\n${payload}\n`;
+}
+
+function ship(
+  record: Record<string, string>,
+  epoch: number,
+  root: string,
+): void {
+  const dsn = resolveDsn(root);
+  if (!dsn) return;
+  const parsed = parseDsn(dsn);
+  if (!parsed) return;
+  const envelope = buildEnvelope(record, epoch, randomUUID().replace(/-/g, ""));
+
+  // Test/inspection seam — capture the envelope instead of shipping.
+  const capture = process.env.DEV_METRICS_ENVELOPE_OUT;
+  if (capture) {
+    try {
+      fs.appendFileSync(capture, envelope);
+    } catch {
+      /* fail-open */
+    }
+    return;
+  }
+
+  const url = `${parsed.scheme}://${parsed.host}/api/${parsed.projectId}/envelope/`;
+  const auth = `Sentry sentry_key=${parsed.key}, sentry_version=7, sentry_client=dev-metrics-${product().cli}/1.0`;
+  // Fire-and-forget: never awaited, so the caller never blocks. Bounded by a 2s
+  // abort so a hung ingest can't leak a pending request in the long-lived server.
+  void fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-sentry-envelope",
+      "X-Sentry-Auth": auth,
+    },
+    body: envelope,
+    signal: AbortSignal.timeout(SHIP_TIMEOUT_MS),
+  })
+    // Discard the body. The status is never read, and an unconsumed body keeps
+    // the connection checked out of undici's pool in this long-lived server —
+    // one leak per emitted event. Same reason health.ts cancels its bodies.
+    .then((res) => res.body?.cancel())
+    .catch(() => {
+      /* fail-open: offline / bad DSN / timeout → drop, JSONL already buffered */
+    });
+}
+
+// ── public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Record one telemetry event. Never throws, never blocks. Extra fields are
+ * stringified (matching dev_metrics.py); pass only PII-safe values — registered
+ * command names, flag names (not values), error classes (not messages).
+ */
+export function record(
+  event: string,
+  fields: Record<string, string | number | boolean | null | undefined> = {},
+): void {
+  try {
+    if (!event) return;
+    const root = repoRoot();
+    const epoch = Math.floor(Date.now() / 1000);
+
+    const obj: Record<string, string> = { ts: isoNoMillis() };
+    Object.assign(obj, commonFields(event, root));
+    for (const [k, v] of Object.entries(fields)) {
+      obj[k] = v == null ? "" : String(v);
+    }
+
+    try {
+      const dir = path.join(root, ".dev-metrics");
+      fs.mkdirSync(dir, { recursive: true });
+      fs.appendFileSync(
+        path.join(dir, "events.jsonl"),
+        JSON.stringify(obj) + "\n",
+      );
+    } catch {
+      /* non-writable dir → fail-open */
+    }
+
+    if (suppressShip()) return;
+    // The JSONL object doubles as the Sentry attribute/tag set, minus `ts`.
+    const { ts: _ts, ...shipObj } = obj;
+    void _ts;
+    ship(shipObj, epoch, root);
+  } catch {
+    /* Fail-open: telemetry must never break a caller. */
+  }
+}
+
+/** Den's fixed tool id — event-name namespace segment AND `tool` attribute. */
+export const TOOL = `${product().cli}`;
+
+export type Surface = "cli" | "ux";
+
+/**
+ * Record one `devtool.den.invocation` (Tier-1). One per user-initiated run.
+ * `command` MUST be a registered command/action name (never raw argv).
+ */
+export function recordInvocation(opts: {
+  command: string;
+  surface: Surface;
+  durationMs?: number;
+  exit?: number;
+  extra?: Record<string, string | number | boolean | null | undefined>;
+}): void {
+  record(`devtool.${product().name}.invocation`, {
+    tool: TOOL,
+    command: opts.command,
+    surface: opts.surface,
+    duration_ms: opts.durationMs,
+    exit: opts.exit,
+    ...opts.extra,
+  });
+}
+
+/**
+ * Record one `devtool.den.failed`. Ships Tier-1 today (add to common-iac's
+ * TIER2 allowlist to make it alertable). `reason` MUST be an error *class*, not
+ * a message.
+ */
+export function recordFailure(opts: {
+  command: string;
+  surface: Surface;
+  reason: string;
+  durationMs?: number;
+  extra?: Record<string, string | number | boolean | null | undefined>;
+}): void {
+  record(`devtool.${product().name}.failed`, {
+    tool: TOOL,
+    command: opts.command,
+    surface: opts.surface,
+    reason: opts.reason,
+    duration_ms: opts.durationMs,
+    ...opts.extra,
+  });
+}
+
+/** Start a timer; returns a fn giving elapsed whole milliseconds. */
+export function startTimer(): () => number {
+  const t0 = Date.now();
+  return () => Date.now() - t0;
+}

package/src/shared/edge/config.ts

@@ -0,0 +1,229 @@
+/**
+ * Reads `edge:` (and `web:`) from config/den.yml, with per-engineer
+ * overrides from config/local/user.yml.
+ *
+ *   edge:
+ *     org: acme
+ *     domain: acme.localhost
+ *     aliases: [acme.internal]
+ *     image: traefik:v3.7.17
+ *     workspaces: [main]
+ *     routes: { <name>: <upstream url> }
+ *     publish: true          # false: another proxy fronts the edge
+ *     http_port: 80
+ *     https_port: 443
+ *     # opt-ins (all off by default):
+ *     caroot: ~/path/to/mkcert-ca   # use an existing CA; never mint one
+ *     issue_cert: false             # included config holds the certs
+ *     https_redirect: false         # included config redirects per name
+ *     docker_labels: { network: apps-network }
+ *     include: edge/dynamic         # dynamic-config files, repo-relative
+ *     mounts: { <host path>: <container path> }   # read-only
+ *     networks: [<external network>]
+ *     args: [--accesslog=true]
+ *   web:
+ *     port: 7777             # the web UI; routed as `<brand name>`
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as yaml from "yaml";
+import { brandSlug, defaultBrand } from "../brand.js";
+import { DEFAULT_PORT } from "../constants.js";
+import { getDistRoot } from "../paths.js";
+import { readManifestStacks } from "../stacks/config.js";
+import { getActiveWorkspaces } from "../environment-manager/workspaces.js";
+import { assertDomain } from "./render.js";
+import type { EdgeConfig } from "./types.js";
+
+import { product } from "../product.js";
+export const DEFAULT_TRAEFIK_IMAGE = "traefik:v3.7.17";
+
+interface RawEdge {
+  org?: string;
+  domain?: string;
+  aliases?: string[];
+  image?: string;
+  workspaces?: string[];
+  routes?: Record<string, string>;
+  state_dir?: string;
+  publish?: boolean;
+  http_port?: number;
+  https_port?: number;
+  caroot?: string;
+  issue_cert?: boolean;
+  https_redirect?: boolean;
+  docker_labels?: { network?: string } | boolean;
+  include?: string;
+  mounts?: Record<string, string>;
+  networks?: string[];
+  args?: string[];
+}
+
+function readYaml(file: string): Record<string, unknown> {
+  try {
+    return (
+      (yaml.parse(fs.readFileSync(file, "utf-8")) as Record<string, unknown>) ??
+      {}
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw err;
+  }
+}
+
+function layers(root: string) {
+  return {
+    team: readYaml(path.join(root, product().configFile)),
+    user: readYaml(path.join(root, "config", "local", "user.yml")),
+  };
+}
+
+function expandHome(p: string): string {
+  return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+/** `~/x` → home; a relative path → under the repo root. */
+function resolvePath(p: string, root: string): string {
+  const e = expandHome(p);
+  return path.isAbsolute(e) ? e : path.join(root, e);
+}
+
+function list(v: unknown, name: string): string[] {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || v.some((x) => typeof x !== "string"))
+    throw new Error(`edge.${name} must be a list of strings`);
+  return v as string[];
+}
+
+function dockerLabels(v: RawEdge["docker_labels"]): { network: string } | null {
+  if (v === undefined || v === false) return null;
+  const network = typeof v === "object" ? v.network : undefined;
+  if (!network || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(network))
+    throw new Error(
+      "edge.docker_labels needs docker_labels.network: the Docker network " +
+        "the edge reaches labelled containers on, e.g. { network: apps-network }",
+    );
+  return { network };
+}
+
+function mounts(v: RawEdge["mounts"], root: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [host, target] of Object.entries(v ?? {})) {
+    if (typeof target !== "string" || !path.posix.isAbsolute(target))
+      throw new Error(
+        `edge.mounts: "${host}" must map to an absolute container path, got "${String(target)}"`,
+      );
+    out[resolvePath(host, root)] = target;
+  }
+  return out;
+}
+
+/** The web UI's route name: the brand name as a slug ("Den" → "den"). */
+function webRouteName(team: Record<string, unknown>): string {
+  const name = (team.brand as { name?: string } | undefined)?.name?.trim();
+  return brandSlug({ ...defaultBrand(), name: name || defaultBrand().name });
+}
+
+function port(v: unknown, name: string): number {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1 || n > 65535)
+    throw new Error(`${name} must be a port number, got "${String(v)}"`);
+  return n;
+}
+
+/** The den web UI port: user `web.port` > team `web.port` > 7777. */
+export function readWebPort(root: string = getDistRoot()): number {
+  const { team, user } = layers(root);
+  const v =
+    (user.web as { port?: number } | undefined)?.port ??
+    (team.web as { port?: number } | undefined)?.port ??
+    DEFAULT_PORT;
+  return port(v, "web.port");
+}
+
+/** Stacks declared in repo manifests across the active workspaces. */
+function manifestStackNames(): string[] {
+  try {
+    return getActiveWorkspaces().flatMap((ws) =>
+      Object.keys(readManifestStacks(ws)),
+    );
+  } catch {
+    return []; // a broken manifest must not stop the edge
+  }
+}
+
+export function readEdgeConfig(root: string = getDistRoot()): EdgeConfig {
+  const { team: t, user: u } = layers(root);
+  const team = (t.edge ?? {}) as RawEdge;
+  const user = (u.edge ?? {}) as RawEdge;
+  if (!team.org || !team.domain)
+    throw new Error(
+      `${product().configFile} has no \`edge:\` block with \`org\` and \`domain\` — ` +
+        "add one to give this instance its own HTTPS edge.",
+    );
+  if (!/^[a-z0-9-]+$/.test(team.org))
+    throw new Error(
+      `edge.org "${team.org}" must be lowercase letters, digits and dashes`,
+    );
+  assertDomain(team.domain);
+  const aliases = user.aliases ?? team.aliases ?? [];
+  if (!Array.isArray(aliases))
+    throw new Error("edge.aliases must be a list of domains");
+  aliases.forEach(assertDomain);
+  const publish = user.publish ?? team.publish ?? true;
+  return {
+    org: team.org,
+    domain: team.domain,
+    aliases,
+    image: user.image ?? team.image ?? DEFAULT_TRAEFIK_IMAGE,
+    workspaces: user.workspaces ?? team.workspaces ?? ["main"],
+    subzones: [
+      ...new Set([
+        ...Object.keys((t.stacks as Record<string, unknown>) ?? {}),
+        ...manifestStackNames(),
+      ]),
+    ].sort(),
+    routes: {
+      [webRouteName(t)]: `http://host.docker.internal:${readWebPort(root)}`,
+      ...(team.routes ?? {}),
+      ...(user.routes ?? {}),
+    },
+    ports: publish
+      ? {
+          http: port(user.http_port ?? team.http_port ?? 80, "edge.http_port"),
+          https: port(
+            user.https_port ?? team.https_port ?? 443,
+            "edge.https_port",
+          ),
+        }
+      : null,
+    stateDir: expandHome(
+      process.env.DEN_EDGE_DIR ??
+        user.state_dir ??
+        team.state_dir ??
+        path.join(
+          process.env.XDG_DATA_HOME ||
+            path.join(os.homedir(), ".local", "share"),
+          team.org,
+          "edge",
+        ),
+    ),
+    caroot:
+      (user.caroot ?? team.caroot)
+        ? resolvePath((user.caroot ?? team.caroot)!, root)
+        : null,
+    issueCert: (user.issue_cert ?? team.issue_cert) !== false,
+    httpsRedirect: (user.https_redirect ?? team.https_redirect) !== false,
+    dockerLabels: dockerLabels(user.docker_labels ?? team.docker_labels),
+    include: team.include ? resolvePath(team.include, root) : null,
+    mounts: mounts({ ...(team.mounts ?? {}), ...(user.mounts ?? {}) }, root),
+    networks: [
+      ...new Set([
+        ...list(team.networks, "networks"),
+        ...list(user.networks, "networks"),
+      ]),
+    ],
+    args: [...list(team.args, "args"), ...list(user.args, "args")],
+  };
+}