@contractspec/example.product-intent 1.57.0 → 1.59.0

package/dist/node/sync-actions.js

@@ -0,0 +1,491 @@
+// 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/sync-actions.ts
+import { createAgentJsonRunner } from "@contractspec/lib.ai-agent";
+import {
+  buildProjectManagementSyncPayload,
+  extractEvidence,
+  generateTickets,
+  groupProblems,
+  impactEngine,
+  suggestPatch
+} from "@contractspec/lib.product-intent-utils";
+import { LinearProjectManagementProvider } from "@contractspec/integration.providers-impls/impls/linear";
+import { JiraProjectManagementProvider } from "@contractspec/integration.providers-impls/impls/jira";
+import { NotionProjectManagementProvider } from "@contractspec/integration.providers-impls/impls/notion";
+var QUESTION = "Which activation and onboarding friction should we prioritize next?";
+function resolveProvider() {
+  const raw = (process.env.CONTRACTSPEC_PM_PROVIDER ?? "").toLowerCase();
+  if (raw === "linear" || raw === "jira" || raw === "notion")
+    return raw;
+  throw new Error("Set CONTRACTSPEC_PM_PROVIDER to one of: linear, jira, notion");
+}
+async function resolveModelRunner() {
+  const provider = resolveAiProviderName();
+  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 ?? undefined;
+  if (provider !== "ollama" && !apiKey && !proxyUrl && !organizationId) {
+    throw new Error(`Missing API credentials for ${provider}. Set provider API key or CONTRACTSPEC_AI_PROXY_URL.`);
+  }
+  return createAgentJsonRunner({
+    provider: {
+      provider,
+      model,
+      apiKey,
+      baseUrl,
+      proxyUrl,
+      organizationId
+    },
+    temperature: 0,
+    system: "You are a product discovery analyst. Respond with strict JSON only and use exact quotes for citations."
+  });
+}
+function resolveAiProviderName() {
+  const raw = process.env.CONTRACTSPEC_AI_PROVIDER ?? process.env.AI_PROVIDER ?? "openai";
+  const normalized = raw.toLowerCase();
+  const allowed = [
+    "openai",
+    "anthropic",
+    "mistral",
+    "gemini",
+    "ollama"
+  ];
+  if (!allowed.includes(normalized)) {
+    throw new Error(`Unsupported AI provider: ${raw}. Use one of: ${allowed.join(", ")}`);
+  }
+  return normalized;
+}
+function resolveApiKey(provider) {
+  switch (provider.toLowerCase()) {
+    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;
+    default:
+      return;
+  }
+}
+function createLogger() {
+  return {
+    log: () => {
+      return;
+    }
+  };
+}
+async function run() {
+  const provider = resolveProvider();
+  const modelRunner = await resolveModelRunner();
+  const evidenceChunks = await loadEvidenceChunksWithSignals({
+    posthog: resolvePosthogEvidenceOptionsFromEnv() ?? undefined
+  });
+  const findings = await extractEvidence(evidenceChunks, QUESTION, {
+    modelRunner,
+    logger: createLogger(),
+    maxAttempts: 2
+  });
+  const problems = await groupProblems(findings, QUESTION, {
+    modelRunner,
+    logger: createLogger(),
+    maxAttempts: 2
+  });
+  const tickets = await generateTickets(problems, findings, QUESTION, {
+    modelRunner,
+    logger: createLogger(),
+    maxAttempts: 2
+  });
+  const patchIntent = tickets[0] ? await suggestPatch(tickets[0], {
+    modelRunner,
+    logger: createLogger(),
+    maxAttempts: 2
+  }) : undefined;
+  const impact = patchIntent ? impactEngine(patchIntent) : undefined;
+  const payload = buildProjectManagementSyncPayload({
+    question: QUESTION,
+    tickets,
+    patchIntent,
+    impact,
+    options: {
+      includeSummary: true,
+      baseTags: ["product-intent"],
+      defaultPriority: "medium"
+    }
+  });
+  if (process.env.CONTRACTSPEC_PM_DRY_RUN === "true") {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const created = await syncToProvider(provider, payload);
+  console.log(JSON.stringify(created, null, 2));
+}
+async function syncToProvider(provider, payload) {
+  if (provider === "linear") {
+    const client2 = new LinearProjectManagementProvider({
+      apiKey: requireEnv("LINEAR_API_KEY"),
+      teamId: requireEnv("LINEAR_TEAM_ID"),
+      projectId: process.env.LINEAR_PROJECT_ID,
+      stateId: process.env.LINEAR_STATE_ID,
+      assigneeId: process.env.LINEAR_ASSIGNEE_ID,
+      labelIds: splitList(process.env.LINEAR_LABEL_IDS)
+    });
+    return executeSync(client2, payload);
+  }
+  if (provider === "jira") {
+    const client2 = new JiraProjectManagementProvider({
+      siteUrl: requireEnv("JIRA_SITE_URL"),
+      email: requireEnv("JIRA_EMAIL"),
+      apiToken: requireEnv("JIRA_API_TOKEN"),
+      projectKey: process.env.JIRA_PROJECT_KEY,
+      issueType: process.env.JIRA_ISSUE_TYPE,
+      defaultLabels: splitList(process.env.JIRA_DEFAULT_LABELS)
+    });
+    return executeSync(client2, payload);
+  }
+  const client = new NotionProjectManagementProvider({
+    apiKey: requireEnv("NOTION_API_KEY"),
+    databaseId: process.env.NOTION_DATABASE_ID,
+    summaryParentPageId: process.env.NOTION_SUMMARY_PARENT_PAGE_ID,
+    titleProperty: process.env.NOTION_TITLE_PROPERTY,
+    statusProperty: process.env.NOTION_STATUS_PROPERTY,
+    priorityProperty: process.env.NOTION_PRIORITY_PROPERTY,
+    tagsProperty: process.env.NOTION_TAGS_PROPERTY,
+    dueDateProperty: process.env.NOTION_DUE_DATE_PROPERTY,
+    descriptionProperty: process.env.NOTION_DESCRIPTION_PROPERTY
+  });
+  return executeSync(client, payload);
+}
+async function executeSync(client, payload) {
+  const summary = payload.summary ? await client.createWorkItem(payload.summary) : undefined;
+  const items = await client.createWorkItems(payload.items);
+  return { summary, items };
+}
+function requireEnv(key) {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`Missing required env var: ${key}`);
+  }
+  return value;
+}
+function splitList(value) {
+  if (!value)
+    return;
+  const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+run().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/dist/posthog-signals.d.ts

@@ -1,22 +1,18 @@
-import { FunnelDefinition } from "./libs/analytics/dist/types.js";
-import { EvidenceChunk } from "@contractspec/lib.contracts/product-intent/types";
-import { AnalyticsReader, DateRangeInput } from "@contractspec/lib.contracts/integrations/providers/analytics";
-
-//#region src/posthog-signals.d.ts
-interface PosthogEvidenceOptions {
-  reader: AnalyticsReader;
-  dateRange?: DateRangeInput;
-  eventNames?: string[];
-  limit?: number;
-  funnel?: FunnelDefinition;
-  includeFeatureFlags?: boolean;
+import type { AnalyticsReader, DateRangeInput } from '@contractspec/lib.contracts/integrations/providers/analytics';
+import type { EvidenceChunk } from '@contractspec/lib.contracts/product-intent/types';
+import type { FunnelDefinition } from '@contractspec/lib.analytics';
+export interface PosthogEvidenceOptions {
+    reader: AnalyticsReader;
+    dateRange?: DateRangeInput;
+    eventNames?: string[];
+    limit?: number;
+    funnel?: FunnelDefinition;
+    includeFeatureFlags?: boolean;
 }
-interface PosthogEvidenceEnvOptions {
-  defaultLookbackDays?: number;
-  defaultLimit?: number;
+export interface PosthogEvidenceEnvOptions {
+    defaultLookbackDays?: number;
+    defaultLimit?: number;
 }
-declare function loadPosthogEvidenceChunks(options: PosthogEvidenceOptions): Promise<EvidenceChunk[]>;
-declare function resolvePosthogEvidenceOptionsFromEnv(options?: PosthogEvidenceEnvOptions): PosthogEvidenceOptions | null;
-//#endregion
-export { PosthogEvidenceEnvOptions, PosthogEvidenceOptions, loadPosthogEvidenceChunks, resolvePosthogEvidenceOptionsFromEnv };
+export declare function loadPosthogEvidenceChunks(options: PosthogEvidenceOptions): Promise<EvidenceChunk[]>;
+export declare function resolvePosthogEvidenceOptionsFromEnv(options?: PosthogEvidenceEnvOptions): PosthogEvidenceOptions | null;
 //# sourceMappingURL=posthog-signals.d.ts.map

package/dist/posthog-signals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"posthog-signals.d.ts","names":[],"sources":["../src/posthog-signals.ts"],"mappings":";;;;;UAaiB,sBAAA;EACf,MAAA,EAAQ,eAAA;EACR,SAAA,GAAY,cAAA;EACZ,UAAA;EACA,KAAA;EACA,MAAA,GAAS,gBAAA;EACT,mBAAA;AAAA;AAAA,UAGe,yBAAA;EACf,mBAAA;EACA,YAAA;AAAA;AAAA,iBAGoB,yBAAA,CACpB,OAAA,EAAS,sBAAA,GACR,OAAA,CAAQ,aAAA;AAAA,iBAwNK,oCAAA,CACd,OAAA,GAAS,yBAAA,GACR,sBAAA"}
+{"version":3,"file":"posthog-signals.d.ts","sourceRoot":"","sources":["../src/posthog-signals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EACf,MAAM,8DAA8D,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kDAAkD,CAAC;AAEtF,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAGrC,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,aAAa,EAAE,CAAC,CAoB1B;AAoMD,wBAAgB,oCAAoC,CAClD,OAAO,GAAE,yBAA8B,GACtC,sBAAsB,GAAG,IAAI,CA8C/B"}