avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/experimentation-events.js

@@ -0,0 +1,547 @@
+"use strict";
+
+const { nowIso } = require("./fsx");
+const {
+  appendProductLearningEvent,
+  redactPayload,
+  redactString,
+  sha256,
+  validateProductLearningEvent,
+} = require("./product-learning-events");
+
+const EXPERIMENTATION_EVENT_GROUPS = Object.freeze({
+  experiment: Object.freeze([
+    "experiment_assigned",
+    "experiment_exposed",
+    "experiment_variant_rendered",
+    "experiment_goal_completed",
+    "experiment_guardrail_triggered",
+    "experiment_result_reviewed",
+    "experiment_decision_made",
+  ]),
+  website: Object.freeze([
+    "page_viewed",
+    "hero_viewed",
+    "hero_cta_clicked",
+    "secondary_cta_clicked",
+    "install_command_copied",
+    "docs_clicked",
+    "demo_started",
+    "demo_completed",
+    "teams_interest_clicked",
+    "faq_opened",
+    "security_section_viewed",
+    "value_section_viewed",
+    "trust_page_viewed",
+  ]),
+  comprehension: Object.freeze([
+    "comprehension_survey_shown",
+    "comprehension_survey_answered",
+    "message_recall_answered",
+    "objection_selected",
+    "confusion_signal_detected",
+  ]),
+  activation: Object.freeze([
+    "activation_started",
+    "activation_completed",
+    "activation_failed",
+    "activation_safe_repair_attempted",
+    "activation_safe_repair_completed",
+    "activation_next_action_shown",
+    "activation_account_skipped",
+    "activation_account_connected",
+    "first_value_shown",
+    "first_value_acknowledged",
+  ]),
+  product_value: Object.freeze([
+    "prompt_shaped",
+    "context_pack_created",
+    "context_reduction_applied",
+    "workspace_map_created",
+    "workspace_map_used",
+    "skill_risk_scan_completed",
+    "risky_instruction_detected",
+    "guard_decision_made",
+    "unsafe_action_blocked",
+    "safe_path_suggested",
+    "safe_path_applied",
+    "route_recommended",
+    "route_applied",
+    "proof_generated",
+    "handoff_created",
+    "reentry_used",
+    "proof_history_requested",
+    "proof_export_requested",
+    "visual_qa_started",
+    "visual_qa_completed",
+    "visual_qa_finding_detected",
+  ]),
+  pricing_pro_intent: Object.freeze([
+    "pricing_viewed",
+    "pricing_plan_clicked",
+    "free_plan_clicked",
+    "pro_plan_clicked",
+    "pro_feature_requested",
+    "pro_limit_reached",
+    "upgrade_page_viewed",
+    "checkout_started",
+    "checkout_abandoned",
+    "upgrade_completed",
+  ]),
+  trust_annoyance: Object.freeze([
+    "pricing_confusion_detected",
+    "trust_faq_opened",
+    "security_concern_clicked",
+    "feedback_negative_submitted",
+    "disable_avorelo_started",
+    "uninstall_started",
+    "pro_nudge_dismissed",
+    "pro_nudge_suppressed",
+  ]),
+});
+
+const EXPERIMENTATION_REQUIRED_EVENTS = Object.freeze([
+  "experiment_assigned",
+  "experiment_exposed",
+  "hero_cta_clicked",
+  "install_command_copied",
+  "pricing_viewed",
+  "activation_started",
+  "activation_completed",
+  "first_value_shown",
+  "comprehension_survey_answered",
+]);
+
+const EXPERIMENTATION_EVENT_REGISTRY = Object.freeze(
+  Object.entries(EXPERIMENTATION_EVENT_GROUPS)
+    .flatMap(([group, eventNames]) => eventNames.map((eventName) => [eventName, Object.freeze({
+      eventName,
+      group,
+      category: group,
+    })]))
+    .reduce((acc, [eventName, definition]) => {
+      acc[eventName] = definition;
+      return acc;
+    }, {})
+);
+
+const EXPERIMENTATION_SOURCE_KEYS = Object.freeze([
+  "utm_source",
+  "utm_campaign",
+  "utm_medium",
+  "utm_term",
+  "utm_content",
+  "referrer",
+]);
+
+const EXPERIMENTATION_METADATA_KEYS = Object.freeze([
+  "experimentId",
+  "variantId",
+  "heroVariant",
+  "pricingVariant",
+  "securityVariant",
+  "demoVisualVariant",
+  "ctaVariant",
+  "assignmentSource",
+]);
+
+const SAFE_TOP_LEVEL_FIELDS = new Set([
+  "anonymousId",
+  "accountId",
+  "projectId",
+  "localRunId",
+  "surface",
+  "source",
+  "experiment",
+  "properties",
+  "timestamp",
+  "occurredAt",
+  "status",
+]);
+
+const SAFE_LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9 _.:/-]{0,119}$/;
+const SAFE_CODE_RE = /^[A-Za-z0-9_.:-]{1,120}$/;
+const WINDOWS_PATH_RE = /[A-Za-z]:[\\/](?:[^\\/\r\n\t]+[\\/])*[^\\/\r\n\t]*/;
+const UNIX_PATH_RE = /(?:^|[\s(])\/(?:Users|home|mnt|var|tmp|etc|opt|srv|usr|repos?|workspace|workspaces|projects?|app|src|tests|scripts|docs|vendor|artifacts|bin|node_modules)(?:\/[^\s)]+)+/;
+const REPO_PATH_RE = /(?:^|[\s(])(?:src|scripts|tests|docs|apps|vendor|artifacts|bin|package\.json|AGENTS\.md|\.claude)(?:[\\/][^\s)]+)*/i;
+const ENV_PATH_RE = /(?:^|[\s(])(?:[A-Za-z]:[\\/])?[^"'`\r\n]*\.env(?:\.[A-Za-z0-9_-]+)?(?:$|[\s)])/i;
+const URL_RE = /^https?:\/\/[^/\s?#]+/i;
+const SECRET_RE = /sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|(?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*[^\s'"]+/i;
+const FREE_TEXT_KEY_RE = /(answer|message|text|notes|recall|objection|feedback|comment|response|transcript|prompt|code|content|body)/i;
+const COMMAND_OUTPUT_KEY_RE = /(stdout|stderr|output|stack|trace|terminal|console|command)/i;
+
+function isRawContentKey(key) {
+  const lowerKey = String(key || "").toLowerCase();
+  if (!lowerKey) return false;
+  if (lowerKey.startsWith("raw")) return true;
+  if (lowerKey === "prompt" || lowerKey.startsWith("prompt") || lowerKey.endsWith("prompt")) return true;
+  if (lowerKey === "code" || lowerKey.startsWith("code") || lowerKey.endsWith("code")) return true;
+  if (lowerKey.includes("secret") || lowerKey.includes("token") || lowerKey.includes("credential")) return true;
+  if (lowerKey.includes("apikey") || lowerKey.includes("api_key") || lowerKey.includes("api-key")) return true;
+  return false;
+}
+
+function isExperimentationEventName(eventName) {
+  return Boolean(EXPERIMENTATION_EVENT_REGISTRY[eventName]);
+}
+
+function listExperimentationEventNames() {
+  return Object.keys(EXPERIMENTATION_EVENT_REGISTRY).sort();
+}
+
+function getExperimentationEventDefinition(eventName) {
+  return EXPERIMENTATION_EVENT_REGISTRY[eventName] || null;
+}
+
+function normalizeSafeCode(value) {
+  const text = String(value || "").trim();
+  if (!text) return null;
+  if (SAFE_CODE_RE.test(text)) return text;
+  return sha256(text);
+}
+
+function normalizeSafeLabel(value) {
+  const text = String(value || "").trim();
+  if (!text) return null;
+  if (SAFE_LABEL_RE.test(text) && !looksPathLikeString(text)) {
+    return redactString(text).slice(0, 120);
+  }
+  return sha256(text);
+}
+
+function normalizeReferrer(value) {
+  const text = String(value || "").trim();
+  if (!text) return null;
+  if (URL_RE.test(text)) {
+    try {
+      const url = new URL(text);
+      return url.origin;
+    } catch {
+      return null;
+    }
+  }
+  return normalizeSafeLabel(text);
+}
+
+function hashIdentifier(value) {
+  const text = String(value || "").trim();
+  if (!text) return null;
+  return sha256(text);
+}
+
+function looksPathLikeString(value) {
+  const text = String(value || "");
+  if (!text || URL_RE.test(text)) return false;
+  return WINDOWS_PATH_RE.test(text)
+    || UNIX_PATH_RE.test(text)
+    || REPO_PATH_RE.test(text)
+    || ENV_PATH_RE.test(text);
+}
+
+function looksLikeCommandOutput(value) {
+  const text = String(value || "");
+  if (!text) return false;
+  if (text.includes("\n")) {
+    return /error:|traceback|exception|^\s*at\s+|PS [A-Za-z]:\\|^\$ |npm ERR!/im.test(text);
+  }
+  return false;
+}
+
+function hashAndMeasure(target, key, value) {
+  const raw = typeof value === "string" ? value : JSON.stringify(value);
+  target[`${key}Hash`] = sha256(raw);
+  target[`${key}Length`] = String(raw || "").length;
+}
+
+function sanitizeSource(source, flags) {
+  const sanitized = {};
+  const input = source && typeof source === "object" ? source : {};
+  for (const key of EXPERIMENTATION_SOURCE_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(input, key)) continue;
+    if (key === "referrer") {
+      sanitized.referrer = normalizeReferrer(input.referrer);
+      continue;
+    }
+    sanitized[key] = normalizeSafeLabel(input[key]);
+  }
+  return sanitized;
+}
+
+function sanitizeExperimentMetadata(experiment, flags) {
+  const sanitized = {};
+  const input = experiment && typeof experiment === "object" ? experiment : {};
+  for (const key of EXPERIMENTATION_METADATA_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(input, key)) continue;
+    sanitized[key] = normalizeSafeCode(input[key]);
+  }
+  return sanitized;
+}
+
+function sanitizeStringValue(target, key, value, flags) {
+  const text = String(value || "");
+  if (!text) {
+    target[key] = "";
+    return;
+  }
+  if (isRawContentKey(key)) {
+    if (/prompt/i.test(key)) flags.containsPrompt = true;
+    if (/code/i.test(key)) flags.containsCode = true;
+    if (/secret|token|credential|apikey|api_key/i.test(key)) flags.containsSecret = true;
+    hashAndMeasure(target, key, text);
+    return;
+  }
+  if (COMMAND_OUTPUT_KEY_RE.test(key) || looksLikeCommandOutput(text)) {
+    flags.containsSensitivePath = flags.containsSensitivePath || looksPathLikeString(text);
+    hashAndMeasure(target, key, text);
+    return;
+  }
+  if (looksPathLikeString(text)) {
+    flags.containsSensitivePath = true;
+    target[key] = "[redacted-path]";
+    target[`${key}Hash`] = sha256(text);
+    return;
+  }
+  if (SECRET_RE.test(text)) {
+    flags.containsSecret = true;
+    target[key] = redactString(text).slice(0, 120);
+    return;
+  }
+  if (FREE_TEXT_KEY_RE.test(key) || text.length > 160 || text.includes("\n")) {
+    hashAndMeasure(target, key, text);
+    return;
+  }
+  target[key] = normalizeSafeLabel(text);
+}
+
+function sanitizePropertiesValue(key, value, flags) {
+  if (value === null || value === undefined) return value ?? null;
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 20).map((entry) => {
+      if (entry === null || entry === undefined) return null;
+      if (typeof entry === "number") return Number.isFinite(entry) ? entry : null;
+      if (typeof entry === "boolean") return entry;
+      if (typeof entry === "string") {
+        if (looksPathLikeString(entry)) {
+          flags.containsSensitivePath = true;
+          return "[redacted-path]";
+        }
+        if (SECRET_RE.test(entry)) {
+          flags.containsSecret = true;
+          return redactString(entry).slice(0, 120);
+        }
+        if (entry.length > 120 || entry.includes("\n")) {
+          return sha256(entry);
+        }
+        return normalizeSafeLabel(entry);
+      }
+      if (typeof entry === "object") {
+        return sanitizeProperties(entry, flags);
+      }
+      return null;
+    });
+  }
+  if (typeof value === "object") {
+    return sanitizeProperties(value, flags);
+  }
+  return null;
+}
+
+function sanitizeProperties(properties, flags) {
+  const sanitized = {};
+  const input = properties && typeof properties === "object" ? properties : {};
+  Object.keys(input).forEach((key) => {
+    const lowerKey = key.toLowerCase();
+    const value = input[key];
+    if (isRawContentKey(lowerKey)) {
+      if (/prompt/.test(lowerKey)) flags.containsPrompt = true;
+      if (/code/.test(lowerKey)) flags.containsCode = true;
+      if (/secret|token|credential|apikey|api_key/.test(lowerKey)) flags.containsSecret = true;
+      hashAndMeasure(sanitized, key, value);
+      return;
+    }
+    if (lowerKey.includes("path") || lowerKey.includes("file")) {
+      flags.containsSensitivePath = true;
+      sanitized[key] = "[redacted-path]";
+      hashAndMeasure(sanitized, key, value);
+      return;
+    }
+    if (COMMAND_OUTPUT_KEY_RE.test(lowerKey)) {
+      flags.containsSensitivePath = flags.containsSensitivePath || looksPathLikeString(value);
+      hashAndMeasure(sanitized, key, value);
+      return;
+    }
+    if (typeof value === "string") {
+      const holder = {};
+      sanitizeStringValue(holder, key, value, flags);
+      if (Object.prototype.hasOwnProperty.call(holder, key)) {
+        sanitized[key] = holder[key];
+      }
+      Object.keys(holder)
+        .filter((holderKey) => holderKey !== key)
+        .forEach((holderKey) => {
+          sanitized[holderKey] = holder[holderKey];
+        });
+      return;
+    }
+    sanitized[key] = sanitizePropertiesValue(key, value, flags);
+  });
+  return redactPayload(sanitized);
+}
+
+function sanitizeLearningPayload(input = {}) {
+  const flags = {
+    containsPrompt: false,
+    containsCode: false,
+    containsSecret: false,
+    containsSensitivePath: false,
+  };
+
+  const topLevelProperties = input.properties && typeof input.properties === "object"
+    ? input.properties
+    : Object.keys(input)
+      .filter((key) => !SAFE_TOP_LEVEL_FIELDS.has(key))
+      .reduce((acc, key) => {
+        acc[key] = input[key];
+        return acc;
+      }, {});
+
+  return {
+    schemaVersion: 1,
+    anonymousIdHash: hashIdentifier(input.anonymousId),
+    accountIdHash: hashIdentifier(input.accountId),
+    projectIdHash: hashIdentifier(input.projectId),
+    localRunIdHash: hashIdentifier(input.localRunId),
+    surface: normalizeSafeCode(input.surface) || "local",
+    source: sanitizeSource(input.source, flags),
+    experiment: sanitizeExperimentMetadata(input.experiment, flags),
+    properties: sanitizeProperties(topLevelProperties, flags),
+    privacy: flags,
+  };
+}
+
+function buildLearningEvent(eventName, input = {}) {
+  const definition = getExperimentationEventDefinition(eventName);
+  const occurredAt = input.timestamp || input.occurredAt || nowIso();
+  const payload = sanitizeLearningPayload(input);
+  payload.timestamp = occurredAt;
+  return {
+    eventName,
+    category: definition ? definition.category : null,
+    occurredAt,
+    surface: payload.surface || "local",
+    status: input.status ? normalizeSafeCode(input.status) || "observed" : "observed",
+    payload,
+  };
+}
+
+function validateLearningEvent(event) {
+  const errors = [];
+  if (!event || typeof event !== "object") {
+    return { valid: false, errors: ["Event must be an object"] };
+  }
+  if (!isExperimentationEventName(event.eventName)) {
+    errors.push(`Unknown experimentation event: ${event.eventName}`);
+  }
+  const definition = getExperimentationEventDefinition(event.eventName);
+  if (definition && event.category !== definition.category) {
+    errors.push(`Event category mismatch for ${event.eventName}`);
+  }
+  const baseValidation = event.category
+    ? validateProductLearningEvent(event)
+    : { valid: false, errors: ["Event category is required"] };
+  errors.push(...baseValidation.errors);
+  return { valid: errors.length === 0, errors };
+}
+
+function maybeThrowStrict(result, options = {}) {
+  if (options.strict && !result.ok) {
+    const error = new Error(result.errors.join("; "));
+    error.result = result;
+    throw error;
+  }
+  return result;
+}
+
+function trackLearningEvent(cwd, eventName, input = {}, options = {}) {
+  const event = buildLearningEvent(eventName, input);
+  const validation = validateLearningEvent(event);
+  if (!validation.valid) {
+    return maybeThrowStrict({
+      ok: false,
+      errors: validation.errors,
+      event,
+    }, options);
+  }
+  const result = appendProductLearningEvent(cwd, event);
+  return maybeThrowStrict({
+    ...result,
+    event: result.event || event,
+  }, options);
+}
+
+function trackExperimentEvent(cwd, eventName, input = {}, options = {}) {
+  const definition = getExperimentationEventDefinition(eventName);
+  if (!definition || definition.group !== "experiment") {
+    return maybeThrowStrict({
+      ok: false,
+      errors: [`${eventName} is not an experiment-group event`],
+      event: null,
+    }, options);
+  }
+  return trackLearningEvent(cwd, eventName, input, options);
+}
+
+function validateExperimentationTaxonomy() {
+  const errors = [];
+  const seen = new Set();
+  Object.entries(EXPERIMENTATION_EVENT_GROUPS).forEach(([group, eventNames]) => {
+    if (!Array.isArray(eventNames) || eventNames.length === 0) {
+      errors.push(`Group ${group} is empty`);
+      return;
+    }
+    eventNames.forEach((eventName) => {
+      if (seen.has(eventName)) {
+        errors.push(`Duplicate event name: ${eventName}`);
+      }
+      seen.add(eventName);
+      const definition = getExperimentationEventDefinition(eventName);
+      if (!definition) {
+        errors.push(`Missing registry definition: ${eventName}`);
+        return;
+      }
+      if (definition.group !== group) {
+        errors.push(`Registry group mismatch for ${eventName}`);
+      }
+    });
+  });
+  EXPERIMENTATION_REQUIRED_EVENTS.forEach((eventName) => {
+    if (!seen.has(eventName)) {
+      errors.push(`Missing required experimentation event: ${eventName}`);
+    }
+  });
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+module.exports = {
+  EXPERIMENTATION_EVENT_GROUPS,
+  EXPERIMENTATION_EVENT_REGISTRY,
+  EXPERIMENTATION_REQUIRED_EVENTS,
+  isExperimentationEventName,
+  listExperimentationEventNames,
+  getExperimentationEventDefinition,
+  sanitizeLearningPayload,
+  buildLearningEvent,
+  validateLearningEvent,
+  validateExperimentationTaxonomy,
+  trackLearningEvent,
+  trackExperimentEvent,
+};

package/scripts/lib/external-capability-compliance.js

@@ -0,0 +1,107 @@
+"use strict";
+
+const { listSources } = require("./source-catalog");
+
+function toComplianceEntry(source) {
+  return {
+    projectName: source.name,
+    sourceUrl: source.sourceUrl,
+    licenseUrl: source.licenseUrl || null,
+    license: source.license,
+    attributionRequired: Boolean(source.attributionRequired),
+    attributionText: source.attributionText || "",
+    noticeRequired: Boolean(source.noticeRequired),
+    bundledCode: false,
+    modifiedCode: false,
+    allowedUseMode: source.defaultUseMode,
+    reviewStatus: source.sourceReviewStatus,
+    lastReviewedAt: source.lastReviewedAt || null,
+    commercialUseMetadata: source.commercialUseMetadata || "",
+    complianceNotes: [
+      ...(source.licenseNotes || []),
+      ...(source.securityNotes || []),
+      ...(source.knownRisks || []),
+    ],
+    avorelo: {
+      integrationPattern: source.productDecision,
+      productNote: (source.adaptationCandidates || []).join(", ") || "reference only",
+      currentStatus: source.productDecision,
+    },
+  };
+}
+
+function listCompliance() {
+  return listSources().map(toComplianceEntry);
+}
+
+const EXTERNAL_CAPABILITY_COMPLIANCE = Object.freeze(listCompliance());
+const COMPLIANCE_MAP = new Map(EXTERNAL_CAPABILITY_COMPLIANCE.map((entry) => [entry.projectName, entry]));
+
+const REQUIRED_COMPLIANCE_FIELDS = [
+  "projectName",
+  "license",
+  "attributionRequired",
+  "attributionText",
+  "noticeRequired",
+  "bundledCode",
+  "modifiedCode",
+  "allowedUseMode",
+  "reviewStatus",
+  "commercialUseMetadata",
+  "complianceNotes",
+];
+
+function validateComplianceEntry(entry) {
+  const errors = [];
+  for (const field of REQUIRED_COMPLIANCE_FIELDS) {
+    if (entry[field] === undefined || entry[field] === null) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+  if (entry.license === "unknown") {
+    if (entry.reviewStatus === "trusted") {
+      errors.push("Unknown license cannot have reviewStatus=trusted");
+    }
+    if (!["reference_only", "blocked"].includes(entry.allowedUseMode)) {
+      errors.push("Unknown license must have allowedUseMode=reference_only or blocked");
+    }
+  }
+  if (entry.reviewStatus === "unreviewed" && entry.allowedUseMode === "internal") {
+    errors.push("Unreviewed external capability cannot have allowedUseMode=internal");
+  }
+  if (entry.bundledCode === true) {
+    errors.push("bundledCode must remain false for external references in this PR");
+  }
+  if (entry.modifiedCode === true) {
+    errors.push("modifiedCode must remain false for external references in this PR");
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function validateAllCompliance() {
+  const errors = [];
+  for (const entry of EXTERNAL_CAPABILITY_COMPLIANCE) {
+    const result = validateComplianceEntry(entry);
+    result.errors.forEach((error) => errors.push(`[${entry.projectName}] ${error}`));
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function getCompliance(projectName) {
+  return COMPLIANCE_MAP.get(String(projectName || "").trim()) || null;
+}
+
+function isSafeToReference(projectName) {
+  const entry = getCompliance(projectName);
+  if (!entry) return false;
+  return entry.allowedUseMode === "reference_only" || entry.allowedUseMode === "adapted_internal";
+}
+
+module.exports = {
+  EXTERNAL_CAPABILITY_COMPLIANCE,
+  validateComplianceEntry,
+  validateAllCompliance,
+  getCompliance,
+  listCompliance,
+  isSafeToReference,
+};