@contractspec/example.product-intent 1.57.0 → 1.59.0

package/dist/node/script.js

@@ -0,0 +1,512 @@
+// src/posthog-signals.ts
+import { FunnelAnalyzer } from "@contractspec/lib.analytics/funnel";
+import { PosthogAnalyticsProvider } from "@contractspec/integration.providers-impls/impls/posthog";
+async function loadPosthogEvidenceChunks(options) {
+  const chunks = [];
+  const range = resolveRange(options.dateRange);
+  const eventSummary = await loadEventSummary(options, range);
+  if (eventSummary) {
+    chunks.push(eventSummary);
+  }
+  const funnelEvidence = await loadFunnelEvidence(options, range);
+  if (funnelEvidence) {
+    chunks.push(funnelEvidence);
+  }
+  const featureFlags = await loadFeatureFlagEvidence(options);
+  if (featureFlags) {
+    chunks.push(featureFlags);
+  }
+  return chunks;
+}
+async function loadEventSummary(options, range) {
+  if (!options.reader.queryHogQL)
+    return null;
+  const eventFilter = buildEventFilter(options.eventNames);
+  const limit = options.limit ?? 10;
+  const result = await options.reader.queryHogQL({
+    query: [
+      "select",
+      "  event as eventName,",
+      "  count() as total",
+      "from events",
+      "where timestamp >= {dateFrom} and timestamp < {dateTo}",
+      eventFilter.clause ? `and ${eventFilter.clause}` : "",
+      "group by eventName",
+      "order by total desc",
+      `limit ${limit}`
+    ].filter(Boolean).join(`
+`),
+    values: {
+      dateFrom: range.from.toISOString(),
+      dateTo: range.to.toISOString(),
+      ...eventFilter.values
+    }
+  });
+  const rows = mapRows(result);
+  if (rows.length === 0)
+    return null;
+  const lines = rows.map((row) => {
+    const name = asString(row.eventName) ?? "unknown";
+    const total = asNumber(row.total);
+    return `- ${name}: ${total}`;
+  });
+  return {
+    chunkId: `posthog:event_summary:${range.from.toISOString()}`,
+    text: [
+      `PostHog event summary (${range.from.toISOString()} → ${range.to.toISOString()}):`,
+      ...lines
+    ].join(`
+`),
+    meta: {
+      source: "posthog",
+      kind: "event_summary",
+      dateFrom: range.from.toISOString(),
+      dateTo: range.to.toISOString()
+    }
+  };
+}
+async function loadFunnelEvidence(options, range) {
+  if (!options.funnel)
+    return null;
+  if (!options.reader.getEvents)
+    return null;
+  const events = [];
+  const eventNames = options.funnel.steps.map((step) => step.eventName);
+  for (const eventName of eventNames) {
+    const response = await options.reader.getEvents({
+      event: eventName,
+      dateRange: {
+        from: range.from,
+        to: range.to
+      },
+      limit: options.limit ?? 500
+    });
+    response.results.forEach((event) => {
+      events.push({
+        name: event.event,
+        userId: event.distinctId,
+        tenantId: typeof event.properties?.tenantId === "string" ? event.properties.tenantId : undefined,
+        timestamp: event.timestamp,
+        properties: event.properties
+      });
+    });
+  }
+  if (events.length === 0)
+    return null;
+  const analyzer = new FunnelAnalyzer;
+  const analysis = analyzer.analyze(events, options.funnel);
+  const lines = analysis.steps.map((step) => {
+    return `- ${step.step.eventName}: ${step.count} (conversion ${step.conversionRate}, drop-off ${step.dropOffRate})`;
+  });
+  return {
+    chunkId: `posthog:funnel:${options.funnel.name}`,
+    text: [`PostHog funnel analysis — ${options.funnel.name}:`, ...lines].join(`
+`),
+    meta: {
+      source: "posthog",
+      kind: "funnel",
+      funnelName: options.funnel.name,
+      dateFrom: range.from.toISOString(),
+      dateTo: range.to.toISOString()
+    }
+  };
+}
+async function loadFeatureFlagEvidence(options) {
+  if (!options.includeFeatureFlags)
+    return null;
+  if (!options.reader.getFeatureFlags)
+    return null;
+  const response = await options.reader.getFeatureFlags({ limit: 10 });
+  if (!response.results.length)
+    return null;
+  const lines = response.results.map((flag) => {
+    const key = flag.key ?? "unknown";
+    const active = flag.active ? "active" : "inactive";
+    return `- ${key}: ${active}`;
+  });
+  return {
+    chunkId: "posthog:feature_flags",
+    text: ["PostHog feature flags:", ...lines].join(`
+`),
+    meta: {
+      source: "posthog",
+      kind: "feature_flags"
+    }
+  };
+}
+function resolveRange(dateRange) {
+  const now = new Date;
+  const from = dateRange?.from instanceof Date ? dateRange.from : dateRange?.from ? new Date(dateRange.from) : new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+  const to = dateRange?.to instanceof Date ? dateRange.to : dateRange?.to ? new Date(dateRange.to) : now;
+  return { from, to };
+}
+function buildEventFilter(eventNames) {
+  if (!eventNames || eventNames.length === 0)
+    return {};
+  if (eventNames.length === 1) {
+    return {
+      clause: "event = {event0}",
+      values: { event0: eventNames[0] }
+    };
+  }
+  const values = {};
+  const clauses = eventNames.map((eventName, index) => {
+    values[`event${index}`] = eventName;
+    return `event = {event${index}}`;
+  });
+  return {
+    clause: `(${clauses.join(" or ")})`,
+    values
+  };
+}
+function mapRows(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return [];
+  }
+  const columns = result.columns;
+  return result.results.flatMap((row) => {
+    if (!Array.isArray(row))
+      return [];
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return [record];
+  });
+}
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed))
+      return parsed;
+  }
+  return 0;
+}
+function resolvePosthogEvidenceOptionsFromEnv(options = {}) {
+  const projectId = process.env.POSTHOG_PROJECT_ID;
+  const personalApiKey = process.env.POSTHOG_PERSONAL_API_KEY;
+  if (!projectId || !personalApiKey)
+    return null;
+  const lookbackDays = resolveNumberEnv("POSTHOG_EVIDENCE_LOOKBACK_DAYS", options.defaultLookbackDays ?? 30);
+  const limit = resolveNumberEnv("POSTHOG_EVIDENCE_LIMIT", options.defaultLimit ?? 10);
+  const now = new Date;
+  const from = new Date(now.getTime() - lookbackDays * 24 * 60 * 60 * 1000);
+  const eventNames = resolveCsvEnv("POSTHOG_EVIDENCE_EVENTS");
+  const funnelSteps = resolveCsvEnv("POSTHOG_EVIDENCE_FUNNEL_STEPS");
+  const funnel = funnelSteps && funnelSteps.length ? {
+    name: "posthog-evidence-funnel",
+    steps: funnelSteps.map((eventName, index) => ({
+      id: `step_${index + 1}`,
+      eventName
+    }))
+  } : undefined;
+  const reader = new PosthogAnalyticsProvider({
+    host: process.env.POSTHOG_HOST,
+    projectId,
+    personalApiKey
+  });
+  return {
+    reader,
+    dateRange: { from, to: now },
+    eventNames,
+    limit,
+    funnel,
+    includeFeatureFlags: resolveBooleanEnv("POSTHOG_EVIDENCE_FEATURE_FLAGS", true)
+  };
+}
+function resolveCsvEnv(key) {
+  const value = process.env[key];
+  if (!value)
+    return;
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+function resolveNumberEnv(key, fallback) {
+  const value = process.env[key];
+  if (!value)
+    return fallback;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+function resolveBooleanEnv(key, fallback) {
+  const value = process.env[key];
+  if (value === undefined)
+    return fallback;
+  return value.toLowerCase() === "true";
+}
+
+// src/load-evidence.ts
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+var MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+var DEFAULT_EVIDENCE_ROOT = path.join(MODULE_DIR, "../evidence");
+var DEFAULT_TRANSCRIPT_DIRS = ["interviews", "tickets", "public"];
+var DEFAULT_CHUNK_SIZE = 800;
+function stripYamlFrontMatter(contents) {
+  const start = contents.indexOf("---");
+  if (start === -1)
+    return contents;
+  const end = contents.indexOf("---", start + 3);
+  if (end === -1)
+    return contents;
+  return contents.slice(end + 3).trimStart();
+}
+function chunkTranscript(fileId, text, chunkSize) {
+  const chunks = [];
+  const clean = text.trim();
+  for (let offset = 0, idx = 0;offset < clean.length; idx += 1) {
+    const slice = clean.slice(offset, offset + chunkSize);
+    chunks.push({
+      chunkId: `${fileId}#c_${String(idx).padStart(2, "0")}`,
+      text: slice,
+      meta: { source: fileId }
+    });
+    offset += chunkSize;
+  }
+  return chunks;
+}
+function loadEvidenceChunks(options = {}) {
+  const evidenceRoot = options.evidenceRoot ?? DEFAULT_EVIDENCE_ROOT;
+  const transcriptDirs = options.transcriptDirs ?? DEFAULT_TRANSCRIPT_DIRS;
+  const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  const chunks = [];
+  for (const dir of transcriptDirs) {
+    const fullDir = path.join(evidenceRoot, dir);
+    if (!fs.existsSync(fullDir))
+      continue;
+    for (const fileName of fs.readdirSync(fullDir)) {
+      const ext = path.extname(fileName).toLowerCase();
+      if (ext !== ".md")
+        continue;
+      const filePath = path.join(fullDir, fileName);
+      const raw = fs.readFileSync(filePath, "utf8");
+      const withoutFrontMatter = stripYamlFrontMatter(raw);
+      const baseId = path.parse(fileName).name;
+      const fileChunks = chunkTranscript(baseId, withoutFrontMatter, chunkSize);
+      chunks.push(...fileChunks);
+    }
+  }
+  return chunks;
+}
+async function loadEvidenceChunksWithSignals(options = {}) {
+  const baseChunks = loadEvidenceChunks(options);
+  if (!options.posthog)
+    return baseChunks;
+  const posthogChunks = await loadPosthogEvidenceChunks(options.posthog);
+  return [...baseChunks, ...posthogChunks];
+}
+
+// src/script.ts
+import fs2 from "node:fs";
+import path2 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { createAgentJsonRunner } from "@contractspec/lib.ai-agent";
+import {
+  extractEvidence,
+  generateTickets,
+  groupProblems,
+  impactEngine,
+  suggestPatch
+} from "@contractspec/lib.product-intent-utils";
+var QUESTION = "Which activation and onboarding friction should we prioritize next?";
+var DEFAULT_PROVIDER = "openai";
+var DEFAULT_MODEL = "gpt-5.2";
+var DEFAULT_TEMPERATURE = 0;
+var DEFAULT_MAX_ATTEMPTS = 2;
+var MODULE_DIR2 = path2.dirname(fileURLToPath2(import.meta.url));
+var REPO_ROOT = path2.resolve(MODULE_DIR2, "../../../..");
+var REPO_SCAN_FILES = [
+  "packages/examples/product-intent/src/load-evidence.ts",
+  "packages/examples/product-intent/src/script.ts",
+  "packages/libs/contracts/src/product-intent/contract-patch-intent.ts",
+  "packages/libs/contracts/src/product-intent/spec.ts",
+  "packages/libs/product-intent-utils/src/impact-engine.ts"
+];
+function collectRepoFiles(root, files) {
+  const collected = [];
+  for (const relativePath of files) {
+    const fullPath = path2.join(root, relativePath);
+    if (!fs2.existsSync(fullPath))
+      continue;
+    const content = fs2.readFileSync(fullPath, "utf8");
+    collected.push({ path: relativePath, content });
+  }
+  return collected;
+}
+function resolveProviderName() {
+  const raw = process.env.CONTRACTSPEC_AI_PROVIDER ?? process.env.AI_PROVIDER ?? DEFAULT_PROVIDER;
+  const normalized = raw.toLowerCase();
+  const allowed = [
+    "openai",
+    "anthropic",
+    "mistral",
+    "gemini",
+    "ollama"
+  ];
+  if (!allowed.includes(normalized)) {
+    throw new Error(`Unsupported AI provider '${raw}'. Allowed: ${allowed.join(", ")}`);
+  }
+  return normalized;
+}
+function resolveApiKey(provider) {
+  switch (provider) {
+    case "openai":
+      return process.env.OPENAI_API_KEY;
+    case "anthropic":
+      return process.env.ANTHROPIC_API_KEY;
+    case "mistral":
+      return process.env.MISTRAL_API_KEY;
+    case "gemini":
+      return process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY;
+    case "ollama":
+      return;
+  }
+}
+function resolveTemperature() {
+  const raw = process.env.CONTRACTSPEC_AI_TEMPERATURE ?? process.env.AI_TEMPERATURE;
+  if (!raw)
+    return DEFAULT_TEMPERATURE;
+  const value = Number.parseFloat(raw);
+  return Number.isNaN(value) ? DEFAULT_TEMPERATURE : value;
+}
+function resolveMaxAttempts() {
+  const raw = process.env.CONTRACTSPEC_AI_MAX_ATTEMPTS ?? process.env.AI_MAX_ATTEMPTS;
+  if (!raw)
+    return DEFAULT_MAX_ATTEMPTS;
+  const value = Number.parseInt(raw, 10);
+  return Number.isNaN(value) ? DEFAULT_MAX_ATTEMPTS : Math.max(1, value);
+}
+function writeArtifact(dir, name, contents) {
+  const filePath = path2.join(dir, name);
+  fs2.writeFileSync(filePath, contents, "utf8");
+  return filePath;
+}
+function createPipelineLogger(logDir, runId) {
+  const tracePath = path2.join(logDir, "trace.jsonl");
+  return {
+    log(entry) {
+      const baseName = `${entry.stage}-attempt-${entry.attempt}-${entry.phase}`;
+      const payload = {
+        runId,
+        stage: entry.stage,
+        phase: entry.phase,
+        attempt: entry.attempt,
+        timestamp: entry.timestamp
+      };
+      if (entry.prompt) {
+        payload.promptPath = path2.relative(REPO_ROOT, writeArtifact(logDir, `${baseName}.prompt.txt`, entry.prompt));
+      }
+      if (entry.response) {
+        payload.responsePath = path2.relative(REPO_ROOT, writeArtifact(logDir, `${baseName}.response.txt`, entry.response));
+      }
+      if (entry.error) {
+        payload.errorPath = path2.relative(REPO_ROOT, writeArtifact(logDir, `${baseName}.error.txt`, entry.error));
+      }
+      fs2.appendFileSync(tracePath, `${JSON.stringify(payload)}
+`, "utf8");
+    }
+  };
+}
+async function main() {
+  const provider = resolveProviderName();
+  const temperature = resolveTemperature();
+  const maxAttempts = resolveMaxAttempts();
+  const apiKey = resolveApiKey(provider);
+  const proxyUrl = process.env.CONTRACTSPEC_AI_PROXY_URL;
+  const organizationId = process.env.CONTRACTSPEC_ORG_ID;
+  const baseUrl = process.env.OLLAMA_BASE_URL;
+  const model = process.env.CONTRACTSPEC_AI_MODEL ?? process.env.AI_MODEL ?? (provider === "mistral" ? DEFAULT_MODEL : undefined);
+  if (provider !== "ollama" && !apiKey && !proxyUrl && !organizationId) {
+    throw new Error(`Missing API credentials for ${provider}. Set the provider API key or CONTRACTSPEC_AI_PROXY_URL.`);
+  }
+  const runId = new Date().toISOString().replace(/[:.]/g, "-");
+  const logDir = path2.join(MODULE_DIR2, "../logs", `run-${runId}`);
+  fs2.mkdirSync(logDir, { recursive: true });
+  const logger = createPipelineLogger(logDir, runId);
+  const modelRunner = await createAgentJsonRunner({
+    provider: {
+      provider,
+      model,
+      apiKey,
+      baseUrl,
+      proxyUrl,
+      organizationId
+    },
+    temperature,
+    system: "You are a product discovery analyst. Respond with strict JSON only and use exact quotes for citations."
+  });
+  console.log(`AI provider: ${provider}`);
+  console.log(`Model: ${model ?? "(provider default)"}`);
+  console.log(`Temperature: ${temperature}`);
+  console.log(`Max attempts: ${maxAttempts}`);
+  console.log(`Trace log: ${path2.relative(REPO_ROOT, logDir)}/trace.jsonl`);
+  const posthogEvidence = resolvePosthogEvidenceOptionsFromEnv();
+  const evidenceChunks = await loadEvidenceChunksWithSignals({
+    posthog: posthogEvidence ?? undefined
+  });
+  console.log(`Loaded ${evidenceChunks.length} evidence chunks`);
+  const findings = await extractEvidence(evidenceChunks, QUESTION, {
+    maxFindings: 12,
+    modelRunner,
+    logger,
+    maxAttempts
+  });
+  console.log(`
+Evidence findings:
+`);
+  console.log(JSON.stringify(findings, null, 2));
+  const problems = await groupProblems(findings, QUESTION, {
+    modelRunner,
+    logger,
+    maxAttempts
+  });
+  console.log(`
+Problems:
+`);
+  console.log(JSON.stringify(problems, null, 2));
+  const tickets = await generateTickets(problems, findings, QUESTION, {
+    modelRunner,
+    logger,
+    maxAttempts
+  });
+  console.log(`
+Tickets:
+`);
+  console.log(JSON.stringify(tickets, null, 2));
+  if (!tickets[0]) {
+    console.log(`
+No tickets generated.`);
+    return;
+  }
+  const patchIntent = await suggestPatch(tickets[0], {
+    modelRunner,
+    logger,
+    maxAttempts
+  });
+  console.log(`
+Patch intent:
+`);
+  console.log(JSON.stringify(patchIntent, null, 2));
+  const repoFiles = collectRepoFiles(REPO_ROOT, REPO_SCAN_FILES);
+  const impact = impactEngine(patchIntent, {
+    repoFiles,
+    maxHitsPerChange: 3
+  });
+  console.log(`
+Impact report (deterministic):
+`);
+  console.log(JSON.stringify(impact, null, 2));
+}
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});