@lorekit/cli 1.24.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/mcp.mjs

@@ -124,16 +124,36 @@ export function mcpToRestBase(mcpEndpointUrl) {
  * @param {number} [opts.timeoutMs=10000]
  * @param {string} [opts.traceparent] - W3C traceparent header value
  */
+/**
+ * Normalise a client-supplied usage correlation id (a PR ref, session id, or CI
+ * job id). Bounded + charset-restricted to match the server's `parseCorrelationId`
+ * (supabase/functions/_shared/usage-stats.ts); returns null for empty/over-long/
+ * out-of-charset input so a bad value is simply not sent. Zero-dep (the CLI does
+ * not import mcp-core), so the small regex is duplicated intentionally.
+ */
+export function normalizeCorrelationId(raw) {
+  if (typeof raw !== 'string') return null;
+  const t = raw.trim();
+  if (!t || t.length > 200) return null;
+  return /^[A-Za-z0-9_\-./:#@]+$/.test(t) ? t : null;
+}
+
 export async function restFetch(baseUrl, token, path, { method = 'GET', body, timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const url = `${baseUrl}${path}`;
+    // Opt-in usage correlation: when LOREKIT_CORRELATION_ID is set (e.g. by a CI
+    // job or a hook to a PR/session id), tag every REST call so GET
+    // /memories/usage?correlation_id=… can report "usage for this PR". Absent env
+    // ⇒ no header ⇒ existing behaviour unchanged.
+    const correlationId = normalizeCorrelationId(process.env.LOREKIT_CORRELATION_ID);
     const headers = {
       accept: 'application/json',
       ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
       ...(token ? { authorization: `Bearer ${token}` } : {}),
       ...(traceparent ? { traceparent } : {}),
+      ...(correlationId ? { 'x-lorekit-correlation-id': correlationId } : {}),
     };
     const res = await fetch(url, {
       method,

package/src/telemetry.mjs

@@ -165,16 +165,58 @@ function toOtlpAttributes(attributes) {
   return Object.entries(attributes).map(([key, value]) => ({ key, value: toOtlpValue(value) }));
 }
 
-function resourceAttributes(version) {
-  return [
+// OTel `os.type` / `host.arch` use their own bounded enum vocabularies, which
+// are NOT identical to Node's `process.platform` / `process.arch` spellings.
+// Node's `win32` / `sunos` and `x64` / `ia32` / `arm` are the ones that differ;
+// emitting them verbatim produces off-registry attribute values that a Dash0 /
+// OTel-native backend can't group with telemetry from other SDKs. Map the known
+// divergences and pass anything already-canonical (or unknown) through.
+//   os.type:   https://opentelemetry.io/docs/specs/semconv/registry/attributes/os/
+//   host.arch: https://opentelemetry.io/docs/specs/semconv/registry/attributes/host/
+const OS_TYPE_BY_PLATFORM = { win32: 'windows', sunos: 'solaris' };
+// Node's `process.arch` reports `ppc` for 32-bit PowerPC; the OTel `host.arch`
+// registry value for it is `ppc32` (its `ppc64` spelling already matches Node).
+const HOST_ARCH_BY_PROCESS_ARCH = { x64: 'amd64', ia32: 'x86', arm: 'arm32', ppc: 'ppc32' };
+
+/** Map a Node `process.platform` value to an OTel `os.type` registry value. */
+export function normalizeOsType(platform) {
+  return OS_TYPE_BY_PLATFORM[platform] ?? platform;
+}
+
+/** Map a Node `process.arch` value to an OTel `host.arch` registry value. */
+export function normalizeHostArch(arch) {
+  return HOST_ARCH_BY_PROCESS_ARCH[arch] ?? arch;
+}
+
+/**
+ * Resolve the `deployment.environment.name` resource value, or `undefined` when
+ * none is set. The CLI runs on end-users' machines, so — unlike the edge/web/
+ * mcp-node deployments — it has no ambient environment and deliberately OMITS
+ * the attribute by default. It is emitted ONLY when explicitly overridden via
+ * `DEPLOYMENT_ENVIRONMENT` (falling back to `OTEL_DEPLOYMENT_ENVIRONMENT`) — the
+ * same single, env-driven knob the edge honours, which the correlated-trace
+ * harness (`scripts/emit-correlated-trace.mts`) uses to stamp `test`.
+ * @param {object} [env]  defaults to process.env
+ */
+export function resolveDeploymentEnvironment(env = process.env) {
+  const raw = env.DEPLOYMENT_ENVIRONMENT ?? env.OTEL_DEPLOYMENT_ENVIRONMENT;
+  const value = raw !== undefined ? String(raw).trim() : '';
+  return value || undefined;
+}
+
+function resourceAttributes(version, env = process.env) {
+  const attrs = [
     { key: 'service.name', value: { stringValue: 'cli' } },
     { key: 'service.namespace', value: { stringValue: 'lorekit' } },
     { key: 'service.version', value: { stringValue: String(version) } },
     { key: 'process.runtime.name', value: { stringValue: 'nodejs' } },
     { key: 'process.runtime.version', value: { stringValue: process.versions.node } },
-    { key: 'os.type', value: { stringValue: process.platform } },
-    { key: 'host.arch', value: { stringValue: process.arch } },
+    { key: 'os.type', value: { stringValue: normalizeOsType(process.platform) } },
+    { key: 'host.arch', value: { stringValue: normalizeHostArch(process.arch) } },
   ];
+  const deploymentEnv = resolveDeploymentEnvironment(env);
+  if (deploymentEnv) attrs.push({ key: 'deployment.environment.name', value: { stringValue: deploymentEnv } });
+  return attrs;
 }
 
 // ── Payload builders (pure — unit-tested) ─────────────────────────────────────
@@ -200,7 +242,7 @@ export function buildTracePayload({ version, name, attributes, startMs, endMs, s
         resource: { attributes: resourceAttributes(version) },
         scopeSpans: [
           {
-            scope: { name: 'lorekit-cli', version: String(version) },
+            scope: { name: 'cli', version: String(version) },
             spans: [
               {
                 traceId: traceId ?? randHex(16),
@@ -230,7 +272,7 @@ export function buildMetricsPayload({ version, attributes, startMs, endMs }) {
         resource: { attributes: resourceAttributes(version) },
         scopeMetrics: [
           {
-            scope: { name: 'lorekit-cli', version: String(version) },
+            scope: { name: 'cli', version: String(version) },
             metrics: [
               {
                 name: 'lorekit.cli.invocations',