avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/design-partner-feedback.js

@@ -0,0 +1,346 @@
+"use strict";
+
+// ── Design Partner Feedback ───────────────────────────────────────────────────
+// Contract: avorelo.designPartnerFeedback.v1
+//
+// Captures and summarizes structured feedback from named design partner sessions.
+// Strictly source=design_partner only — dogfood is NOT counted here.
+// No raw PII, no secrets, no exact cost claims, no public launch claims.
+// Honest insufficient_data when no qualifying sessions exist.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.designPartnerFeedback.v1";
+const SCHEMA_VERSION = 1;
+const DP_DIR_REL = ".claude/cco/feedback/design-partner";
+const SESSIONS_DIR_REL = DP_DIR_REL + "/sessions";
+const SUMMARY_ARTIFACT_REL = DP_DIR_REL + "/latest-summary.json";
+
+// Valid values (keep consistent with alpha-feedback)
+const VALID_FRICTION_TYPES = new Set([
+  "install_confusion", "ai_prompt_unclear", "hook_approval_unclear",
+  "mcp_governance_warn", "token_context_unknown", "proof_missing",
+  "support_bundle_missing", "command_noise", "recovery_needed",
+  "first_value_unclear", "verification_missing", "missing_evidence",
+  "exact_savings_unavailable", "browser_proof_missing",
+  "plugin_distribution_unclear", "other", "unknown",
+]);
+const VALID_SEVERITIES = new Set(["low", "medium", "high", "blocker"]);
+const VALID_ACTIVATION_STAGES = new Set([
+  "unknown", "first_run", "activation", "first_value", "repeat_use", "handoff", "support",
+]);
+const VALID_CONSENT_VALUES = new Set(["provided", "not_recorded"]);
+
+const MAX_TEXT_LENGTH = 500;
+const MAX_FIELD_LENGTH = 64;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeSessionId() {
+  return `dpf-${Date.now()}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+function sanitizeText(text, maxLen) {
+  if (!text || typeof text !== "string") return "";
+  return text.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "").slice(0, maxLen).trim();
+}
+
+function sanitizeField(text) {
+  return sanitizeText(text, MAX_FIELD_LENGTH);
+}
+
+function redactText(text) {
+  if (!text) return "";
+  return text
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-key]")
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}/g, "[redacted-email]");
+}
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch { return null; }
+}
+
+function ensureDirs(cwd) {
+  [DP_DIR_REL, SESSIONS_DIR_REL].forEach(function(rel) {
+    var dir = path.join(cwd, rel);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  });
+}
+
+// ── Session builder ───────────────────────────────────────────────────────────
+
+function buildDesignPartnerFeedbackSession(cwd, opts) {
+  opts = opts || {};
+  var errors = [];
+
+  var partnerAlias = sanitizeField(opts.partnerAlias || "");
+  var activationStage = VALID_ACTIVATION_STAGES.has(opts.activationStage) ? opts.activationStage : "unknown";
+  var frictionType = VALID_FRICTION_TYPES.has(opts.frictionType) ? opts.frictionType : "unknown";
+  var severity = VALID_SEVERITIES.has(opts.severity) ? opts.severity : "medium";
+  var consent = VALID_CONSENT_VALUES.has(opts.consent) ? opts.consent : "not_recorded";
+  var summary = sanitizeText(redactText(opts.summary || ""), MAX_TEXT_LENGTH);
+  var desiredBehavior = sanitizeText(redactText(opts.desiredBehavior || ""), MAX_TEXT_LENGTH);
+  var sessionNotes = sanitizeText(redactText(opts.sessionNotes || ""), MAX_TEXT_LENGTH);
+  var theme = sanitizeField(opts.theme || "");
+  var issueCategory = sanitizeField(opts.issueCategory || "");
+  var consentDetails = opts.consentDetails ? sanitizeText(opts.consentDetails, MAX_TEXT_LENGTH) : null;
+
+  if (!partnerAlias) errors.push("partnerAlias is required");
+  if (!summary) errors.push("summary is required");
+
+  if (errors.length > 0) {
+    return { ok: false, errors: errors, contract: CONTRACT };
+  }
+
+  var session = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    sessionId: makeSessionId(),
+    createdAt: nowIso(),
+    source: "design_partner",
+    partnerAlias: partnerAlias,
+    activationStage: activationStage,
+    frictionType: frictionType,
+    severity: severity,
+    consent: consent,
+    consentDetails: consentDetails,
+    summary: summary,
+    desiredBehavior: desiredBehavior,
+    sessionNotes: sessionNotes,
+    theme: theme || null,
+    issueCategory: issueCategory || null,
+    simulated: opts.simulated === true,
+    redacted: true,
+    noPublicLaunchClaim: true,
+  };
+
+  return { ok: true, session: session, contract: CONTRACT };
+}
+
+function writeDesignPartnerFeedbackSession(cwd, session) {
+  ensureDirs(cwd);
+  var file = path.join(cwd, SESSIONS_DIR_REL, session.sessionId + ".json");
+  fs.writeFileSync(file, JSON.stringify(session, null, 2));
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "design_partner_session_captured",
+      category: "feedback",
+      partnerAlias: session.partnerAlias,
+      frictionType: session.frictionType,
+      severity: session.severity,
+      activationStage: session.activationStage,
+      consent: session.consent,
+    });
+  } catch (e) {}
+  return { ok: true, path: file, sessionId: session.sessionId };
+}
+
+// ── Import ────────────────────────────────────────────────────────────────────
+// Imports an array of sessions from a JSON file (array or single object).
+// Validates each entry, skips invalid ones, writes accepted ones to disk.
+
+function importDesignPartnerFeedback(cwd, filePath, opts) {
+  opts = opts || {};
+  var absPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  var raw;
+  try {
+    raw = safeReadJson(absPath);
+  } catch (e) {
+    return { ok: false, error: "Could not read file: " + filePath, acceptedCount: 0, rejectedCount: 0, redacted: true };
+  }
+  if (!raw) {
+    return { ok: false, error: "File not found or invalid JSON: " + filePath, acceptedCount: 0, rejectedCount: 0, redacted: true };
+  }
+
+  var entries = Array.isArray(raw) ? raw : [raw];
+  var accepted = [], rejected = [];
+
+  entries.forEach(function(entry) {
+    if (!entry || typeof entry !== "object") {
+      rejected.push({ reason: "not_an_object" });
+      return;
+    }
+    // Skip non-design-partner sources silently (source must be design_partner)
+    if (entry.source && entry.source !== "design_partner") {
+      rejected.push({ reason: "wrong_source", source: entry.source });
+      return;
+    }
+    var result = buildDesignPartnerFeedbackSession(cwd, Object.assign({ source: "design_partner" }, entry));
+    if (!result.ok) {
+      rejected.push({ reason: "validation_failed", errors: result.errors });
+      return;
+    }
+    var writeResult = writeDesignPartnerFeedbackSession(cwd, result.session);
+    accepted.push({ sessionId: result.session.sessionId, path: writeResult.path });
+  });
+
+  return {
+    ok: true,
+    acceptedCount: accepted.length,
+    rejectedCount: rejected.length,
+    accepted: accepted,
+    rejected: rejected,
+    redacted: true,
+  };
+}
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+
+function readAllDesignPartnerSessions(cwd) {
+  var dir = path.join(cwd, SESSIONS_DIR_REL);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(function(f) { return f.endsWith(".json"); })
+    .map(function(f) { return safeReadJson(path.join(dir, f)); })
+    .filter(Boolean)
+    .filter(function(s) { return s.source === "design_partner"; });
+}
+
+function buildDesignPartnerFeedbackSummary(cwd, opts) {
+  opts = opts || {};
+  var sessions = readAllDesignPartnerSessions(cwd);
+  var nonSimulated = sessions.filter(function(s) { return !s.simulated; });
+
+  if (nonSimulated.length === 0) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "insufficient_data",
+      readinessStatus: "not_ready",
+      qualifiedSessionCount: 0,
+      totalSessionCount: sessions.length,
+      simulatedCount: sessions.length - nonSimulated.length,
+      frictionBreakdown: {},
+      topFrictions: [],
+      topThemes: [],
+      blockerCount: 0,
+      severityBreakdown: {},
+      activationStageBreakdown: {},
+      consentBreakdown: {},
+      partnerAliasCount: 0,
+      noPublicLaunchClaim: true,
+      noExternalFeedbackClaim: true,
+      redacted: true,
+    };
+  }
+
+  // Count friction types
+  var frictionCounts = {};
+  var themeCounts = {};
+  var severityCounts = {};
+  var stageCounts = {};
+  var consentCounts = {};
+  var partnerAliases = new Set();
+
+  nonSimulated.forEach(function(s) {
+    var ft = s.frictionType || "unknown";
+    frictionCounts[ft] = (frictionCounts[ft] || 0) + 1;
+    if (s.theme) themeCounts[s.theme] = (themeCounts[s.theme] || 0) + 1;
+    var sev = s.severity || "medium";
+    severityCounts[sev] = (severityCounts[sev] || 0) + 1;
+    var stage = s.activationStage || "unknown";
+    stageCounts[stage] = (stageCounts[stage] || 0) + 1;
+    var consent = s.consent || "not_recorded";
+    consentCounts[consent] = (consentCounts[consent] || 0) + 1;
+    if (s.partnerAlias) partnerAliases.add(s.partnerAlias);
+  });
+
+  var topFrictions = Object.entries(frictionCounts)
+    .sort(function(a, b) { return b[1] - a[1]; })
+    .slice(0, 5)
+    .map(function(e) { return { frictionType: e[0], count: e[1] }; });
+
+  var topThemes = Object.entries(themeCounts)
+    .sort(function(a, b) { return b[1] - a[1]; })
+    .slice(0, 5)
+    .map(function(e) { return { theme: e[0], count: e[1] }; });
+
+  var blockerCount = severityCounts["blocker"] || 0;
+  var readinessStatus = nonSimulated.length >= 3 ? "sufficient" : "insufficient";
+  var status = nonSimulated.length >= 3 ? "ready" : "insufficient_data";
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: status,
+    readinessStatus: readinessStatus,
+    qualifiedSessionCount: nonSimulated.length,
+    totalSessionCount: sessions.length,
+    simulatedCount: sessions.length - nonSimulated.length,
+    frictionBreakdown: frictionCounts,
+    topFrictions: topFrictions,
+    topThemes: topThemes,
+    blockerCount: blockerCount,
+    severityBreakdown: severityCounts,
+    activationStageBreakdown: stageCounts,
+    consentBreakdown: consentCounts,
+    partnerAliasCount: partnerAliases.size,
+    noPublicLaunchClaim: true,
+    noExternalFeedbackClaim: true,
+    redacted: true,
+  };
+}
+
+function writeDesignPartnerFeedbackSummary(cwd, summary) {
+  ensureDirs(cwd);
+  fs.writeFileSync(path.join(cwd, SUMMARY_ARTIFACT_REL), JSON.stringify(summary, null, 2));
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "design_partner_feedback_summary_built",
+      category: "feedback",
+      status: summary.status,
+      qualifiedSessionCount: summary.qualifiedSessionCount,
+    });
+  } catch (e) {}
+  return summary;
+}
+
+// ── Text formatter ────────────────────────────────────────────────────────────
+
+function formatDesignPartnerFeedbackText(summary, opts) {
+  opts = opts || {};
+  var lines = [];
+  lines.push("Design partner feedback: " + summary.status);
+  lines.push("Sessions (qualified / total): " + summary.qualifiedSessionCount + " / " + summary.totalSessionCount);
+  if (summary.simulatedCount > 0) lines.push("  Simulated (not counted): " + summary.simulatedCount);
+  lines.push("Partners: " + summary.partnerAliasCount);
+  lines.push("Blockers: " + summary.blockerCount);
+  if (summary.topFrictions && summary.topFrictions.length > 0) {
+    lines.push("Top frictions:");
+    summary.topFrictions.forEach(function(f) {
+      lines.push("  " + f.frictionType + " (" + f.count + ")");
+    });
+  }
+  if (summary.topThemes && summary.topThemes.length > 0) {
+    lines.push("Top themes: " + summary.topThemes.map(function(t) { return t.theme + " (" + t.count + ")"; }).join(", "));
+  }
+  lines.push("No public launch claim.");
+  return lines.join("\n");
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  SUMMARY_ARTIFACT_REL,
+  SESSIONS_DIR_REL,
+  buildDesignPartnerFeedbackSession,
+  writeDesignPartnerFeedbackSession,
+  importDesignPartnerFeedback,
+  buildDesignPartnerFeedbackSummary,
+  writeDesignPartnerFeedbackSummary,
+  formatDesignPartnerFeedbackText,
+  readAllDesignPartnerSessions,
+};