@cullit/core 0.1.0 → 0.4.0

package/dist/index.d.ts

@@ -1,50 +1,6 @@
-type AIProvider = 'anthropic' | 'openai' | 'gemini' | 'ollama' | 'openclaw' | 'none';
-type Audience = 'developer' | 'end-user' | 'executive';
-type Tone = 'professional' | 'casual' | 'terse';
-type OutputFormat = 'markdown' | 'html' | 'json';
-type PublisherType = 'stdout' | 'github-release' | 'slack' | 'discord' | 'file';
-type EnrichmentType = 'jira' | 'linear';
-interface AIConfig {
-    provider: AIProvider;
-    model?: string;
-    apiKey?: string;
-    audience: Audience;
-    tone: Tone;
-    categories: string[];
-    maxTokens?: number;
-}
-interface SourceConfig {
-    type: 'local' | 'jira' | 'linear';
-    owner?: string;
-    repo?: string;
-    enrichment?: EnrichmentType[];
-}
-interface PublishTarget {
-    type: PublisherType;
-    channel?: string;
-    webhookUrl?: string;
-    path?: string;
-}
-interface JiraConfig {
-    domain: string;
-    email?: string;
-    apiToken?: string;
-}
-interface LinearConfig {
-    apiKey?: string;
-}
-interface OpenClawConfig {
-    baseUrl?: string;
-    token?: string;
-}
-interface CullConfig {
-    ai: AIConfig;
-    source: SourceConfig;
-    publish: PublishTarget[];
-    jira?: JiraConfig;
-    linear?: LinearConfig;
-    openclaw?: OpenClawConfig;
-}
+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';
+
 interface GitCommit {
     hash: string;
     shortHash: string;
@@ -106,7 +62,7 @@ interface Generator {
     generate(context: EnrichedContext, config: AIConfig): Promise<ReleaseNotes>;
 }
 interface Publisher {
-    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+    publish(notes: ReleaseNotes, format: OutputFormat, preformatted?: string): Promise<void>;
 }
 interface PipelineResult {
     notes: ReleaseNotes;
@@ -115,10 +71,19 @@ interface PipelineResult {
     duration: number;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.4.0";
 declare const DEFAULT_CATEGORIES: string[];
 declare const DEFAULT_MODELS: Record<string, string>;
 
+type LogLevel = 'quiet' | 'normal' | 'verbose';
+interface Logger {
+    info(msg: string): void;
+    verbose(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+declare function createLogger(level?: LogLevel): Logger;
+
 /**
  * Collects git log data between two refs (tags, branches, or commit SHAs).
  * Extracts commits, PR numbers, and issue keys from commit messages.
@@ -150,63 +115,6 @@ declare function getRecentTags(cwd?: string, count?: number): string[];
  */
 declare function getLatestTag(cwd?: string): string | null;
 
-/**
- * Collects release data directly from Jira (no git required).
- * Queries completed issues by JQL (project, sprint, date range, etc.)
- * and converts them into the GitDiff format for the pipeline.
- *
- * Usage:
- *   --from "project = PROJ AND sprint = 'Sprint 42'"
- *   --from "project = PROJ AND resolved >= '2025-03-01'"
- *   --from "project = PROJ AND fixVersion = 'v2.0'"
- */
-declare class JiraCollector implements Collector {
-    private config;
-    constructor(config: JiraConfig);
-    collect(from: string, to: string): Promise<GitDiff>;
-    private buildJQL;
-    private fetchIssues;
-}
-
-/**
- * Collects release data directly from Linear (no git required).
- * Queries completed issues by project, cycle, or team.
- *
- * Usage:
- *   --from "team:ENG"              (completed issues from team ENG, last 30 days)
- *   --from "project:Project Name"  (completed issues from a project)
- *   --from "cycle:current"         (current cycle's completed issues)
- *   --from "label:release-v2"      (issues with a specific label)
- */
-declare class LinearCollector implements Collector {
-    private apiKey;
-    constructor(apiKey?: string);
-    collect(from: string, to: string): Promise<GitDiff>;
-    private parseFilter;
-    private fetchIssues;
-    private buildFilterClause;
-}
-
-/**
- * Generates release notes using AI.
- * Supports Anthropic, OpenAI, Gemini, Ollama, OpenClaw — BYOK.
- */
-declare class AIGenerator implements Generator {
-    private openclawConfig?;
-    private timeoutMs;
-    constructor(openclawConfig?: OpenClawConfig, timeoutMs?: number);
-    private fetchWithTimeout;
-    generate(context: EnrichedContext, config: AIConfig): Promise<ReleaseNotes>;
-    private resolveApiKey;
-    private buildPrompt;
-    private callAnthropic;
-    private callOpenAI;
-    private callGemini;
-    private callOllama;
-    private callOpenClaw;
-    private parseResponse;
-}
-
 /**
  * Template-based release notes generator — no AI required.
  * Groups commits by conventional commit prefix and ticket type.
@@ -227,7 +135,7 @@ declare function formatNotes(notes: ReleaseNotes, format: OutputFormat): string;
  * Outputs release notes to stdout (default).
  */
 declare class StdoutPublisher implements Publisher {
-    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+    publish(notes: ReleaseNotes, format: OutputFormat, preformatted?: string): Promise<void>;
 }
 /**
  * Writes release notes to a file.
@@ -235,65 +143,108 @@ declare class StdoutPublisher implements Publisher {
 declare class FilePublisher implements Publisher {
     private path;
     constructor(path: string);
-    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
+    publish(notes: ReleaseNotes, format: OutputFormat, preformatted?: string): Promise<void>;
+}
+
+type SemverBump = 'patch' | 'minor' | 'major';
+interface ReleaseAdvisory {
+    /** Whether a release is recommended now */
+    shouldRelease: boolean;
+    /** Suggested semver bump type */
+    suggestedBump: SemverBump;
+    /** Current (latest) version tag */
+    currentVersion: string | null;
+    /** What the next version would be */
+    nextVersion: string | null;
+    /** Number of unreleased commits */
+    commitCount: number;
+    /** Number of unique contributors */
+    contributorCount: number;
+    /** Days since last release */
+    daysSinceRelease: number | null;
+    /** Breakdown of commit types */
+    breakdown: {
+        features: number;
+        fixes: number;
+        breaking: number;
+        chores: number;
+        other: number;
+    };
+    /** Human-readable reasons for the recommendation */
+    reasons: string[];
 }
 /**
- * Posts release notes to a Slack channel via webhook.
+ * Analyzes the repo state and provides a release recommendation.
+ * Examines commits since the last tag, categorizes them via conventional
+ * commit patterns, and applies industry-standard heuristics.
  */
-declare class SlackPublisher implements Publisher {
-    private webhookUrl;
-    constructor(webhookUrl: string);
-    publish(notes: ReleaseNotes, _format: OutputFormat): Promise<void>;
-    private buildSlackMessage;
-}
+declare function analyzeReleaseReadiness(cwd?: string): ReleaseAdvisory;
+
 /**
- * Posts release notes to Discord via webhook.
+ * Cullit License Gating
+ *
+ * Free tier (no key):  provider=none, publish to stdout/file only
+ * Pro tier (with key): all providers, all publishers, all enrichments
  */
-declare class DiscordPublisher implements Publisher {
-    private webhookUrl;
-    constructor(webhookUrl: string);
-    publish(notes: ReleaseNotes, _format: OutputFormat): Promise<void>;
-    private buildDiscordMessage;
+type LicenseTier = 'free' | 'pro';
+interface LicenseStatus {
+    tier: LicenseTier;
+    valid: boolean;
+    message?: string;
 }
 /**
- * Creates or updates a GitHub Release via the GitHub API.
- * Requires GITHUB_TOKEN env var (provided automatically in GitHub Actions).
+ * Resolve the user's license tier from CULLIT_API_KEY env var.
+ * Validates the key format and caches verification result.
  */
-declare class GitHubReleasePublisher implements Publisher {
-    private token;
-    private owner;
-    private repo;
-    constructor();
-    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
-    private getRelease;
-    private createRelease;
-    private updateRelease;
-    private headers;
-}
+declare function resolveLicense(): LicenseStatus;
+/**
+ * Check whether the current license allows the requested provider.
+ */
+declare function isProviderAllowed(provider: string, license: LicenseStatus): boolean;
+/**
+ * Check whether the current license allows the requested publisher.
+ */
+declare function isPublisherAllowed(publisherType: string, license: LicenseStatus): boolean;
+/**
+ * Check whether the current license allows enrichment (Jira/Linear).
+ */
+declare function isEnrichmentAllowed(license: LicenseStatus): boolean;
+/**
+ * Build a human-readable upgrade message for a gated feature.
+ */
+declare function upgradeMessage(feature: string): string;
 
 /**
- * Enriches git diff with Jira ticket details.
- * Extracts PROJ-123 style keys from commit messages and fetches from Jira REST API.
+ * Plugin Registry — the seam between free (core) and pro features.
+ *
+ * Core registers: git collector, template generator, stdout/file publishers.
+ * Pro registers:  AI generator, Jira/Linear collectors + enrichers, Slack/Discord/GitHub publishers.
+ *
+ * The CLI calls `await import('@cullit/pro')` to load pro plugins if installed.
  */
-declare class JiraEnricher implements Enricher {
-    private config;
-    constructor(config: JiraConfig);
-    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
-    private extractUniqueKeys;
-    private fetchTicket;
-}
+
+type CollectorFactory = (...args: any[]) => Collector;
+type EnricherFactory = (...args: any[]) => Enricher;
+type GeneratorFactory = (...args: any[]) => Generator;
+type PublisherFactory = (...args: any[]) => Publisher;
+declare function registerCollector(type: string, factory: CollectorFactory): void;
+declare function registerEnricher(type: string, factory: EnricherFactory): void;
+declare function registerGenerator(provider: string, factory: GeneratorFactory): void;
+declare function registerPublisher(type: string, factory: PublisherFactory): void;
+declare function getCollector(type: string): CollectorFactory | undefined;
+declare function getEnricher(type: string): EnricherFactory | undefined;
+declare function getGenerator(provider: string): GeneratorFactory | undefined;
+declare function getPublisher(type: string): PublisherFactory | undefined;
+declare function hasGenerator(provider: string): boolean;
+declare function hasCollector(type: string): boolean;
+declare function hasPublisher(type: string): boolean;
+declare function hasEnricher(type: string): boolean;
 
 /**
- * Enriches git diff with Linear issue details.
- * Extracts issue identifiers from commit messages and branch names.
+ * Shared fetch wrapper with timeout support.
+ * Prevents hanging on unresponsive external APIs.
  */
-declare class LinearEnricher implements Enricher {
-    private apiKey;
-    constructor(apiKey?: string);
-    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
-    private extractUniqueKeys;
-    private fetchIssue;
-}
+declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs?: number): Promise<Response>;
 
 /**
  * Main pipeline: Collect → Enrich → Generate → Format → Publish
@@ -301,6 +252,7 @@ declare class LinearEnricher implements Enricher {
 declare function runPipeline(from: string, to: string, config: CullConfig, options?: {
     format?: OutputFormat;
     dryRun?: boolean;
+    logger?: Logger;
 }): Promise<PipelineResult>;
 
-export { type AIConfig, AIGenerator, type AIProvider, type Audience, type ChangeCategory, type ChangeEntry, type Collector, type CullConfig, DEFAULT_CATEGORIES, DEFAULT_MODELS, DiscordPublisher, type EnrichedContext, type EnrichedTicket, type Enricher, type EnrichmentType, FilePublisher, type Generator, GitCollector, type GitCommit, type GitDiff, GitHubReleasePublisher, JiraCollector, type JiraConfig, JiraEnricher, LinearCollector, type LinearConfig, LinearEnricher, type OpenClawConfig, type OutputFormat, type PipelineResult, type PublishTarget, type Publisher, type PublisherType, type ReleaseNotes, SlackPublisher, type SourceConfig, StdoutPublisher, TemplateGenerator, type Tone, VERSION, formatNotes, getLatestTag, getRecentTags, runPipeline };
+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 };