@cullit/core 0.4.0 → 1.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { EnrichmentType, OutputFormat, AIConfig, CullConfig } from '@cullit/config';
-export { AIConfig, AIProvider, Audience, CullConfig, EnrichmentType, JiraConfig, LinearConfig, OpenClawConfig, OutputFormat, PublishTarget, PublisherType, SourceConfig, Tone } from '@cullit/config';
+export { AIConfig, AIProvider, Audience, BitbucketConfig, ConfluenceConfig, CullConfig, EnrichmentType, GitLabConfig, JiraConfig, LinearConfig, NotionConfig, OpenClawConfig, OutputFormat, PublishTarget, PublisherType, SourceConfig, Tone } from '@cullit/config';
 
 interface GitCommit {
     hash: string;
@@ -31,7 +31,7 @@ interface EnrichedContext {
     diff: GitDiff;
     tickets: EnrichedTicket[];
 }
-type ChangeCategory = 'features' | 'fixes' | 'breaking' | 'improvements' | 'chores' | 'other';
+type ChangeCategory = string;
 interface ChangeEntry {
     description: string;
     category: ChangeCategory;
@@ -71,9 +71,17 @@ interface PipelineResult {
     duration: number;
 }
 
-declare const VERSION = "0.4.0";
+declare const VERSION = "1.0.0";
 declare const DEFAULT_CATEGORIES: string[];
 declare const DEFAULT_MODELS: Record<string, string>;
+declare const AI_PROVIDERS: readonly ["anthropic", "openai", "gemini", "ollama", "openclaw", "none"];
+declare const OUTPUT_FORMATS: readonly ["markdown", "html", "json"];
+declare const PUBLISHER_TYPES: readonly ["stdout", "file", "slack", "discord", "github-release", "teams", "confluence", "notion", "gitlab-release", "changelog"];
+declare const ENRICHMENT_TYPES: readonly ["jira", "linear"];
+declare const CHANGE_CATEGORIES: readonly ["features", "fixes", "breaking", "improvements", "chores", "other"];
+declare const AUDIENCES: readonly ["developer", "end-user", "executive"];
+declare const TONES: readonly ["professional", "casual", "terse"];
+declare const SOURCE_TYPES: readonly ["local", "jira", "linear", "gitlab", "bitbucket"];
 
 type LogLevel = 'quiet' | 'normal' | 'verbose';
 interface Logger {
@@ -129,6 +137,10 @@ declare class TemplateGenerator implements Generator {
     private buildSummary;
 }
 
+type FormatterFn = (notes: ReleaseNotes) => string;
+declare function registerFormatter(format: string, fn: FormatterFn): void;
+declare function getFormatter(format: string): FormatterFn | undefined;
+declare function listFormatters(): string[];
 declare function formatNotes(notes: ReleaseNotes, format: OutputFormat): string;
 
 /**
@@ -185,6 +197,9 @@ declare function analyzeReleaseReadiness(cwd?: string): ReleaseAdvisory;
  *
  * Free tier (no key):  provider=none, publish to stdout/file only
  * Pro tier (with key): all providers, all publishers, all enrichments
+ *
+ * validateLicense() performs async remote validation with caching.
+ * resolveLicense() remains sync for quick format-only checks (display).
  */
 type LicenseTier = 'free' | 'pro';
 interface LicenseStatus {
@@ -194,9 +209,15 @@ interface LicenseStatus {
 }
 /**
  * Resolve the user's license tier from CULLIT_API_KEY env var.
- * Validates the key format and caches verification result.
+ * Sync format-only check — use for display, not enforcement.
  */
 declare function resolveLicense(): LicenseStatus;
+/**
+ * Validate the license asynchronously with remote server validation.
+ * Falls back to format-only check if offline or no validation URL configured.
+ * Results are cached for 24 hours per key.
+ */
+declare function validateLicense(): Promise<LicenseStatus>;
 /**
  * Check whether the current license allows the requested provider.
  */
@@ -213,6 +234,19 @@ declare function isEnrichmentAllowed(license: LicenseStatus): boolean;
  * Build a human-readable upgrade message for a gated feature.
  */
 declare function upgradeMessage(feature: string): string;
+interface UsageLimits {
+    generationsPerMonth: number;
+    maxProjects: number;
+}
+/**
+ * Get usage limits for a license tier.
+ */
+declare function getTierLimits(tier: string): UsageLimits;
+/**
+ * Report a generation event to the metering service.
+ * Non-blocking — failures are logged but never block the pipeline.
+ */
+declare function reportUsage(project?: string): Promise<void>;
 
 /**
  * Plugin Registry — the seam between free (core) and pro features.
@@ -239,6 +273,10 @@ declare function hasGenerator(provider: string): boolean;
 declare function hasCollector(type: string): boolean;
 declare function hasPublisher(type: string): boolean;
 declare function hasEnricher(type: string): boolean;
+declare function listCollectors(): string[];
+declare function listEnrichers(): string[];
+declare function listGenerators(): string[];
+declare function listPublishers(): string[];
 
 /**
  * Shared fetch wrapper with timeout support.
@@ -255,4 +293,4 @@ declare function runPipeline(from: string, to: string, config: CullConfig, optio
     logger?: Logger;
 }): Promise<PipelineResult>;
 
-export { type ChangeCategory, type ChangeEntry, type Collector, type CollectorFactory, DEFAULT_CATEGORIES, DEFAULT_MODELS, type EnrichedContext, type EnrichedTicket, type Enricher, type EnricherFactory, FilePublisher, type Generator, type GeneratorFactory, GitCollector, type GitCommit, type GitDiff, type LicenseStatus, type LicenseTier, type LogLevel, type Logger, type PipelineResult, type Publisher, type PublisherFactory, type ReleaseAdvisory, type ReleaseNotes, type SemverBump, StdoutPublisher, TemplateGenerator, VERSION, analyzeReleaseReadiness, createLogger, fetchWithTimeout, formatNotes, getCollector, getEnricher, getGenerator, getLatestTag, getPublisher, getRecentTags, hasCollector, hasEnricher, hasGenerator, hasPublisher, isEnrichmentAllowed, isProviderAllowed, isPublisherAllowed, registerCollector, registerEnricher, registerGenerator, registerPublisher, resolveLicense, runPipeline, upgradeMessage };
+export { AI_PROVIDERS, AUDIENCES, CHANGE_CATEGORIES, type ChangeCategory, type ChangeEntry, type Collector, type CollectorFactory, DEFAULT_CATEGORIES, DEFAULT_MODELS, ENRICHMENT_TYPES, type EnrichedContext, type EnrichedTicket, type Enricher, type EnricherFactory, FilePublisher, type Generator, type GeneratorFactory, GitCollector, type GitCommit, type GitDiff, type LicenseStatus, type LicenseTier, type LogLevel, type Logger, OUTPUT_FORMATS, PUBLISHER_TYPES, type PipelineResult, type Publisher, type PublisherFactory, type ReleaseAdvisory, type ReleaseNotes, SOURCE_TYPES, type SemverBump, StdoutPublisher, TONES, TemplateGenerator, type UsageLimits, VERSION, analyzeReleaseReadiness, createLogger, fetchWithTimeout, formatNotes, getCollector, getEnricher, getFormatter, getGenerator, getLatestTag, getPublisher, getRecentTags, getTierLimits, hasCollector, hasEnricher, hasGenerator, hasPublisher, isEnrichmentAllowed, isProviderAllowed, isPublisherAllowed, listCollectors, listEnrichers, listFormatters, listGenerators, listPublishers, registerCollector, registerEnricher, registerFormatter, registerGenerator, registerPublisher, reportUsage, resolveLicense, runPipeline, upgradeMessage, validateLicense };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/constants.ts
-var VERSION = "0.4.0";
+var VERSION = "1.0.0";
 var DEFAULT_CATEGORIES = ["features", "fixes", "breaking", "improvements", "chores"];
 var DEFAULT_MODELS = {
   anthropic: "claude-sonnet-4-20250514",
@@ -8,6 +8,14 @@ var DEFAULT_MODELS = {
   ollama: "llama3.1",
   openclaw: "anthropic/claude-sonnet-4-6"
 };
+var AI_PROVIDERS = ["anthropic", "openai", "gemini", "ollama", "openclaw", "none"];
+var OUTPUT_FORMATS = ["markdown", "html", "json"];
+var PUBLISHER_TYPES = ["stdout", "file", "slack", "discord", "github-release", "teams", "confluence", "notion", "gitlab-release", "changelog"];
+var ENRICHMENT_TYPES = ["jira", "linear"];
+var CHANGE_CATEGORIES = ["features", "fixes", "breaking", "improvements", "chores", "other"];
+var AUDIENCES = ["developer", "end-user", "executive"];
+var TONES = ["professional", "casual", "terse"];
+var SOURCE_TYPES = ["local", "jira", "linear", "gitlab", "bitbucket"];
 
 // src/logger.ts
 function createLogger(level = "normal") {
@@ -289,6 +297,16 @@ var TemplateGenerator = class {
 };
 
 // src/formatter.ts
+var formatters = /* @__PURE__ */ new Map();
+function registerFormatter(format, fn) {
+  formatters.set(format, fn);
+}
+function getFormatter(format) {
+  return formatters.get(format);
+}
+function listFormatters() {
+  return Array.from(formatters.keys());
+}
 var CATEGORY_LABELS = {
   features: "\u2728 Features",
   fixes: "\u{1F41B} Bug Fixes",
@@ -306,16 +324,8 @@ var CATEGORY_ORDER = [
   "other"
 ];
 function formatNotes(notes, format) {
-  switch (format) {
-    case "markdown":
-      return formatMarkdown(notes);
-    case "html":
-      return formatHTML(notes);
-    case "json":
-      return JSON.stringify(notes, null, 2);
-    default:
-      return formatMarkdown(notes);
-  }
+  const fn = formatters.get(format) || formatters.get("markdown");
+  return fn(notes);
 }
 function formatMarkdown(notes) {
   const lines = [];
@@ -386,6 +396,9 @@ function groupByCategory(notes) {
   }
   return grouped;
 }
+registerFormatter("markdown", formatMarkdown);
+registerFormatter("html", formatHTML);
+registerFormatter("json", (notes) => JSON.stringify(notes, null, 2));
 
 // src/publishers/index.ts
 import { writeFileSync } from "fs";
@@ -531,9 +544,28 @@ function analyzeReleaseReadiness(cwd = process.cwd()) {
   };
 }
 
+// src/fetch.ts
+var DEFAULT_TIMEOUT = 3e4;
+async function fetchWithTimeout(url, init, timeoutMs = DEFAULT_TIMEOUT) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new Error(`Request to ${new URL(url).hostname} timed out after ${timeoutMs / 1e3}s`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/gate.ts
 var FREE_PROVIDERS = /* @__PURE__ */ new Set(["none"]);
 var FREE_PUBLISHERS = /* @__PURE__ */ new Set(["stdout", "file"]);
+var LICENSE_CACHE_TTL = 24 * 60 * 60 * 1e3;
+var cachedValidation = null;
 function resolveLicense() {
   const key = process.env.CULLIT_API_KEY?.trim();
   if (!key) {
@@ -544,6 +576,48 @@ function resolveLicense() {
   }
   return { tier: "pro", valid: true };
 }
+async function validateLicense() {
+  const key = process.env.CULLIT_API_KEY?.trim();
+  const validationUrl = process.env.CULLIT_LICENSE_URL?.trim();
+  if (!key) {
+    return { tier: "free", valid: true };
+  }
+  if (!/^clt_[a-zA-Z0-9]{32,}$/.test(key)) {
+    return { tier: "free", valid: false, message: "Invalid CULLIT_API_KEY format. Expected: clt_<key>" };
+  }
+  if (cachedValidation && cachedValidation.key === key && Date.now() < cachedValidation.expiresAt) {
+    return cachedValidation.status;
+  }
+  if (!validationUrl) {
+    return { tier: "pro", valid: true };
+  }
+  try {
+    const res = await fetchWithTimeout(validationUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${key}` },
+      body: JSON.stringify({ key })
+    }, 1e4);
+    if (res.ok) {
+      const data = await res.json();
+      const status2 = {
+        tier: data.tier === "pro" ? "pro" : "free",
+        valid: data.valid !== false,
+        message: data.message
+      };
+      cachedValidation = { status: status2, key, expiresAt: Date.now() + LICENSE_CACHE_TTL };
+      return status2;
+    }
+    const status = {
+      tier: "free",
+      valid: false,
+      message: "License validation failed. Check your API key at https://cullit.io/pricing"
+    };
+    cachedValidation = { status, key, expiresAt: Date.now() + LICENSE_CACHE_TTL };
+    return status;
+  } catch {
+    return { tier: "pro", valid: true };
+  }
+}
 function isProviderAllowed(provider, license) {
   if (license.tier === "pro" && license.valid) return true;
   return FREE_PROVIDERS.has(provider);
@@ -560,6 +634,35 @@ function upgradeMessage(feature) {
    Get your API key at https://cullit.io/pricing
    Then set CULLIT_API_KEY in your environment.`;
 }
+var TIER_LIMITS = {
+  free: { generationsPerMonth: 10, maxProjects: 1 },
+  pro: { generationsPerMonth: 500, maxProjects: 5 },
+  team: { generationsPerMonth: 2e3, maxProjects: 25 },
+  enterprise: { generationsPerMonth: Infinity, maxProjects: Infinity }
+};
+function getTierLimits(tier) {
+  return TIER_LIMITS[tier] || TIER_LIMITS.free;
+}
+async function reportUsage(project = "default") {
+  const key = process.env.CULLIT_API_KEY?.trim();
+  const meterUrl = process.env.CULLIT_METER_URL?.trim();
+  if (!meterUrl || !key) return;
+  try {
+    await fetchWithTimeout(meterUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${key}`
+      },
+      body: JSON.stringify({
+        event: "generation",
+        project,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    }, 5e3);
+  } catch {
+  }
+}
 
 // src/registry.ts
 var collectors = /* @__PURE__ */ new Map();
@@ -602,34 +705,29 @@ function hasPublisher(type) {
 function hasEnricher(type) {
   return enrichers.has(type);
 }
-
-// src/fetch.ts
-var DEFAULT_TIMEOUT = 3e4;
-async function fetchWithTimeout(url, init, timeoutMs = DEFAULT_TIMEOUT) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, { ...init, signal: controller.signal });
-  } catch (err) {
-    if (err.name === "AbortError") {
-      throw new Error(`Request to ${new URL(url).hostname} timed out after ${timeoutMs / 1e3}s`);
-    }
-    throw err;
-  } finally {
-    clearTimeout(timer);
-  }
+function listCollectors() {
+  return Array.from(collectors.keys());
+}
+function listEnrichers() {
+  return Array.from(enrichers.keys());
+}
+function listGenerators() {
+  return Array.from(generators.keys());
+}
+function listPublishers() {
+  return Array.from(publishers.keys());
 }
 
 // src/index.ts
 registerCollector("local", () => new GitCollector());
 registerGenerator("none", () => new TemplateGenerator());
-registerPublisher("stdout", () => new StdoutPublisher());
-registerPublisher("file", (path) => new FilePublisher(path));
+registerPublisher("stdout", (_target) => new StdoutPublisher());
+registerPublisher("file", (target) => new FilePublisher(target.path));
 async function runPipeline(from, to, config, options = {}) {
   const startTime = Date.now();
   const format = options.format || "markdown";
   const log = options.logger || createLogger("normal");
-  const license = resolveLicense();
+  const license = await validateLicense();
   if (!license.valid) {
     throw new Error(license.message || "Invalid CULLIT_API_KEY");
   }
@@ -639,20 +737,12 @@ async function runPipeline(from, to, config, options = {}) {
   const collectorFactory = getCollector(config.source.type);
   if (!collectorFactory) {
     throw new Error(
-      `Source type "${config.source.type}" is not available. ` + (config.source.type === "jira" || config.source.type === "linear" ? "Install @cullit/pro to use this source." : "Valid sources: local")
+      `Source type "${config.source.type}" is not available. ` + (config.source.type !== "local" ? "Install @cullit/pro to use this source." : "Valid sources: local")
     );
   }
-  const sourceLabel = config.source.type === "jira" ? "issues from Jira" : config.source.type === "linear" ? "issues from Linear" : `commits between ${from}..${to}`;
+  const sourceLabel = config.source.type === "local" ? `commits between ${from}..${to}` : `items from ${config.source.type}`;
   log.info(`\xBB Collecting ${sourceLabel}`);
-  let collector;
-  if (config.source.type === "jira") {
-    if (!config.jira) throw new Error("Jira source requires jira config in .cullit.yml");
-    collector = collectorFactory(config.jira);
-  } else if (config.source.type === "linear") {
-    collector = collectorFactory(config.linear?.apiKey);
-  } else {
-    collector = collectorFactory();
-  }
+  const collector = collectorFactory(config);
   const diff = await collector.collect(from, to);
   const itemLabel = config.source.type === "jira" || config.source.type === "linear" ? "issues" : "commits";
   log.info(`\xBB Found ${diff.commits.length} ${itemLabel}${diff.filesChanged ? `, ${diff.filesChanged} files changed` : ""}`);
@@ -673,14 +763,7 @@ async function runPipeline(from, to, config, options = {}) {
       continue;
     }
     log.info(`\xBB Enriching from ${source}...`);
-    let enricher;
-    if (source === "jira" && config.jira) {
-      enricher = enricherFactory(config.jira);
-    } else if (source === "linear") {
-      enricher = enricherFactory(config.linear?.apiKey);
-    } else {
-      continue;
-    }
+    const enricher = enricherFactory(config);
     const enrichedTickets = await enricher.enrich(diff);
     tickets.push(...enrichedTickets);
     log.info(`\xBB ${source}: found ${enrichedTickets.length} ${source === "jira" ? "tickets" : "issues"}`);
@@ -725,26 +808,7 @@ async function runPipeline(from, to, config, options = {}) {
           log.info(`\xBB Skipping ${target.type} \u2014 install @cullit/pro to enable`);
           continue;
         }
-        let publisher;
-        switch (target.type) {
-          case "stdout":
-            publisher = publisherFactory();
-            break;
-          case "file":
-            if (!target.path) continue;
-            publisher = publisherFactory(target.path);
-            break;
-          case "slack":
-          case "discord":
-            if (!target.webhookUrl) continue;
-            publisher = publisherFactory(target.webhookUrl);
-            break;
-          case "github-release":
-            publisher = publisherFactory();
-            break;
-          default:
-            continue;
-        }
+        const publisher = publisherFactory(target);
         await publisher.publish(notes, format, formatted);
         publishedTo.push(target.type === "file" ? `file:${target.path}` : target.type);
       } catch (err) {
@@ -762,11 +826,19 @@ async function runPipeline(from, to, config, options = {}) {
   return { notes, formatted, publishedTo, duration };
 }
 export {
+  AI_PROVIDERS,
+  AUDIENCES,
+  CHANGE_CATEGORIES,
   DEFAULT_CATEGORIES,
   DEFAULT_MODELS,
+  ENRICHMENT_TYPES,
   FilePublisher,
   GitCollector,
+  OUTPUT_FORMATS,
+  PUBLISHER_TYPES,
+  SOURCE_TYPES,
   StdoutPublisher,
+  TONES,
   TemplateGenerator,
   VERSION,
   analyzeReleaseReadiness,
@@ -775,10 +847,12 @@ export {
   formatNotes,
   getCollector,
   getEnricher,
+  getFormatter,
   getGenerator,
   getLatestTag,
   getPublisher,
   getRecentTags,
+  getTierLimits,
   hasCollector,
   hasEnricher,
   hasGenerator,
@@ -786,11 +860,19 @@ export {
   isEnrichmentAllowed,
   isProviderAllowed,
   isPublisherAllowed,
+  listCollectors,
+  listEnrichers,
+  listFormatters,
+  listGenerators,
+  listPublishers,
   registerCollector,
   registerEnricher,
+  registerFormatter,
   registerGenerator,
   registerPublisher,
+  reportUsage,
   resolveLicense,
   runPipeline,
-  upgradeMessage
+  upgradeMessage,
+  validateLicense
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cullit/core",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Core engine for Cullit — AI-powered release note generation.",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@cullit/config": "0.4.0"
+    "@cullit/config": "1.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",