@ogcio/o11y-validator 0.2.1

package/README.md

@@ -0,0 +1,65 @@
+# @ogcio/o11y-validator
+
+npm wrapper for the o11y-validator Go binary. Allows running the validator via `npx` without installing Go.
+
+## Quick start
+
+```bash
+# Build the binary for your current platform
+pnpm build:local
+
+# Run directly
+node bin/o11y-validator.mjs
+
+# Or via npx (after publishing)
+npx @ogcio/o11y-validator
+```
+
+## Environment variables
+
+The launcher reads a `.env` file from the current working directory. Shell env vars take precedence.
+
+```bash
+# .env
+RULES_DIR=./rules
+FORWARD_TO_COLLECTOR=false
+LOG_LEVEL=debug
+```
+
+## Rules
+
+The validator needs a rules directory. If you do **not** set `RULES_DIR`, the
+launcher downloads the rule set from GitHub at the tag matching this package's
+version and caches it **inside the installed package** (`.rules-cache/`, scoped
+to the package version). Subsequent runs reuse the cache — no network needed. If
+the rules cannot be obtained (and `RULES_DIR` is unset), the launcher **exits
+with an error**.
+
+The repo and ref are taken from `package.json` (`repository` and
+`name@version`). The path to the rules inside the repo is **hardcoded** in the
+launcher as `o11y-validator/rules` — see the maintainer note below.
+
+| Variable       | Default   | Purpose                                                    |
+| -------------- | --------- | ---------------------------------------------------------- |
+| `RULES_DIR`    | _(unset)_ | Use a local rules directory and skip downloading entirely. |
+| `GITHUB_TOKEN` | _(unset)_ | Raises rate limits; required if the repo is private.       |
+
+> **Maintainer note:** if the rules directory is relocated in a future release,
+> update `RULES_SUBPATH` in `bin/o11y-validator.mjs` to match. It is intentionally
+> not configurable via env.
+
+## Build for all platforms
+
+```bash
+pnpm build
+```
+
+Cross-compiles every target with plain `go build` CGO disabled,
+so no zig, osxcross, or macOS agent is required, `darwin/arm64` is ad-hoc signed
+by the Go linker automatically.
+
+## Releasing
+
+A pre-commit hook keeps `o11y-validator.lock` in sync with the `o11y-validator/`
+tree so validator changes can trigger a release of this package.
+see [distribution.md](../../o11y-validator/docs/distribution.md).

package/bin/o11y-validator.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// @ogcio/o11y-validator - launcher
+// 1 - Loads .env
+// 2 - dispatches the `init` command or resolves the platform binary and executes it with inherited stdio.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { arch, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureRulesCache, RULES_REF } from "../lib/rules.mjs";
+import { initCommand } from "../lib/init.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Load .env file from cwd (does NOT override existing env vars) ──
+const envFile = join(process.cwd(), ".env");
+if (existsSync(envFile)) {
+  for (const line of readFileSync(envFile, "utf8").split("\n")) {
+    const match = line.match(/^\s*([^#=]+?)\s*=\s*(.*)\s*$/);
+    if (match && !process.env[match[1]]) {
+      process.env[match[1]] = match[2].replace(/^['"]|['"]$/g, "");
+    }
+  }
+}
+
+const args = process.argv.slice(2);
+
+// `init <path>` — eject the version-pinned rules into a directory
+if (args[0] === "init") {
+  try {
+    await initCommand(args[1]);
+    process.exit(0);
+  } catch (err) {
+    console.error(`[o11y-validator] init failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// Provide validation rules for the run
+// A RULES_DIR set by the user (env or .env) skips fetching entirely.
+if (!process.env.RULES_DIR) {
+  try {
+    process.env.RULES_DIR = await ensureRulesCache();
+  } catch (err) {
+    console.error(`[o11y-validator] could not obtain rules (${RULES_REF}): ${err.message}`);
+    console.error(
+      `[o11y-validator] set RULES_DIR to a local rules directory, or check your network / GITHUB_TOKEN.`,
+    );
+    process.exit(1);
+  }
+}
+
+// ── Resolve platform binary ──
+const normalizedArch = arch() === "x64" ? "x64" : "arm64";
+const bin = `o11y-validator-${platform()}-${normalizedArch}`;
+const binPath = join(__dirname, bin);
+
+if (!existsSync(binPath)) {
+  console.error(
+    `[o11y-validator] No binary found for platform: ${platform()}-${normalizedArch}`,
+  );
+  console.error(`Expected binary at: ${binPath}`);
+  console.error(
+    `\nAvailable platforms: darwin-arm64, darwin-x64, linux-arm64, linux-x64`,
+  );
+  console.error(`Run "pnpm build" in packages/validator-cli to compile.`);
+  process.exit(1);
+}
+
+// ── Execute the Go binary ──
+try {
+  execFileSync(binPath, args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/lib/init.mjs

@@ -0,0 +1,55 @@
+// @ogcio/o11y-validator - `init` command
+// Ejects the version-pinned rule set into a user-provided directory so teams can
+// review or customize the rules locally. Fails on:
+// - missing path,
+// - non-empty destination,
+// - unobtainable rules.
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ensureRulesCache, listRuleFiles, pkg, RULES_REF } from "./rules.mjs";
+
+export async function initCommand(targetArg) {
+  if (!targetArg) {
+    throw new Error("usage: o11y-validator init <path>");
+  }
+
+  const target = resolve(process.cwd(), targetArg);
+
+  if (existsSync(target)) {
+    if (!statSync(target).isDirectory()) {
+      throw new Error(`destination exists and is not a directory: ${target}`);
+    }
+    if (readdirSync(target).length > 0) {
+      throw new Error(`destination directory is not empty: ${target}`);
+    }
+  }
+
+  // Source the rules from the git repo cache (download if never fetched).
+  let cacheDir;
+  try {
+    cacheDir = await ensureRulesCache();
+  } catch (err) {
+    throw new Error(`could not obtain rules (${RULES_REF}): ${err.message}`, {
+      cause: err,
+    });
+  }
+
+  const files = listRuleFiles(cacheDir);
+  if (files.length === 0) {
+    throw new Error(`no rule files available for ${RULES_REF}`);
+  }
+
+  mkdirSync(target, { recursive: true });
+  for (const name of files) {
+    copyFileSync(join(cacheDir, name), join(target, name));
+  }
+
+  console.log(`[o11y-validator] Initialized rules in ${target}`);
+  console.log(`[o11y-validator]     package version: ${pkg.version}`);
+  console.log(`[o11y-validator]     rules ref:       ${RULES_REF}`);
+  console.log(`[o11y-validator]     files:           ${files.length}`);
+  console.log(`[o11y-validator] Use them with env: RULES_DIR=${target}`);
+}
+
+

package/lib/rules.mjs

@@ -0,0 +1,83 @@
+// @ogcio/o11y-validator - rules resolution
+// Rules are fetched from GitHub at the tag matching this package's version and cached on disk,
+// so a given release always resolves the rule set it shipped with.
+// The repo and ref come from package.json;
+// The path within the repo is hardcoded below.
+//
+// NOTE: if the rules directory is relocated in a future release, update
+// RULES_SUBPATH to match.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+export const RULES_SUBPATH = "o11y-validator/rules";
+export const RULES_REF = `${pkg.name}@${pkg.version}`;
+
+export function rulesCacheDir() {
+  // Cache inside the installed package, alongside the binary, scoped to the version.
+  return join(pkgRoot, ".rules-cache");
+}
+
+export function listRuleFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => /\.ya?ml$/.test(name))
+    .sort();
+}
+
+function ghRepo() {
+  const repository = pkg.repository;
+  const url = typeof repository === "string" ? repository : repository?.url || "";
+  const match = url.match(/github\.com[/:]([^/]+)\/([^/.]+)(?:\.git)?/i);
+  if (!match) {
+    throw new Error("package.json 'repository' must be a GitHub URL");
+  }
+  return `${match[1]}/${match[2]}`;
+}
+
+function ghHeaders(accept = "application/vnd.github+json") {
+  const headers = { "user-agent": "o11y-validator-cli", accept };
+  // GITHUB_TOKEN required for private repos.
+  const token = process.env.GITHUB_TOKEN || process.env.NODE_AUTH_TOKEN;
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
+export async function downloadRules(destDir) {
+  const repo = ghRepo();
+  const listUrl = `https://api.github.com/repos/${repo}/contents/${RULES_SUBPATH}?ref=${encodeURIComponent(RULES_REF)}`;
+  const res = await fetch(listUrl, { headers: ghHeaders() });
+  if (!res.ok) {
+    throw new Error(`GitHub contents ${res.status} for ref ${RULES_REF}`);
+  }
+  const entries = await res.json();
+  const files = entries.filter((e) => e.type === "file" && /\.ya?ml$/.test(e.name));
+  if (files.length === 0) {
+    throw new Error(`no rule files at ${RULES_SUBPATH}@${RULES_REF}`);
+  }
+  mkdirSync(destDir, { recursive: true });
+  for (const file of files) {
+    // Fetch raw bytes via the contents API so the auth header also works for
+    // private repositories.
+    const raw = await fetch(file.url, {
+      headers: ghHeaders("application/vnd.github.raw"),
+    });
+    if (!raw.ok) throw new Error(`download ${file.name}: ${raw.status}`);
+    writeFileSync(join(destDir, file.name), Buffer.from(await raw.arrayBuffer()));
+  }
+}
+
+// Ensure the rules cache is populated, downloading it if empty. Returns the
+// cache directory. Throws if rules cannot be obtained.
+export async function ensureRulesCache() {
+  const dir = rulesCacheDir();
+  if (listRuleFiles(dir).length === 0) {
+    await downloadRules(dir);
+  }
+  return dir;
+}
+

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@ogcio/o11y-validator",
+  "version": "0.2.1",
+  "description": "Telemetry rules validator for OGCIO services — wraps the Go binary for npx execution",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ogcio/o11y.git"
+  },
+  "bin": {
+    "o11y-validator": "./bin/o11y-validator.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "opentelemetry",
+    "observability",
+    "validator",
+    "ottl"
+  ],
+  "license": "ISC",
+  "scripts": {
+    "build": "./scripts/build.sh",
+    "build:local": "./scripts/build.sh local",
+    "lock": "./scripts/update-lock.sh"
+  }
+}