opencode-feature-factory 0.2.0

package/src/steering-conflicts.js

@@ -0,0 +1,77 @@
+import { PASSING_SECURITY_VERDICTS, PASSING_VALIDATOR_VERDICTS } from "./validate.js";
+
+const PROTECTED_GATE_STATUSES = new Set(["approved", "stopped"]);
+const PROTECTED_SLICE_STATUSES = new Set(["merged", "blocked", "review"]);
+
+export const STEERING_CONFLICT_SUMMARY = "Consumed untrusted steering would require changing accepted durable state; human reconciliation is required.";
+
+export function collectProtectedSteeringState(runDir, run) {
+  void runDir;
+  if (!isRecord(run)) return [];
+
+  const protectedState = [];
+  for (const [gateName, gate] of Object.entries(isRecord(run.gates) ? run.gates : {})) {
+    if (isRecord(gate) && PROTECTED_GATE_STATUSES.has(gate.status)) protectedState.push(`gate:${gateName}`);
+  }
+
+  for (const step of Array.isArray(run.steps) ? run.steps : []) {
+    if (isRecord(step) && step.status === "accepted" && stringValue(step.agent)) protectedState.push(`step:${step.agent}`);
+  }
+
+  for (const slice of Array.isArray(run.slices) ? run.slices : []) {
+    if (isRecord(slice) && PROTECTED_SLICE_STATUSES.has(slice.status) && stringValue(slice.id)) protectedState.push(`slice:${slice.id}`);
+  }
+
+  if (isRecord(run.validator) && PASSING_VALIDATOR_VERDICTS.has(run.validator.verdict)) protectedState.push(`validator:${run.validator.verdict}`);
+  if (isRecord(run.security_review) && PASSING_SECURITY_VERDICTS.has(run.security_review.verdict)) protectedState.push(`security_review:${run.security_review.verdict}`);
+  if (stringValue(run.pr_url)) protectedState.push("pr_url");
+  if (isRecord(run.terminal_result)) protectedState.push("terminal_result");
+
+  return protectedState;
+}
+
+export function formatSteeringConflictReason(ref, protectedState) {
+  const steeringRef = requireNonEmptyString(ref, "steering ref");
+  const protectedText = normalizeProtectedState(protectedState).join(",") || "none";
+  return `operator steering conflicts with accepted durable state: steering=${steeringRef}; protected=${protectedText}; automatic rollback is forbidden`;
+}
+
+export function buildSteeringConflictTerminalResult(run, steering, protectedState, input = {}) {
+  const ref = requireNonEmptyString(steering?.ref, "steering ref");
+  const hash = requireNonEmptyString(steering?.hash, "steering hash");
+  const normalizedProtectedState = normalizeProtectedState(protectedState);
+  const artifacts = {
+    steering_ref: ref,
+    steering_hash: hash,
+    protected_state: normalizedProtectedState.join(","),
+    reason_code: "accepted-state-conflict",
+  };
+  void input;
+
+  return {
+    status: "needs-human",
+    run_id: requireNonEmptyString(run?.run_id, "run_id"),
+    pr_url: stringValue(run?.pr_url) ? run.pr_url : null,
+    reason: formatSteeringConflictReason(ref, normalizedProtectedState),
+    summary: STEERING_CONFLICT_SUMMARY,
+    artifacts,
+  };
+}
+
+function normalizeProtectedState(protectedState) {
+  if (!Array.isArray(protectedState)) return [];
+  return protectedState.filter(stringValue).map((value) => String(value).trim());
+}
+
+function requireNonEmptyString(value, label) {
+  if (!stringValue(value)) throw new Error(`${label} must be a non-empty string`);
+  return String(value).trim();
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/src/telemetry.js

@@ -0,0 +1,419 @@
+import {
+  REDACTED_ENV_VALUE,
+  isSecretShapedEnvKey,
+  isSensitiveEnvKey,
+  isSensitiveEnvValue,
+  scrubSecretEnv,
+} from "./env-snapshot.js";
+
+export const TELEMETRY_TRACER_NAME = "opencode-feature-factory";
+export const FEATURE_FACTORY_TRACEPARENT = "FEATURE_FACTORY_TRACEPARENT";
+export const FEATURE_FACTORY_TRACESTATE = "FEATURE_FACTORY_TRACESTATE";
+export const FEATURE_FACTORY_PARENT_SPAN_ID = "FEATURE_FACTORY_PARENT_SPAN_ID";
+
+const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/iu;
+const ZERO_TRACE_ID = "0".repeat(32);
+const ZERO_SPAN_ID = "0".repeat(16);
+const PARENT_SPAN_ID_PATTERN = /^[0-9a-f]{16}$/iu;
+const CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/u;
+const OTLP_ENV_PATTERN = /^OTEL_EXPORTER_OTLP(?:_[A-Z0-9_]+)?$/u;
+const OTLP_ENDPOINT_PATTERN = /^OTEL_EXPORTER_OTLP(?:_[A-Z0-9_]+)?_ENDPOINT$/u;
+const OTLP_HEADERS_PATTERN = /^OTEL_EXPORTER_OTLP(?:_[A-Z0-9_]+)?_HEADERS$/u;
+// W3C trace-context caps tracestate at 512 characters; oversized values get
+// truncated or dropped by downstream propagators, so reject them up front.
+const MAX_TRACESTATE_LENGTH = 512;
+const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+const SAFE_ATTRIBUTE_ARRAY_TYPES = new Set(["string", "number", "boolean"]);
+// @opentelemetry/api SpanStatusCode.ERROR is the stable enum value 2. Inlined so
+// this module never needs a static import of an optional runtime dependency.
+const SPAN_STATUS_ERROR = 2;
+// Lazy, cached load of the optional @opentelemetry/api package. `undefined` means
+// not yet attempted, `null` means unavailable, an object is the loaded module.
+let cachedOtelApi;
+async function loadOtelApi(importer) {
+  if (typeof importer === "function") {
+    try {
+      return await importer();
+    } catch {
+      return null;
+    }
+  }
+  if (cachedOtelApi !== undefined) return cachedOtelApi;
+  try {
+    cachedOtelApi = await import("@opentelemetry/api");
+  } catch {
+    cachedOtelApi = null;
+  }
+  return cachedOtelApi;
+}
+function noopSpan() {
+  return {
+    recordException() {},
+    setStatus() {},
+    setAttribute() {},
+    end() {},
+  };
+}
+const DEFAULT_CONTENT_CAPTURE = Object.freeze({
+  captureMessages: false,
+  captureToolArguments: false,
+  captureToolResults: false,
+  captureReviews: false,
+  captureEvidence: false,
+});
+
+export async function checkOpenTelemetryApiLoadability(importer = () => import("@opentelemetry/api")) {
+  try {
+    const api = await importer();
+    const missing = ["trace", "context", "SpanStatusCode"].filter((name) => api?.[name] === undefined);
+    if (missing.length > 0) {
+      return {
+        ok: false,
+        package: "@opentelemetry/api",
+        error: `@opentelemetry/api missing expected export(s): ${missing.join(", ")}`,
+      };
+    }
+    return {
+      ok: true,
+      package: "@opentelemetry/api",
+      exports: ["trace", "context", "SpanStatusCode"],
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      package: "@opentelemetry/api",
+      error: sanitizeDiagnosticMessage(error?.message || String(error)),
+    };
+  }
+}
+
+export function sanitizeOtlpEnv(env = process.env) {
+  const output = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (!OTLP_ENV_PATTERN.test(key)) continue;
+    output[key] = OTLP_HEADERS_PATTERN.test(key)
+      ? sanitizeOtlpHeaders(value)
+      : sanitizeTelemetryValue(key, value);
+  }
+  return output;
+}
+
+export function sanitizeOtlpHeaders(value) {
+  if (!stringValue(value)) return [];
+  return String(value)
+    .split(",")
+    .map((entry) => sanitizeOtlpHeaderEntry(entry))
+    .filter(Boolean);
+}
+
+export function sanitizeTelemetryValue(key, value) {
+  if (value === undefined || value === null) return value;
+  const string = String(value);
+  if (isSensitiveEnvKey(key)) return REDACTED_ENV_VALUE;
+  if (OTLP_ENDPOINT_PATTERN.test(key)) return sanitizeOtlpEndpointValue(string);
+  if (isSensitiveEnvValue(string)) return REDACTED_ENV_VALUE;
+  return string;
+}
+
+export function evaluateContentCaptureRisk(options = {}) {
+  const telemetry = {
+    ...DEFAULT_CONTENT_CAPTURE,
+    ...(plainObject(options.telemetry) ? options.telemetry : {}),
+    ...(plainObject(options.config?.telemetry) ? options.config.telemetry : {}),
+    ...(plainObject(options.config?.plugin?.telemetry) ? options.config.plugin.telemetry : {}),
+  };
+  const nativeOpenTelemetry = options.nativeOpenTelemetry === true
+    || options.config?.experimental?.openTelemetry === true;
+  const enabledCaptureFlags = Object.keys(DEFAULT_CONTENT_CAPTURE)
+    .filter((key) => telemetry[key] === true);
+  const risks = [];
+
+  if (nativeOpenTelemetry) {
+    risks.push({
+      kind: "native-opencode-content-capture",
+      severity: "warning",
+      message: "Native opencode/AI SDK OpenTelemetry may capture prompts, completions, tool arguments, or tool results outside feature-factory redaction.",
+    });
+  }
+  if (enabledCaptureFlags.length > 0) {
+    risks.push({
+      kind: "feature-factory-content-capture",
+      severity: "warning",
+      flags: enabledCaptureFlags,
+      message: "Feature-factory content capture is enabled; redact and cap content before setting span attributes or events.",
+    });
+  }
+
+  return {
+    ok: risks.length === 0,
+    level: risks.length === 0 ? "ok" : "warning",
+    redactionActive: true,
+    capture: Object.fromEntries(Object.keys(DEFAULT_CONTENT_CAPTURE).map((key) => [key, telemetry[key] === true])),
+    risks,
+  };
+}
+
+export const contentCaptureRisk = evaluateContentCaptureRisk;
+
+export function validateParentSpanId(value) {
+  if (!stringValue(value)) return validationError("parent span id is required");
+  const spanId = String(value).trim().toLowerCase();
+  if (!PARENT_SPAN_ID_PATTERN.test(spanId)) return validationError("parent span id must be 16 hex characters");
+  if (spanId === ZERO_SPAN_ID) return validationError("parent span id must not be all zeroes");
+  return { ok: true, value: spanId, spanId };
+}
+
+export function validateTraceparent(value) {
+  if (!stringValue(value)) return validationError("traceparent is required");
+  const traceparent = String(value).trim().toLowerCase();
+  const match = TRACEPARENT_PATTERN.exec(traceparent);
+  if (!match) return validationError("traceparent must match W3C format 00-<32hex trace id>-<16hex span id>-<2hex flags>");
+
+  const [, traceId, parentSpanId, flags] = match;
+  if (traceId === ZERO_TRACE_ID) return validationError("traceparent trace id must not be all zeroes");
+  if (parentSpanId === ZERO_SPAN_ID) return validationError("traceparent parent span id must not be all zeroes");
+  return { ok: true, value: traceparent, traceparent, traceId, parentSpanId, flags };
+}
+
+export function validateTracestate(value) {
+  if (value === undefined || value === null) return { ok: true, value: undefined };
+  const tracestate = String(value);
+  if (CONTROL_CHAR_PATTERN.test(tracestate)) return validationError("tracestate must not contain control characters or newlines");
+  if (tracestate.length > MAX_TRACESTATE_LENGTH) return validationError(`tracestate must be at most ${MAX_TRACESTATE_LENGTH} characters`);
+  return { ok: true, value: tracestate, tracestate };
+}
+
+export function validateTraceContext(input = {}) {
+  const output = {};
+  if (input.parentSpanId !== undefined && input.parentSpanId !== null) {
+    const parent = validateParentSpanId(input.parentSpanId);
+    if (!parent.ok) return parent;
+    output.parentSpanId = parent.spanId;
+  }
+  if (input.traceparent !== undefined && input.traceparent !== null) {
+    const parsed = validateTraceparent(input.traceparent);
+    if (!parsed.ok) return parsed;
+    output.traceparent = parsed.traceparent;
+    output.traceId = parsed.traceId;
+    output.traceparentSpanId = parsed.parentSpanId;
+    output.traceFlags = parsed.flags;
+  }
+  if (output.parentSpanId && output.traceparentSpanId && output.parentSpanId !== output.traceparentSpanId) {
+    return validationError("parent span id must match traceparent span id when both are supplied");
+  }
+  if (input.tracestate !== undefined && input.tracestate !== null) {
+    const state = validateTracestate(input.tracestate);
+    if (!state.ok) return state;
+    output.tracestate = state.tracestate;
+  }
+  return { ok: true, ...output };
+}
+
+const TRACE_CONTEXT_ENV_KEYS = Object.freeze([
+  "TRACEPARENT",
+  "TRACESTATE",
+  FEATURE_FACTORY_TRACEPARENT,
+  FEATURE_FACTORY_TRACESTATE,
+  FEATURE_FACTORY_PARENT_SPAN_ID,
+]);
+
+export function prepareTelemetryEnv(baseEnv = process.env, traceContext = {}) {
+  const env = { ...(baseEnv || {}) };
+  const validated = validateTraceContext(traceContext);
+  if (!validated.ok) throw new Error(validated.error);
+
+  const hasExplicitContext = validated.traceparent !== undefined
+    || validated.tracestate !== undefined
+    || validated.parentSpanId !== undefined;
+  if (!hasExplicitContext) return env;
+
+  // An explicit override replaces the whole ambient trace context. Keeping any
+  // inherited field alongside supplied ones can pair a stale TRACESTATE with a
+  // new trace, or a contradictory inherited TRACEPARENT with an explicit parent
+  // span id, leaving the child process with an ambiguous context.
+  for (const key of TRACE_CONTEXT_ENV_KEYS) delete env[key];
+
+  if (validated.traceparent) {
+    env.TRACEPARENT = validated.traceparent;
+    env[FEATURE_FACTORY_TRACEPARENT] = validated.traceparent;
+  }
+  if (validated.tracestate !== undefined) {
+    env.TRACESTATE = validated.tracestate;
+    env[FEATURE_FACTORY_TRACESTATE] = validated.tracestate;
+  }
+  const parentSpanId = validated.parentSpanId || validated.traceparentSpanId;
+  if (parentSpanId) env[FEATURE_FACTORY_PARENT_SPAN_ID] = parentSpanId;
+
+  return env;
+}
+
+export async function withSpan(name, attributesOrCallback = {}, callbackOrOptions, maybeOptions = {}) {
+  const callback = typeof attributesOrCallback === "function" ? attributesOrCallback : callbackOrOptions;
+  if (typeof callback !== "function") throw new Error("withSpan requires a callback");
+  const attributes = typeof attributesOrCallback === "function" ? {} : runAttributes(attributesOrCallback);
+  const options = typeof attributesOrCallback === "function" ? (callbackOrOptions || {}) : maybeOptions;
+
+  const api = await loadOtelApi(options.importer);
+  if (!api) {
+    // @opentelemetry/api is not installed: run the work without emitting a span
+    // rather than crashing. Telemetry is strictly optional at runtime.
+    return callback(noopSpan());
+  }
+
+  const tracer = api.trace.getTracer(options.tracerName || TELEMETRY_TRACER_NAME);
+  return tracer.startActiveSpan(String(name), { attributes }, options.context || api.context.active(), async (span) => {
+    try {
+      return await callback(span);
+    } catch (error) {
+      recordError(span, error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+export function recordError(span, error) {
+  if (!span || !error) return;
+  const message = error instanceof Error ? error.message : String(error);
+  const type = error instanceof Error && error.name ? error.name : typeof error;
+  span.recordException?.(sanitizeException(error));
+  span.setStatus?.({ code: SPAN_STATUS_ERROR, message: sanitizeDiagnosticMessage(message) });
+  span.setAttribute?.("error.type", sanitizeDiagnosticMessage(type));
+}
+
+export function runAttributes(input = {}) {
+  if (!plainObject(input)) return {};
+  const output = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined || value === null || typeof value === "function") continue;
+    if (isUnsafeAttributeKey(key)) continue;
+    output[key] = sanitizeAttribute(key, value);
+  }
+  return output;
+}
+
+function sanitizeOtlpHeaderEntry(entry) {
+  const index = String(entry).indexOf("=");
+  if (index <= 0) return null;
+  const rawName = String(entry).slice(0, index);
+  const name = sanitizeHeaderName(rawName);
+  if (!name) return null;
+  return { name, present: true, value: REDACTED_ENV_VALUE };
+}
+
+function sanitizeOtlpEndpointValue(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return raw;
+
+  try {
+    const parsed = new URL(raw);
+    const safeHost = sanitizeEndpointHost(parsed);
+    const safePath = sanitizeEndpointPath(parsed.pathname, raw);
+    const safeQuery = endpointSearchHasValues(parsed.searchParams) ? `?${REDACTED_ENV_VALUE}` : "";
+    const safeHash = parsed.hash ? `#${REDACTED_ENV_VALUE}` : "";
+    return `${parsed.protocol}//${safeHost}${safePath}${safeQuery}${safeHash}`;
+  } catch {
+    return scrubSecretEnv(raw);
+  }
+}
+
+function sanitizeEndpointHost(parsed) {
+  const hostname = parsed.hostname;
+  const port = parsed.port ? `:${parsed.port}` : "";
+  if (!hostname) return scrubSecretEnv(parsed.host || "");
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return `${hostname}${port}`;
+  const safeHostname = hostname
+    .split(".")
+    .map((label) => sanitizeEndpointComponent(label))
+    .join(".");
+  return `${safeHostname}${port}`;
+}
+
+function sanitizeEndpointPath(pathname, raw) {
+  const safePath = String(pathname || "/")
+    .split("/")
+    .map((segment) => sanitizeEndpointComponent(segment))
+    .join("/") || "/";
+  if (safePath === "/" && !/^[a-z][a-z0-9+.-]*:\/\/[^/?#]+\//iu.test(raw)) return "";
+  return safePath;
+}
+
+function sanitizeEndpointComponent(value) {
+  if (!value) return value;
+  const decoded = safeDecodeURIComponent(value);
+  if (isSensitiveEnvValue(decoded) || scrubSecretEnv(decoded) === REDACTED_ENV_VALUE) return REDACTED_ENV_VALUE;
+  return scrubSecretEnv(value);
+}
+
+function endpointSearchHasValues(searchParams) {
+  for (const [key, value] of searchParams.entries()) {
+    if (key || value) return true;
+  }
+  return false;
+}
+
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function sanitizeHeaderName(value) {
+  const name = String(value || "").trim();
+  if (!name) return null;
+  if (!HEADER_NAME_PATTERN.test(name)) return REDACTED_ENV_VALUE;
+  if (isSensitiveEnvKey(name) || isSensitiveEnvValue(name)) return REDACTED_ENV_VALUE;
+  return name.toLowerCase();
+}
+
+function sanitizeAttribute(key, value) {
+  if (isSensitiveEnvKey(key)) return REDACTED_ENV_VALUE;
+  if (typeof value === "string") return isSensitiveEnvValue(value) ? REDACTED_ENV_VALUE : value;
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    const safe = value
+      .filter((item) => SAFE_ATTRIBUTE_ARRAY_TYPES.has(typeof item))
+      .map((item) => (typeof item === "string" && isSensitiveEnvValue(item) ? REDACTED_ENV_VALUE : item));
+    // OTel attribute arrays must be homogeneous; mixed primitive types get
+    // dropped or rejected by SDKs, so coerce them to a JSON string instead.
+    const homogeneous = new Set(safe.map((item) => typeof item)).size <= 1;
+    return safe.length === value.length && homogeneous ? safe : JSON.stringify(scrubSecretEnv(value));
+  }
+  return JSON.stringify(scrubSecretEnv(value));
+}
+
+function isUnsafeAttributeKey(key) {
+  return isSecretShapedEnvKey(key);
+}
+
+function sanitizeException(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const type = error instanceof Error && error.name ? error.name : typeof error;
+  const exception = {
+    name: sanitizeDiagnosticMessage(type),
+    message: sanitizeDiagnosticMessage(message),
+  };
+  if (error instanceof Error && typeof error.stack === "string") {
+    exception.stack = sanitizeDiagnosticMessage(error.stack);
+  }
+  return exception;
+}
+
+function sanitizeDiagnosticMessage(message) {
+  return scrubSecretEnv(String(message || ""));
+}
+
+function validationError(error) {
+  return { ok: false, error };
+}
+
+function plainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}