@cullit/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EnrichmentType, AIConfig, OutputFormat, JiraConfig, OpenClawConfig, CullConfig } from '@cullit/config';
+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 {
@@ -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;
@@ -62,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;
@@ -71,9 +71,17 @@ interface PipelineResult {
     duration: number;
 }
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.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"];
+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"];
 
 type LogLevel = 'quiet' | 'normal' | 'verbose';
 interface Logger {
@@ -115,63 +123,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 fetch;
-    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.
@@ -186,13 +137,17 @@ 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;
 
 /**
  * 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.
@@ -200,66 +155,7 @@ declare class StdoutPublisher implements Publisher {
 declare class FilePublisher implements Publisher {
     private path;
     constructor(path: string);
-    publish(notes: ReleaseNotes, format: OutputFormat): Promise<void>;
-}
-/**
- * Posts release notes to a Slack channel via webhook.
- */
-declare class SlackPublisher implements Publisher {
-    private webhookUrl;
-    constructor(webhookUrl: string);
-    publish(notes: ReleaseNotes, _format: OutputFormat): Promise<void>;
-    private buildSlackMessage;
-}
-/**
- * Posts release notes to Discord via webhook.
- */
-declare class DiscordPublisher implements Publisher {
-    private webhookUrl;
-    constructor(webhookUrl: string);
-    publish(notes: ReleaseNotes, _format: OutputFormat): Promise<void>;
-    private buildDiscordMessage;
-}
-/**
- * Creates or updates a GitHub Release via the GitHub API.
- * Requires GITHUB_TOKEN env var (provided automatically in GitHub Actions).
- */
-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;
-}
-
-/**
- * Enriches git diff with Jira ticket details.
- * Extracts PROJ-123 style keys from commit messages and fetches from Jira REST API.
- */
-declare class JiraEnricher implements Enricher {
-    private config;
-    constructor(config: JiraConfig);
-    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
-    private extractUniqueKeys;
-    private fetchTicket;
-}
-
-/**
- * Enriches git diff with Linear issue details.
- * Extracts issue identifiers from commit messages and branch names.
- */
-declare class LinearEnricher implements Enricher {
-    private apiKey;
-    constructor(apiKey?: string);
-    enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
-    private fetchIssuesIndividually;
-    private extractUniqueKeys;
-    private fetchIssuesBatch;
-    private fetchIssue;
+    publish(notes: ReleaseNotes, format: OutputFormat, preformatted?: string): Promise<void>;
 }
 
 type SemverBump = 'patch' | 'minor' | 'major';
@@ -301,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 {
@@ -310,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.
  */
@@ -330,6 +235,42 @@ declare function isEnrichmentAllowed(license: LicenseStatus): boolean;
  */
 declare function upgradeMessage(feature: string): string;
 
+/**
+ * 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.
+ */
+
+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;
+declare function listCollectors(): string[];
+declare function listEnrichers(): string[];
+declare function listGenerators(): string[];
+declare function listPublishers(): string[];
+
+/**
+ * Shared fetch wrapper with timeout support.
+ * Prevents hanging on unresponsive external APIs.
+ */
+declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs?: number): Promise<Response>;
+
 /**
  * Main pipeline: Collect → Enrich → Generate → Format → Publish
  */
@@ -339,4 +280,4 @@ declare function runPipeline(from: string, to: string, config: CullConfig, optio
     logger?: Logger;
 }): Promise<PipelineResult>;
 
-export { AIGenerator, type ChangeCategory, type ChangeEntry, type Collector, DEFAULT_CATEGORIES, DEFAULT_MODELS, DiscordPublisher, type EnrichedContext, type EnrichedTicket, type Enricher, FilePublisher, type Generator, GitCollector, type GitCommit, type GitDiff, GitHubReleasePublisher, JiraCollector, JiraEnricher, type LicenseStatus, type LicenseTier, LinearCollector, LinearEnricher, type LogLevel, type Logger, type PipelineResult, type Publisher, type ReleaseAdvisory, type ReleaseNotes, type SemverBump, SlackPublisher, StdoutPublisher, TemplateGenerator, VERSION, analyzeReleaseReadiness, createLogger, formatNotes, getLatestTag, getRecentTags, isEnrichmentAllowed, isProviderAllowed, isPublisherAllowed, 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, VERSION, analyzeReleaseReadiness, createLogger, fetchWithTimeout, formatNotes, getCollector, getEnricher, getFormatter, getGenerator, getLatestTag, getPublisher, getRecentTags, hasCollector, hasEnricher, hasGenerator, hasPublisher, isEnrichmentAllowed, isProviderAllowed, isPublisherAllowed, listCollectors, listEnrichers, listFormatters, listGenerators, listPublishers, registerCollector, registerEnricher, registerFormatter, registerGenerator, registerPublisher, resolveLicense, runPipeline, upgradeMessage, validateLicense };