@intentius/chant-lexicon-otel 0.124.30 → 0.124.32

package/dist/model.js

@@ -0,0 +1,90 @@
+/**
+ * The plain-data model of an OpenTelemetry Collector config.
+ *
+ * Everything else in this lexicon reads or writes this shape: the serializer
+ * builds it from declared entities, the YAML emitter prints it, the checks
+ * validate it, and `collectorTopology()` reads it back for other tools. It is
+ * exactly the collector's own top-level layout, so a parsed collector YAML
+ * file is already a `CollectorConfig` and needs no conversion.
+ */
+/** The three signals a collector pipeline can carry. */
+export const SIGNALS = ["traces", "metrics", "logs"];
+/**
+ * The component kinds this lexicon types. A connector is an exporter in one
+ * pipeline and a receiver in another, which is how one pipeline feeds another
+ * (traces into span metrics, say).
+ */
+export const COMPONENT_KINDS = ["receiver", "processor", "exporter", "connector", "extension"];
+/** The top-level config section each component kind lives under. */
+export const SECTION_OF = {
+    receiver: "receivers",
+    processor: "processors",
+    exporter: "exporters",
+    connector: "connectors",
+    extension: "extensions",
+};
+/** The collector's id grammar: a type, then optionally `/` and a non-empty name. */
+const ID_PATTERN = /^([A-Za-z0-9_]+)(?:\/([^\s/][^\s]*))?$/;
+/** Build a component id from a type and an optional instance name. */
+export function componentId(type, name) {
+    return name === undefined || name === "" ? type : `${type}/${name}`;
+}
+/** Split a component id into its type and name, or `undefined` when it isn't valid id syntax. */
+export function parseComponentId(id) {
+    const m = ID_PATTERN.exec(id);
+    if (!m)
+        return undefined;
+    return m[2] === undefined ? { type: m[1] } : { type: m[1], name: m[2] };
+}
+/** True when `id` is a valid `type[/name]` component id. */
+export function isComponentId(id) {
+    return ID_PATTERN.test(id);
+}
+/** The signal a pipeline id names, e.g. `traces` for `traces/backend`. */
+export function pipelineSignal(pipelineId) {
+    const slash = pipelineId.indexOf("/");
+    return slash === -1 ? pipelineId : pipelineId.slice(0, slash);
+}
+/** True when a parsed document has the shape of a collector config. */
+export function looksLikeCollectorConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    const service = v.service;
+    if (typeof service !== "object" || service === null)
+        return false;
+    const pipelines = service.pipelines;
+    if (typeof pipelines !== "object" || pipelines === null)
+        return false;
+    return "receivers" in v || "exporters" in v;
+}
+/**
+ * The renamed built-ins. chant emits `builtin`, which the pinned collector
+ * (`COLLECTOR_PIN`, v0.130.0) knows and newer ones still accept. A config
+ * written for a newer collector may use `type`, so code that reads a config
+ * (the importer, the checks, the k8s composites) accepts both.
+ */
+export const COMPONENT_TYPE_ALIASES = [
+    { kind: "exporter", type: "otlp_grpc", builtin: "otlp", since: "v0.148.0", repo: "core" },
+    { kind: "exporter", type: "otlp_http", builtin: "otlphttp", since: "v0.148.0", repo: "core" },
+    { kind: "processor", type: "k8s_attributes", builtin: "k8sattributes", since: "v0.148.0", repo: "contrib" },
+    { kind: "connector", type: "signal_to_metrics", builtin: "signaltometrics", since: "v0.148.0", repo: "contrib" },
+    { kind: "receiver", type: "file_log", builtin: "filelog", since: "v0.149.0", repo: "contrib" },
+    { kind: "connector", type: "span_metrics", builtin: "spanmetrics", since: "v0.151.0", repo: "contrib" },
+    { kind: "connector", type: "service_graph", builtin: "servicegraph", since: "v0.151.0", repo: "contrib" },
+    { kind: "receiver", type: "host_metrics", builtin: "hostmetrics", since: "v0.151.0", repo: "contrib" },
+    { kind: "receiver", type: "kubelet_stats", builtin: "kubeletstats", since: "v0.152.0", repo: "contrib" },
+    { kind: "processor", type: "resource_detection", builtin: "resourcedetection", since: "v0.153.0", repo: "contrib" },
+    { kind: "exporter", type: "load_balancing", builtin: "loadbalancing", since: "v0.153.0", repo: "contrib" },
+    { kind: "processor", type: "delta_to_cumulative", builtin: "deltatocumulative", since: "v0.158.0", repo: "contrib" },
+];
+const ALIAS_TO_BUILTIN = new Map(COMPONENT_TYPE_ALIASES.map((a) => [`${a.kind}:${a.type}`, a.builtin]));
+/** The type chant declares for `kind` + `type`: the old name of a renamed built-in, otherwise `type` itself. */
+export function canonicalComponentType(kind, type) {
+    return ALIAS_TO_BUILTIN.get(`${kind}:${type}`) ?? type;
+}
+/** The type of component id `id`, with a renamed built-in's new name read as the old one: `span_metrics/genai` is `spanmetrics`. */
+export function canonicalTypeOf(kind, id) {
+    const slash = id.indexOf("/");
+    return canonicalComponentType(kind, slash === -1 ? id : id.slice(0, slash));
+}

package/dist/op/activities/collector-audit.js

@@ -0,0 +1,213 @@
+/**
+ * `collectorAudit`: the otel lexicon's pins against what upstream has
+ * released since (#3369), the activity behind `CollectorAuditOp`.
+ *
+ * Three readings, each against a moving upstream:
+ *
+ * - the contrib release list against `COLLECTOR_PIN`: how many releases
+ *   the pin is behind, and the newest one.
+ * - component stability from each built-in component's `metadata.yaml`, at
+ *   the pin and at the newest release: a signal whose stability level
+ *   changed between the two, and any signal that is `deprecated` or
+ *   `unmaintained` at the newest release. A component's file is looked up
+ *   in contrib, then in core, at `<kind>/<type><kind>/metadata.yaml`; one
+ *   found in neither is listed as unchecked, never as a finding.
+ * - `GENAI_SEMCONV_PIN` against the semantic-conventions releases.
+ *
+ * `mode` says what to do with the findings: `report` returns them;
+ * `issue` keeps one open issue current; `pull-request` also bumps the pins
+ * in the lexicon's `src/define.ts` on a proposal branch and opens (or
+ * edits) a pull request with the findings as its body. Only the pin values
+ * change: the config types written against the old pin are the reviewer's
+ * to move, which the body says.
+ */
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { load } from "js-yaml";
+import { COLLECTOR_PIN, GENAI_SEMCONV_PIN } from "../../define.js";
+import * as components from "../../components/index.js";
+import { compareSemver, defaultRunner, fetchReleases, proposePullRequest, stickyIssue } from "./github.js";
+export const CONTRIB_REPO = "open-telemetry/opentelemetry-collector-contrib";
+export const CORE_REPO = "open-telemetry/opentelemetry-collector";
+export const SEMCONV_REPO = "open-telemetry/semantic-conventions";
+export function builtinComponents() {
+    const out = [];
+    const seen = new Set();
+    for (const value of Object.values(components)) {
+        if (typeof value !== "function")
+            continue;
+        const def = value.definition;
+        if (!def || !def.builtin || typeof def.type !== "string")
+            continue;
+        const key = `${def.kind}/${def.type}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ kind: def.kind, type: def.type });
+    }
+    return out.sort((a, b) => `${a.kind}/${a.type}`.localeCompare(`${b.kind}/${b.type}`));
+}
+/** The directory a component lives in upstream: `receiver/k8s_cluster` is `receiver/k8sclusterreceiver`. */
+export function componentDir(c) {
+    return `${c.kind}/${c.type.replace(/_/g, "")}${c.kind}`;
+}
+export function parseStability(text) {
+    let doc;
+    try {
+        doc = load(text);
+    }
+    catch {
+        return undefined;
+    }
+    const status = doc?.status;
+    const stability = status?.stability;
+    if (!stability || typeof stability !== "object")
+        return undefined;
+    const out = {};
+    for (const [level, signals] of Object.entries(stability)) {
+        for (const s of Array.isArray(signals) ? signals : [])
+            if (typeof s === "string")
+                out[s] = level;
+    }
+    return out;
+}
+async function fetchText(f, url) {
+    const res = await f(url);
+    if (res.status === 404)
+        return undefined;
+    if (!res.ok)
+        throw new Error(`${url}: HTTP ${res.status}`);
+    return res.text();
+}
+/** A component's stability at `tag`, from contrib or core; undefined when neither has its metadata.yaml. */
+async function stabilityAt(f, c, tag, budget) {
+    for (const repo of [CONTRIB_REPO, CORE_REPO]) {
+        if (budget.left <= 0)
+            return undefined;
+        budget.left--;
+        const text = await fetchText(f, `https://raw.githubusercontent.com/${repo}/${tag}/${componentDir(c)}/metadata.yaml`);
+        if (text !== undefined)
+            return parseStability(text);
+    }
+    return undefined;
+}
+const RETIRED = new Set(["deprecated", "unmaintained"]);
+/** Findings for one component, from its stability at the pin and at the newest release. */
+export function stabilityFindings(c, atPin, atLatest, pin, latest) {
+    const subject = `${c.kind}/${c.type}`;
+    const out = [];
+    const retired = Object.entries(atLatest).filter(([, level]) => RETIRED.has(level));
+    if (retired.length > 0) {
+        out.push({ kind: "deprecated", subject, detail: `${retired.map(([s, l]) => `${s} ${l}`).join(", ")} at ${latest}` });
+    }
+    if (atPin && pin !== latest) {
+        const changed = [...new Set([...Object.keys(atPin), ...Object.keys(atLatest)])]
+            .filter((s) => atPin[s] !== atLatest[s] && !RETIRED.has(atLatest[s] ?? ""))
+            .map((s) => `${s} ${atPin[s] ?? "absent"} to ${atLatest[s] ?? "absent"}`);
+        if (changed.length > 0)
+            out.push({ kind: "stability-changed", subject, detail: `${changed.join(", ")} (${pin} to ${latest})` });
+    }
+    return out;
+}
+function behindCount(releases, pin) {
+    return releases.filter((r) => compareSemver(r.tag, pin) > 0).length;
+}
+/** `src/define.ts` with `COLLECTOR_PIN` and `GENAI_SEMCONV_PIN` moved to the given versions. */
+export function bumpPins(text, to) {
+    let out = text;
+    const bump = (name, version) => {
+        const re = new RegExp(`(export const ${name}: SchemaPin = Object\\.freeze\\(\\{[^}]*?version:\\s*")([^"]+)(")`);
+        if (!re.test(out))
+            throw new Error(`define.ts has no ${name} with a version to bump`);
+        out = out.replace(re, `$1${version}$3`);
+    };
+    if (to.collector)
+        bump("COLLECTOR_PIN", to.collector);
+    if (to.genai)
+        bump("GENAI_SEMCONV_PIN", to.genai);
+    return out;
+}
+export function renderCollectorAuditSummary(r) {
+    let out = "## Collector audit\n\n";
+    out += `- COLLECTOR_PIN ${r.collector.pin}: ${r.collector.latest === null ? "release list unreadable" : r.collector.behind === 0 ? "current" : `${r.collector.behind} release(s) behind ${r.collector.latest}`}\n`;
+    out += `- GENAI_SEMCONV_PIN ${r.semconv.pin}: ${r.semconv.latest === null ? "release list unreadable" : r.semconv.behind === 0 ? "current" : `${r.semconv.behind} release(s) behind ${r.semconv.latest}`}\n`;
+    const comps = r.findings.filter((f) => f.kind === "deprecated" || f.kind === "stability-changed");
+    if (comps.length > 0) {
+        out += "\n| Component | Finding | Detail |\n|---|---|---|\n";
+        for (const f of comps)
+            out += `| ${f.subject} | ${f.kind} | ${f.detail} |\n`;
+    }
+    else {
+        out += "\nNo component stability findings.\n";
+    }
+    if (r.unchecked.length > 0)
+        out += `\nUnchecked (no metadata.yaml found, or past the budget): ${r.unchecked.join(", ")}\n`;
+    return out;
+}
+/** Audit the otel lexicon's pins and its built-in components against upstream releases. */
+export async function collectorAudit(args = {}) {
+    const f = args._fetch ?? fetch;
+    const run = args._run ?? defaultRunner;
+    const mode = args.mode ?? "report";
+    const findings = [];
+    const unchecked = [];
+    const contrib = await fetchReleases(CONTRIB_REPO, f).catch(() => null);
+    const semconv = await fetchReleases(SEMCONV_REPO, f).catch(() => null);
+    const collector = { pin: COLLECTOR_PIN.version, latest: contrib?.[0]?.tag ?? null, behind: contrib ? behindCount(contrib, COLLECTOR_PIN.version) : 0 };
+    const sem = { pin: GENAI_SEMCONV_PIN.version, latest: semconv?.[0]?.tag ?? null, behind: semconv ? behindCount(semconv, GENAI_SEMCONV_PIN.version) : 0 };
+    if (collector.latest && collector.behind > 0) {
+        findings.push({ kind: "collector-pin-behind", subject: "COLLECTOR_PIN", detail: `${collector.pin} is ${collector.behind} release(s) behind ${collector.latest}` });
+    }
+    if (sem.latest && sem.behind > 0) {
+        findings.push({ kind: "semconv-pin-behind", subject: "GENAI_SEMCONV_PIN", detail: `${sem.pin} is ${sem.behind} release(s) behind ${sem.latest}` });
+    }
+    if (args.stability !== false) {
+        const latest = collector.latest ?? collector.pin;
+        const budget = { left: args.stabilityBudget ?? 200 };
+        for (const c of builtinComponents()) {
+            const atLatest = await stabilityAt(f, c, latest, budget).catch(() => undefined);
+            if (!atLatest) {
+                unchecked.push(`${c.kind}/${c.type}`);
+                continue;
+            }
+            const atPin = latest === collector.pin ? atLatest : await stabilityAt(f, c, collector.pin, budget).catch(() => undefined);
+            findings.push(...stabilityFindings(c, atPin, atLatest, collector.pin, latest));
+        }
+    }
+    const base = { collector, semconv: sem, findings, unchecked };
+    const summary = renderCollectorAuditSummary(base);
+    const result = { mode, ...base, summary };
+    if (findings.length === 0 || mode === "report")
+        return result;
+    const cwd = process.cwd();
+    if (mode === "issue") {
+        result.issueUrl = await stickyIssue(run, cwd, "otel: collector audit findings", summary);
+        return result;
+    }
+    // pull-request: bump the pins that are behind.
+    const to = {
+        ...(collector.latest && collector.behind > 0 ? { collector: collector.latest } : {}),
+        ...(sem.latest && sem.behind > 0 ? { genai: sem.latest } : {}),
+    };
+    if (!to.collector && !to.genai) {
+        result.issueUrl = await stickyIssue(run, cwd, "otel: collector audit findings", summary);
+        return result;
+    }
+    const lexiconDir = resolve(args.lexiconDir ?? join(cwd, "lexicons", "otel"));
+    const root = (await run("git", ["rev-parse", "--show-toplevel"], lexiconDir)).trim();
+    const definePath = join(lexiconDir, "src", "define.ts");
+    const content = bumpPins(readFileSync(definePath, "utf8"), to);
+    const moved = [to.collector ? `COLLECTOR_PIN to ${to.collector}` : "", to.genai ? `GENAI_SEMCONV_PIN to ${to.genai}` : ""].filter(Boolean).join(" and ");
+    result.prUrl = await proposePullRequest(run, {
+        root,
+        branch: args.branch ?? "chant/otel-pins",
+        title: `chore(otel): move ${moved}`,
+        body: `${summary}\n\nThis moves the pin values only. The config types, defaults and checks written against ${collector.pin} ` +
+            "still need reading against the release notes before this merges.\n",
+        files: [{ path: relative(root, definePath), content }],
+        commitMessage: `chore(otel): move ${moved}`,
+        worktreeDir: join(mkdtempSync(join(tmpdir(), "chant-otel-pins-")), "wt"),
+    });
+    return result;
+}

package/dist/op/activities/collector-health.js

@@ -0,0 +1,176 @@
+/**
+ * Running collectors as resources a `ConvergeOp` observes (#3369).
+ *
+ * `collectorHealthObserve` returns one resource per collector, from the
+ * endpoints its config declares:
+ *
+ * - the `health_check` extension (`service.extensions`), at its `endpoint`
+ *   and `path`. At v0.130.0 it answers on `localhost:13133` at `/` by
+ *   default, 200 while the collector runs, and reports no per-component
+ *   status, so a 200 is all it says.
+ * - the `zpages` extension, when the service enables it: `/debug/servicez`
+ *   on its endpoint (default `localhost:55679`).
+ * - the collector's own metrics, when `service.telemetry.metrics` declares
+ *   where they are served: a `pull` reader's prometheus exporter
+ *   (`host`/`port`), or the older `address`. `/metrics` on it.
+ *
+ * A collector whose service enables no `health_check` is `unknown`, never
+ * `drifted`: nothing it declares says whether it is healthy. One that does
+ * is `in-sync` when every declared endpoint answers 200, and `drifted`
+ * otherwise, with each endpoint that did not in the detail.
+ *
+ * The config's hosts are where the collector listens, which is often
+ * `0.0.0.0` or a pod address. `host` replaces the host of every endpoint (a
+ * port-forward, a container's published ports), and `endpoints` replaces
+ * whole URLs.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { load } from "js-yaml";
+import { parseComponentId } from "../../model.js";
+const DEFAULTS = {
+    healthCheck: { endpoint: "localhost:13133", path: "/" },
+    zpages: { endpoint: "localhost:55679", path: "/debug/servicez" },
+};
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** `host:port`, `:port` or a URL, as host and port. A `${env:...}` host reads as unknown (empty). */
+export function splitEndpoint(endpoint) {
+    let s = endpoint.trim().replace(/^[a-z]+:\/\//i, "");
+    s = s.replace(/\/.*$/, "");
+    const m = /^(.*):(\d+)$/.exec(s);
+    if (!m)
+        return undefined;
+    const host = m[1].includes("${") ? "" : m[1];
+    return { host, port: m[2] };
+}
+function urlOf(endpoint, path, host) {
+    const parts = splitEndpoint(endpoint);
+    if (!parts)
+        return undefined;
+    let h = host ?? parts.host;
+    if (h === "" || h === "0.0.0.0" || h === "::" || h === "[::]")
+        h = "localhost";
+    return `http://${h}:${parts.port}${path.startsWith("/") ? path : `/${path}`}`;
+}
+/** The first enabled extension of `type`, and its config. */
+function enabledExtension(config, type) {
+    const service = isRecord(config.service) ? config.service : {};
+    const enabled = Array.isArray(service.extensions) ? service.extensions : [];
+    const extensions = isRecord(config.extensions) ? config.extensions : {};
+    for (const id of enabled) {
+        if (typeof id !== "string" || parseComponentId(id)?.type !== type)
+            continue;
+        const body = extensions[id];
+        return isRecord(body) ? body : {};
+    }
+    return undefined;
+}
+/** Where `service.telemetry.metrics` serves the collector's own metrics, as `host:port`, when the config says. */
+function telemetryEndpoint(config) {
+    const service = isRecord(config.service) ? config.service : {};
+    const telemetry = isRecord(service.telemetry) ? service.telemetry : {};
+    const metrics = isRecord(telemetry.metrics) ? telemetry.metrics : undefined;
+    if (!metrics || metrics.level === "none")
+        return undefined;
+    if (typeof metrics.address === "string")
+        return metrics.address;
+    const readers = Array.isArray(metrics.readers) ? metrics.readers : [];
+    for (const r of readers) {
+        const prom = isRecord(r) && isRecord(r.pull) && isRecord(r.pull.exporter) ? r.pull.exporter.prometheus : undefined;
+        if (isRecord(prom) && (typeof prom.port === "number" || typeof prom.port === "string")) {
+            const host = typeof prom.host === "string" ? prom.host : "localhost";
+            return `${host}:${prom.port}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * The endpoints a collector config declares, as URLs. `healthCheck` is
+ * present only when the service enables a `health_check` extension.
+ */
+export function declaredEndpoints(config, host, overrides = {}) {
+    const out = [];
+    const push = (kind, url) => {
+        const u = overrides[kind] ?? url;
+        if (u)
+            out.push({ kind, url: u });
+    };
+    const hc = enabledExtension(config, "health_check");
+    if (hc) {
+        const endpoint = typeof hc.endpoint === "string" ? hc.endpoint : DEFAULTS.healthCheck.endpoint;
+        const path = typeof hc.path === "string" ? hc.path : DEFAULTS.healthCheck.path;
+        push("healthCheck", urlOf(endpoint, path, host));
+    }
+    const zp = enabledExtension(config, "zpages");
+    if (zp) {
+        const endpoint = typeof zp.endpoint === "string" ? zp.endpoint : DEFAULTS.zpages.endpoint;
+        push("zpages", urlOf(endpoint, DEFAULTS.zpages.path, host));
+    }
+    const tel = telemetryEndpoint(config);
+    if (tel)
+        push("telemetry", urlOf(tel, "/metrics", host));
+    return out;
+}
+const LABEL = { healthCheck: "health_check", zpages: "zpages", telemetry: "telemetry" };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function probe(f, url, timeoutMs) {
+    try {
+        const res = await f(url, { signal: AbortSignal.timeout(timeoutMs) });
+        await res.body?.cancel().catch(() => undefined);
+        return res.status === 200 ? undefined : `answered ${res.status}`;
+    }
+    catch (err) {
+        const cause = err.cause?.code;
+        return `did not answer (${cause ?? err.message})`;
+    }
+}
+function collectorConfig(c) {
+    if (c.configObject)
+        return c.configObject;
+    if (!c.config)
+        throw new Error(`collector "${c.name}" names no config`);
+    const value = load(readFileSync(resolve(process.cwd(), c.config), "utf8"));
+    if (!isRecord(value))
+        throw new Error(`collector "${c.name}": ${c.config} does not hold a YAML mapping`);
+    return value;
+}
+/** Observe each collector through the endpoints its config declares: one resource per collector. */
+export async function collectorHealthObserve(args) {
+    const f = args._fetch ?? fetch;
+    const timeoutMs = args.timeoutMs ?? 5000;
+    const probes = Math.max(1, args.probes ?? 2);
+    const interval = args.probeIntervalMs ?? 1000;
+    const resources = [];
+    for (const c of args.collectors) {
+        let config;
+        try {
+            config = collectorConfig(c);
+        }
+        catch (err) {
+            resources.push({ name: c.name, status: "unknown", detail: `config unreadable: ${err.message}` });
+            continue;
+        }
+        const endpoints = declaredEndpoints(config, c.host, c.endpoints);
+        if (!endpoints.some((e) => e.kind === "healthCheck")) {
+            resources.push({ name: c.name, status: "unknown", detail: "no health_check in service.extensions" });
+            continue;
+        }
+        const failures = [];
+        for (const e of endpoints) {
+            let why;
+            for (let i = 0; i < probes; i++) {
+                why = await probe(f, e.url, timeoutMs);
+                if (!why)
+                    break;
+                if (i + 1 < probes)
+                    await sleep(interval);
+            }
+            if (why)
+                failures.push(`${LABEL[e.kind]} ${e.url} ${why}`);
+        }
+        resources.push(failures.length === 0
+            ? { name: c.name, status: "in-sync", detail: endpoints.map((e) => `${LABEL[e.kind]} ok`).join(", ") }
+            : { name: c.name, status: "drifted", detail: failures.join("; ") });
+    }
+    return { resources };
+}

package/dist/op/activities/exec.js

@@ -0,0 +1,16 @@
+/**
+ * How the otel activities run a binary: a child process whose exit code,
+ * stdout and stderr are returned rather than thrown, so the caller decides
+ * what a non-zero exit means. Tests pass their own runner.
+ */
+import { execFile } from "node:child_process";
+export const defaultExec = (bin, args, opts = {}) => new Promise((resolve) => {
+    execFile(bin, args, { cwd: opts.cwd, timeout: opts.timeoutMs ?? 120000, maxBuffer: 32 * 1024 * 1024, encoding: "utf8" }, (err, stdout, stderr) => {
+        if (!err)
+            return resolve({ code: 0, stdout, stderr });
+        const e = err;
+        if (typeof e.code === "number")
+            return resolve({ code: e.code, stdout, stderr });
+        resolve({ code: null, stdout: stdout ?? "", stderr: stderr ?? "", error: e.message });
+    });
+});

package/dist/op/activities/github.js

@@ -0,0 +1,110 @@
+/**
+ * What the audit activities read from GitHub and write back to it: release
+ * lists over the REST API, and a sticky issue or a proposal pull request
+ * through `git` and `gh`. The prometheus lexicon's rule audit uses the issue
+ * half too.
+ */
+import { execFile } from "node:child_process";
+import { ghHostEnv } from "@intentius/chant/op/activities/gh-host";
+/**
+ * Runs the command in `cwd`. `gh issue` and `gh pr` name no host, so a `gh`
+ * call is told the job's forge or `cwd`'s `origin` host (core's
+ * `ghHostEnv`, #3780, #3798): a GitHub Enterprise Server checkout is not sent
+ * to github.com.
+ */
+export const defaultRunner = async (bin, args, cwd) => {
+    const env = bin === "gh" ? await ghHostEnv(process.env, cwd) : process.env;
+    return new Promise((resolve, reject) => {
+        execFile(bin, args, { cwd, env, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error(`${bin} ${args.join(" ")} failed: ${(stderr || err.message).trim()}`));
+            else
+                resolve(stdout);
+        });
+    });
+};
+/** `v1.2.3` as numbers, or undefined when the tag is not a plain semver. */
+export function semverOf(tag) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(tag.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+export function compareSemver(a, b) {
+    const x = semverOf(a);
+    const y = semverOf(b);
+    if (!x || !y)
+        return a.localeCompare(b);
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    return 0;
+}
+/**
+ * The published, non-prerelease releases of `repo` (`owner/name`) with a
+ * plain semver tag, newest first. Reads one page of 100, which covers
+ * months of collector releases.
+ */
+export async function fetchReleases(repo, f = fetch, token = process.env.GITHUB_TOKEN) {
+    const headers = { Accept: "application/vnd.github+json" };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const res = await f(`https://api.github.com/repos/${repo}/releases?per_page=100`, { headers });
+    if (!res.ok)
+        throw new Error(`GitHub releases of ${repo}: HTTP ${res.status}`);
+    const body = (await res.json());
+    return body
+        .filter((r) => !r.draft && !r.prerelease && typeof r.tag_name === "string" && semverOf(r.tag_name))
+        .map((r) => ({ tag: r.tag_name, ...(r.published_at ? { publishedAt: r.published_at } : {}) }))
+        .sort((a, b) => compareSemver(b.tag, a.tag));
+}
+/**
+ * Open an issue titled `title`, or edit the body of the open one that
+ * already has that title, so a scheduled audit keeps one issue current
+ * instead of opening one per run. Returns its URL.
+ */
+export async function stickyIssue(run, cwd, title, body, labels = []) {
+    const listed = await run("gh", ["issue", "list", "--state", "open", "--search", `"${title}" in:title`, "--json", "number,title,url"], cwd);
+    const open = JSON.parse(listed || "[]").find((i) => i.title === title);
+    if (open) {
+        await run("gh", ["issue", "edit", String(open.number), "--body", body], cwd);
+        return open.url;
+    }
+    const args = ["issue", "create", "--title", title, "--body", body];
+    for (const l of labels)
+        args.push("--label", l);
+    return (await run("gh", args, cwd)).trim();
+}
+/**
+ * Commit `files` on `branch`, from the remote's default branch, in a
+ * worktree of its own (the checked-out branch and working tree are never
+ * touched), push it, and open a pull request, or edit the open one for that
+ * branch. Returns the pull request's URL.
+ */
+export async function proposePullRequest(run, o) {
+    const remote = o.remote ?? "origin";
+    await run("git", ["fetch", remote], o.root);
+    let base = o.base;
+    if (!base) {
+        const head = (await run("git", ["symbolic-ref", "--short", `refs/remotes/${remote}/HEAD`], o.root).catch(() => `${remote}/main`)).trim();
+        base = head.startsWith(`${remote}/`) ? head.slice(remote.length + 1) : head;
+    }
+    await run("git", ["worktree", "add", "--force", "-B", o.branch, o.worktreeDir, `${remote}/${base}`], o.root);
+    try {
+        const { writeFileSync } = await import("node:fs");
+        const { join } = await import("node:path");
+        for (const f of o.files)
+            writeFileSync(join(o.worktreeDir, f.path), f.content);
+        await run("git", ["add", ...o.files.map((f) => f.path)], o.worktreeDir);
+        await run("git", ["commit", "-m", o.commitMessage], o.worktreeDir);
+        await run("git", ["push", "--force", remote, `HEAD:refs/heads/${o.branch}`], o.worktreeDir);
+    }
+    finally {
+        await run("git", ["worktree", "remove", "--force", o.worktreeDir], o.root).catch(() => undefined);
+    }
+    const listed = await run("gh", ["pr", "list", "--head", o.branch, "--state", "open", "--json", "number,url"], o.root);
+    const open = JSON.parse(listed || "[]")[0];
+    if (open) {
+        await run("gh", ["pr", "edit", String(open.number), "--title", o.title, "--body", o.body], o.root);
+        return open.url;
+    }
+    return (await run("gh", ["pr", "create", "--head", o.branch, "--base", base, "--title", o.title, "--body", o.body], o.root)).trim();
+}

package/dist/op/activities/index.js

@@ -0,0 +1,16 @@
+/**
+ * otel Op activities (#3369), resolved by the core activity registry when a
+ * project's `chant.config.ts` lists the `otel` lexicon. Every function this
+ * module exports is an activity, bound by its export name, so the helpers
+ * behind them stay in their own files.
+ *
+ * - `otelcolValidate`, `otelcolComponents`: the collector binary's own
+ *   checks over a config file.
+ * - `collectorHealthObserve`: running collectors as the resources of a
+ *   `ConvergeOp({ observe })`.
+ * - `collectorAudit`: the lexicon's pins against upstream releases, the
+ *   step of `CollectorAuditOp`.
+ */
+export { otelcolValidate, otelcolComponents } from "./otelcol.js";
+export { collectorHealthObserve } from "./collector-health.js";
+export { collectorAudit } from "./collector-audit.js";