@cullit/core 0.1.0 → 0.3.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, AIConfig, OutputFormat, JiraConfig, OpenClawConfig, 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;
@@ -115,10 +71,19 @@ interface PipelineResult {
     duration: number;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.3.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.
@@ -195,7 +160,7 @@ declare class AIGenerator implements Generator {
     private openclawConfig?;
     private timeoutMs;
     constructor(openclawConfig?: OpenClawConfig, timeoutMs?: number);
-    private fetchWithTimeout;
+    private fetch;
     generate(context: EnrichedContext, config: AIConfig): Promise<ReleaseNotes>;
     private resolveApiKey;
     private buildPrompt;
@@ -291,16 +256,87 @@ declare class LinearEnricher implements Enricher {
     private apiKey;
     constructor(apiKey?: string);
     enrich(diff: GitDiff): Promise<EnrichedTicket[]>;
+    private fetchIssuesIndividually;
     private extractUniqueKeys;
+    private fetchIssuesBatch;
     private fetchIssue;
 }
 
+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[];
+}
+/**
+ * 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 function analyzeReleaseReadiness(cwd?: string): ReleaseAdvisory;
+
+/**
+ * Cullit License Gating
+ *
+ * Free tier (no key):  provider=none, publish to stdout/file only
+ * Pro tier (with key): all providers, all publishers, all enrichments
+ */
+type LicenseTier = 'free' | 'pro';
+interface LicenseStatus {
+    tier: LicenseTier;
+    valid: boolean;
+    message?: string;
+}
+/**
+ * Resolve the user's license tier from CULLIT_API_KEY env var.
+ * Validates the key format and caches verification result.
+ */
+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;
+
 /**
  * Main pipeline: Collect → Enrich → Generate → Format → Publish
  */
 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 { 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 };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/constants.ts
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 var DEFAULT_CATEGORIES = ["features", "fixes", "breaking", "improvements", "chores"];
 var DEFAULT_MODELS = {
   anthropic: "claude-sonnet-4-20250514",
@@ -9,14 +9,42 @@ var DEFAULT_MODELS = {
   openclaw: "claude-sonnet-4-6"
 };
 
+// src/logger.ts
+function createLogger(level = "normal") {
+  return {
+    info(msg) {
+      if (level !== "quiet") console.log(msg);
+    },
+    verbose(msg) {
+      if (level === "verbose") console.log(msg);
+    },
+    warn(msg) {
+      if (level !== "quiet") console.warn(msg);
+    },
+    error(msg) {
+      console.error(msg);
+    }
+  };
+}
+
 // src/collectors/git.ts
 import { execSync } from "child_process";
+function validateRef(ref) {
+  if (!ref || ref.length > 256) {
+    throw new Error(`Invalid git ref: too ${ref ? "long" : "short"}`);
+  }
+  if (!/^[a-zA-Z0-9._\-/~^]+$/.test(ref)) {
+    throw new Error(`Invalid git ref "${ref}" \u2014 only alphanumeric, dots, dashes, underscores, slashes, tildes, and carets are allowed`);
+  }
+}
 var GitCollector = class {
   cwd;
   constructor(cwd = process.cwd()) {
     this.cwd = cwd;
   }
   async collect(from, to) {
+    validateRef(from);
+    validateRef(to);
     const log = this.getLog(from, to);
     const commits = this.parseLog(log);
     return {
@@ -124,6 +152,23 @@ function getLatestTag(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/collectors/jira.ts
 var JiraCollector = class {
   config;
@@ -154,13 +199,20 @@ var JiraCollector = class {
       const statusFilter = " AND status in (Done, Closed, Resolved)";
       return from.includes("status") ? from : from + statusFilter;
     }
+    if (!/^[A-Z][A-Z0-9_]{0,30}$/.test(from)) {
+      throw new Error(`Invalid Jira project key: "${from}". Must be uppercase letters, digits, or underscores (e.g., PROJ, MY_PROJ).`);
+    }
+    const safeVersion = to.replace(/["'\\]/g, "");
     if (to === "HEAD") {
       return `project = ${from} AND status in (Done, Closed, Resolved) AND resolved >= -30d ORDER BY resolved DESC`;
     }
-    return `project = ${from} AND fixVersion = "${to}" AND status in (Done, Closed, Resolved) ORDER BY resolved DESC`;
+    return `project = ${from} AND fixVersion = "${safeVersion}" AND status in (Done, Closed, Resolved) ORDER BY resolved DESC`;
   }
   async fetchIssues(jql) {
     const { domain, email, apiToken } = this.config;
+    if (!/^[a-zA-Z0-9.-]+\.atlassian\.net$/.test(domain)) {
+      throw new Error(`Invalid Jira domain: "${domain}". Expected format: yourcompany.atlassian.net`);
+    }
     const resolvedEmail = email || process.env.JIRA_EMAIL;
     const resolvedToken = apiToken || process.env.JIRA_API_TOKEN;
     if (!resolvedEmail || !resolvedToken) {
@@ -176,7 +228,7 @@ var JiraCollector = class {
       url.searchParams.set("startAt", String(startAt));
       url.searchParams.set("maxResults", String(maxResults));
       url.searchParams.set("fields", "summary,issuetype,assignee,status,resolution,resolutiondate,updated,labels,priority,description,fixVersions");
-      const response = await fetch(url.toString(), {
+      const response = await fetchWithTimeout(url.toString(), {
         headers: {
           "Authorization": `Basic ${auth}`,
           "Accept": "application/json"
@@ -254,7 +306,32 @@ var LinearCollector = class {
   }
   async fetchIssues(filter) {
     const filterClause = this.buildFilterClause(filter);
-    const query = `
+    const needsVariable = filter.type !== "cycle" || filter.value !== "current";
+    const query = needsVariable ? `
+      query CompletedIssues($filterValue: String!) {
+        issues(
+          filter: {
+            state: { type: { in: ["completed", "canceled"] } }
+            ${filterClause}
+          }
+          first: 100
+          orderBy: completedAt
+        ) {
+          nodes {
+            identifier
+            title
+            description
+            priority
+            completedAt
+            updatedAt
+            assignee { displayName }
+            state { name type }
+            labels { nodes { name } }
+            project { name }
+          }
+        }
+      }
+    ` : `
       query CompletedIssues {
         issues(
           filter: {
@@ -279,13 +356,14 @@ var LinearCollector = class {
         }
       }
     `;
-    const response = await fetch("https://api.linear.app/graphql", {
+    const variables = needsVariable ? { filterValue: filter.value } : void 0;
+    const response = await fetchWithTimeout("https://api.linear.app/graphql", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": this.apiKey
+        "Authorization": `Bearer ${this.apiKey}`
       },
-      body: JSON.stringify({ query })
+      body: JSON.stringify({ query, variables })
     });
     if (!response.ok) {
       const error = await response.text();
@@ -316,16 +394,16 @@ var LinearCollector = class {
   buildFilterClause(filter) {
     switch (filter.type) {
       case "team":
-        return `team: { key: { eq: "${filter.value}" } }`;
+        return `team: { key: { eq: $filterValue } }`;
       case "project":
-        return `project: { name: { containsIgnoreCase: "${filter.value}" } }`;
+        return `project: { name: { containsIgnoreCase: $filterValue } }`;
       case "cycle":
         if (filter.value === "current") {
           return `cycle: { isActive: { eq: true } }`;
         }
-        return `cycle: { name: { containsIgnoreCase: "${filter.value}" } }`;
+        return `cycle: { name: { containsIgnoreCase: $filterValue } }`;
       case "label":
-        return `labels: { name: { eq: "${filter.value}" } }`;
+        return `labels: { name: { eq: $filterValue } }`;
       default:
         return "";
     }
@@ -340,19 +418,8 @@ var AIGenerator = class {
     this.openclawConfig = openclawConfig;
     this.timeoutMs = timeoutMs;
   }
-  async fetchWithTimeout(url, init) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.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 ${this.timeoutMs / 1e3}s`);
-      }
-      throw err;
-    } finally {
-      clearTimeout(timer);
-    }
+  async fetch(url, init) {
+    return fetchWithTimeout(url, init, this.timeoutMs);
   }
   async generate(context, config) {
     const prompt = this.buildPrompt(context, config);
@@ -453,7 +520,7 @@ Rules:
 - If a commit message mentions a breaking change, categorize it as "breaking"`;
   }
   async callAnthropic(prompt, apiKey, model) {
-    const response = await this.fetchWithTimeout("https://api.anthropic.com/v1/messages", {
+    const response = await this.fetch("https://api.anthropic.com/v1/messages", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -474,7 +541,7 @@ Rules:
     return data.content[0]?.text || "";
   }
   async callOpenAI(prompt, apiKey, model) {
-    const response = await this.fetchWithTimeout("https://api.openai.com/v1/chat/completions", {
+    const response = await this.fetch("https://api.openai.com/v1/chat/completions", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -496,7 +563,7 @@ Rules:
   }
   async callGemini(prompt, apiKey, model) {
     const modelId = model || "gemini-2.0-flash";
-    const response = await this.fetchWithTimeout(
+    const response = await this.fetch(
       `https://generativelanguage.googleapis.com/v1beta/models/${modelId}:generateContent?key=${encodeURIComponent(apiKey)}`,
       {
         method: "POST",
@@ -516,7 +583,7 @@ Rules:
   }
   async callOllama(prompt, model) {
     const baseUrl = process.env.OLLAMA_HOST || "http://localhost:11434";
-    const response = await this.fetchWithTimeout(`${baseUrl}/api/chat`, {
+    const response = await this.fetch(`${baseUrl}/api/chat`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -538,7 +605,7 @@ Rules:
     const token = this.openclawConfig?.token || process.env.OPENCLAW_TOKEN || "";
     const headers = { "Content-Type": "application/json" };
     if (token) headers["Authorization"] = `Bearer ${token}`;
-    const response = await this.fetchWithTimeout(`${baseUrl}/v1/chat/completions`, {
+    const response = await this.fetch(`${baseUrl}/v1/chat/completions`, {
       method: "POST",
       headers,
       body: JSON.stringify({
@@ -581,7 +648,7 @@ ${raw.substring(0, 500)}`);
         commitCount: context.diff.commits.length,
         prCount: context.diff.commits.filter((c) => c.prNumber).length,
         ticketCount: context.tickets.length,
-        generatedBy: "cull",
+        generatedBy: "cullit",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString()
       }
     };
@@ -619,7 +686,7 @@ var TemplateGenerator = class {
         commitCount: diff.commits.length,
         prCount: diff.commits.filter((c) => c.prNumber).length,
         ticketCount: tickets.length,
-        generatedBy: "cull-template",
+        generatedBy: "cullit-template",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString()
       }
     };
@@ -755,7 +822,7 @@ function formatMarkdown(notes) {
   }
   if (notes.metadata) {
     lines.push("---");
-    lines.push(`*Generated by [Cull](https://cullit.io) \u2022 ${notes.metadata.commitCount} commits, ${notes.metadata.prCount} PRs*`);
+    lines.push(`*Generated by [Cullit](https://cullit.io) \u2022 ${notes.metadata.commitCount} commits, ${notes.metadata.prCount} PRs*`);
   }
   return lines.join("\n");
 }
@@ -781,7 +848,7 @@ function formatHTML(notes) {
     html += `</ul>`;
   }
   if (notes.metadata) {
-    html += `<footer><small>Generated by <a href="https://cullit.io">Cull</a> &bull; ${notes.metadata.commitCount} commits, ${notes.metadata.prCount} PRs</small></footer>`;
+    html += `<footer><small>Generated by <a href="https://cullit.io">Cullit</a> &bull; ${notes.metadata.commitCount} commits, ${notes.metadata.prCount} PRs</small></footer>`;
   }
   html += `</div>`;
   return html;
@@ -817,10 +884,13 @@ var FilePublisher = class {
 var SlackPublisher = class {
   constructor(webhookUrl) {
     this.webhookUrl = webhookUrl;
+    if (!webhookUrl.startsWith("https://hooks.slack.com/") && !webhookUrl.startsWith("https://hooks.slack-gov.com/")) {
+      throw new Error("Invalid Slack webhook URL \u2014 must start with https://hooks.slack.com/ or https://hooks.slack-gov.com/");
+    }
   }
   async publish(notes, _format) {
     const text = this.buildSlackMessage(notes);
-    const response = await fetch(this.webhookUrl, {
+    const response = await fetchWithTimeout(this.webhookUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ text })
@@ -856,10 +926,13 @@ var SlackPublisher = class {
 var DiscordPublisher = class {
   constructor(webhookUrl) {
     this.webhookUrl = webhookUrl;
+    if (!webhookUrl.startsWith("https://discord.com/api/webhooks/") && !webhookUrl.startsWith("https://discordapp.com/api/webhooks/")) {
+      throw new Error("Invalid Discord webhook URL \u2014 must start with https://discord.com/api/webhooks/");
+    }
   }
   async publish(notes, _format) {
     const content = this.buildDiscordMessage(notes);
-    const response = await fetch(this.webhookUrl, {
+    const response = await fetchWithTimeout(this.webhookUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -867,9 +940,9 @@ var DiscordPublisher = class {
           title: `Release ${notes.version}`,
           description: content,
           color: 15269703,
-          // Cull accent color
+          // Cullit accent color
           timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-          footer: { text: "Generated by Cull" }
+          footer: { text: "Generated by Cullit" }
         }]
       })
     });
@@ -924,7 +997,7 @@ var GitHubReleasePublisher = class {
   }
   async getRelease(tag) {
     const url = `https://api.github.com/repos/${this.owner}/${this.repo}/releases/tags/${encodeURIComponent(tag)}`;
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(url, {
       headers: this.headers()
     });
     if (response.status === 404) return null;
@@ -937,7 +1010,7 @@ var GitHubReleasePublisher = class {
   }
   async createRelease(tag, body, notes) {
     const url = `https://api.github.com/repos/${this.owner}/${this.repo}/releases`;
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(url, {
       method: "POST",
       headers: this.headers(),
       body: JSON.stringify({
@@ -956,7 +1029,7 @@ var GitHubReleasePublisher = class {
   async updateRelease(id, body, notes) {
     const tag = notes.version.startsWith("v") ? notes.version : `v${notes.version}`;
     const url = `https://api.github.com/repos/${this.owner}/${this.repo}/releases/${id}`;
-    const response = await fetch(url, {
+    const response = await fetchWithTimeout(url, {
       method: "PATCH",
       headers: this.headers(),
       body: JSON.stringify({
@@ -1013,7 +1086,7 @@ var JiraEnricher = class {
       throw new Error("Jira credentials not configured. Set JIRA_EMAIL and JIRA_API_TOKEN.");
     }
     const auth = Buffer.from(`${resolvedEmail}:${resolvedToken}`).toString("base64");
-    const response = await fetch(
+    const response = await fetchWithTimeout(
       `https://${domain}/rest/api/3/issue/${key}?fields=summary,issuetype,labels,priority,status,description`,
       {
         headers: {
@@ -1053,6 +1126,14 @@ var LinearEnricher = class {
   async enrich(diff) {
     const keys = this.extractUniqueKeys(diff);
     if (keys.length === 0) return [];
+    try {
+      return await this.fetchIssuesBatch(keys);
+    } catch (err) {
+      console.warn(`\u26A0 Linear batch fetch failed, falling back to individual queries: ${err.message}`);
+      return this.fetchIssuesIndividually(keys);
+    }
+  }
+  async fetchIssuesIndividually(keys) {
     const tickets = [];
     for (const key of keys) {
       try {
@@ -1071,6 +1152,56 @@ var LinearEnricher = class {
     }
     return [...new Set(allKeys)];
   }
+  async fetchIssuesBatch(identifiers) {
+    const query = `
+      query BatchIssues($filter: IssueFilter!) {
+        issues(filter: $filter, first: 100) {
+          nodes {
+            identifier
+            title
+            description
+            priority
+            state { name }
+            labels { nodes { name } }
+          }
+        }
+      }
+    `;
+    const response = await fetchWithTimeout("https://api.linear.app/graphql", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        query,
+        variables: {
+          filter: { identifier: { in: identifiers } }
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Linear API error (${response.status})`);
+    }
+    const data = await response.json();
+    const issues = data.data?.issues?.nodes || [];
+    const priorityMap = {
+      0: "none",
+      1: "urgent",
+      2: "high",
+      3: "medium",
+      4: "low"
+    };
+    return issues.map((issue) => ({
+      key: issue.identifier,
+      title: issue.title,
+      description: issue.description?.substring(0, 500),
+      labels: issue.labels?.nodes?.map((l) => l.name) || [],
+      priority: priorityMap[issue.priority] || void 0,
+      status: issue.state?.name,
+      source: "linear"
+    }));
+  }
   async fetchIssue(identifier) {
     const query = `
       query IssueByIdentifier($id: String!) {
@@ -1086,11 +1217,11 @@ var LinearEnricher = class {
         }
       }
     `;
-    const response = await fetch("https://api.linear.app/graphql", {
+    const response = await fetchWithTimeout("https://api.linear.app/graphql", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": this.apiKey
+        "Authorization": `Bearer ${this.apiKey}`
       },
       body: JSON.stringify({ query, variables: { id: identifier } })
     });
@@ -1119,25 +1250,205 @@ var LinearEnricher = class {
   }
 };
 
+// src/advisor.ts
+import { execSync as execSync2 } from "child_process";
+var COMMIT_PATTERNS = [
+  { pattern: /^breaking[(!:]|^BREAKING CHANGE/i, category: "breaking" },
+  { pattern: /!:/, category: "breaking" },
+  { pattern: /^feat[(!:]|^feature[(!:]/i, category: "features" },
+  { pattern: /^fix[(!:]/i, category: "fixes" },
+  { pattern: /^chore[(!:]|^docs[(!:]|^ci[(!:]|^test[(!:]|^style[(!:]|^refactor[(!:]/i, category: "chores" }
+];
+function categorizeCommit(message) {
+  for (const { pattern, category } of COMMIT_PATTERNS) {
+    if (pattern.test(message)) return category;
+  }
+  return "other";
+}
+function bumpVersion(version, bump) {
+  const prefix = version.startsWith("v") ? "v" : "";
+  const clean = version.replace(/^v/, "");
+  const parts = clean.split(".").map(Number);
+  if (parts.length !== 3 || parts.some(isNaN)) return version;
+  switch (bump) {
+    case "major":
+      return `${prefix}${parts[0] + 1}.0.0`;
+    case "minor":
+      return `${prefix}${parts[0]}.${parts[1] + 1}.0`;
+    case "patch":
+      return `${prefix}${parts[0]}.${parts[1]}.${parts[2] + 1}`;
+  }
+}
+function getCommitsSinceTag(tag, cwd) {
+  const format = "%H|%h|%an|%aI|%s";
+  const separator = "---CULLIT_COMMIT---";
+  try {
+    const log = execSync2(
+      `git log ${tag}..HEAD --format="${format}${separator}" --no-merges`,
+      { cwd, encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 }
+    );
+    if (!log.trim()) return [];
+    return log.split(separator).filter((e) => e.trim()).map((entry) => {
+      const [hash, shortHash, author, date, ...msgParts] = entry.trim().split("|");
+      return {
+        hash: hash.trim(),
+        shortHash: shortHash.trim(),
+        author: author.trim(),
+        date: date.trim(),
+        message: msgParts.join("|").trim()
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+function getTagDate(tag, cwd) {
+  try {
+    const dateStr = execSync2(
+      `git log -1 --format=%aI ${tag}`,
+      { cwd, encoding: "utf-8" }
+    ).trim();
+    return new Date(dateStr);
+  } catch {
+    return null;
+  }
+}
+function analyzeReleaseReadiness(cwd = process.cwd()) {
+  const latestTag = getLatestTag(cwd);
+  const reasons = [];
+  if (!latestTag) {
+    return {
+      shouldRelease: true,
+      suggestedBump: "minor",
+      currentVersion: null,
+      nextVersion: null,
+      commitCount: 0,
+      contributorCount: 0,
+      daysSinceRelease: null,
+      breakdown: { features: 0, fixes: 0, breaking: 0, chores: 0, other: 0 },
+      reasons: ["No tags found. Consider creating your first release."]
+    };
+  }
+  const commits = getCommitsSinceTag(latestTag, cwd);
+  const commitCount = commits.length;
+  const breakdown = { features: 0, fixes: 0, breaking: 0, chores: 0, other: 0 };
+  for (const commit of commits) {
+    breakdown[categorizeCommit(commit.message)]++;
+  }
+  const contributors = new Set(commits.map((c) => c.author));
+  const tagDate = getTagDate(latestTag, cwd);
+  const daysSinceRelease = tagDate ? Math.floor((Date.now() - tagDate.getTime()) / (1e3 * 60 * 60 * 24)) : null;
+  let suggestedBump = "patch";
+  if (breakdown.breaking > 0) {
+    suggestedBump = "major";
+    reasons.push(`${breakdown.breaking} breaking change(s) detected \u2014 major bump recommended`);
+  } else if (breakdown.features > 0) {
+    suggestedBump = "minor";
+    reasons.push(`${breakdown.features} new feature(s) \u2014 minor bump recommended`);
+  } else if (breakdown.fixes > 0) {
+    reasons.push(`${breakdown.fixes} bug fix(es) \u2014 patch bump recommended`);
+  }
+  let shouldRelease = false;
+  if (breakdown.breaking > 0) {
+    shouldRelease = true;
+    reasons.push("\u26A0 Breaking changes should be released and communicated promptly");
+  }
+  const securityCommits = commits.filter(
+    (c) => /security|cve|vuln|exploit|xss|injection|auth.*(fix|patch)/i.test(c.message)
+  );
+  if (securityCommits.length > 0) {
+    shouldRelease = true;
+    reasons.push(`\u{1F512} ${securityCommits.length} security-related commit(s) \u2014 release ASAP`);
+  }
+  if (commitCount >= 5) {
+    shouldRelease = true;
+    reasons.push(`${commitCount} unreleased commits \u2014 consider releasing to keep changes small and reviewable`);
+  }
+  if (daysSinceRelease !== null && daysSinceRelease >= 14 && commitCount > 0) {
+    shouldRelease = true;
+    reasons.push(`${daysSinceRelease} days since last release \u2014 regular cadence helps users stay current`);
+  }
+  if (breakdown.features >= 3) {
+    shouldRelease = true;
+    reasons.push("Multiple features accumulated \u2014 users are missing out");
+  }
+  if (commitCount > 0 && commitCount < 5 && !shouldRelease) {
+    reasons.push(`${commitCount} commit(s) since ${latestTag} \u2014 no urgency, but keep an eye on it`);
+  }
+  if (commitCount === 0) {
+    reasons.push("No unreleased commits \u2014 you're up to date!");
+  }
+  const nextVersion = bumpVersion(latestTag, suggestedBump);
+  return {
+    shouldRelease,
+    suggestedBump,
+    currentVersion: latestTag,
+    nextVersion,
+    commitCount,
+    contributorCount: contributors.size,
+    daysSinceRelease,
+    breakdown,
+    reasons
+  };
+}
+
+// src/gate.ts
+var FREE_PROVIDERS = /* @__PURE__ */ new Set(["none"]);
+var FREE_PUBLISHERS = /* @__PURE__ */ new Set(["stdout", "file"]);
+function resolveLicense() {
+  const key = process.env.CULLIT_API_KEY?.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>" };
+  }
+  return { tier: "pro", valid: true };
+}
+function isProviderAllowed(provider, license) {
+  if (license.tier === "pro" && license.valid) return true;
+  return FREE_PROVIDERS.has(provider);
+}
+function isPublisherAllowed(publisherType, license) {
+  if (license.tier === "pro" && license.valid) return true;
+  return FREE_PUBLISHERS.has(publisherType);
+}
+function isEnrichmentAllowed(license) {
+  return license.tier === "pro" && license.valid;
+}
+function upgradeMessage(feature) {
+  return `\u{1F512} ${feature} requires a Cullit Pro license.
+   Get your API key at https://cullit.io/pricing
+   Then set CULLIT_API_KEY in your environment.`;
+}
+
 // src/index.ts
 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();
+  if (!license.valid) {
+    throw new Error(license.message || "Invalid CULLIT_API_KEY");
+  }
+  if (!isProviderAllowed(config.ai.provider, license)) {
+    throw new Error(upgradeMessage(`AI provider "${config.ai.provider}"`));
+  }
   let collector;
   if (config.source.type === "jira") {
     if (!config.jira) throw new Error("Jira source requires jira config in .cullit.yml");
-    console.log(`\xBB Collecting issues from Jira...`);
+    log.info(`\xBB Collecting issues from Jira...`);
     collector = new JiraCollector(config.jira);
   } else if (config.source.type === "linear") {
-    console.log(`\xBB Collecting issues from Linear...`);
+    log.info(`\xBB Collecting issues from Linear...`);
     collector = new LinearCollector(config.linear?.apiKey);
   } else {
-    console.log(`\xBB Collecting commits between ${from}..${to}`);
+    log.info(`\xBB Collecting commits between ${from}..${to}`);
     collector = new GitCollector();
   }
   const diff = await collector.collect(from, to);
   const itemLabel = config.source.type === "jira" || config.source.type === "linear" ? "issues" : "commits";
-  console.log(`\xBB Found ${diff.commits.length} ${itemLabel}${diff.filesChanged ? `, ${diff.filesChanged} files changed` : ""}`);
+  log.info(`\xBB Found ${diff.commits.length} ${itemLabel}${diff.filesChanged ? `, ${diff.filesChanged} files changed` : ""}`);
   if (diff.commits.length === 0) {
     const source = config.source.type === "jira" ? "Jira" : config.source.type === "linear" ? "Linear" : `${from} and ${to}`;
     throw new Error(`No ${itemLabel} found from ${source}`);
@@ -1146,18 +1457,26 @@ async function runPipeline(from, to, config, options = {}) {
   const enrichmentSources = config.source.enrichment || [];
   for (const source of enrichmentSources) {
     if (source === "jira" && config.jira) {
-      console.log("\xBB Enriching from Jira...");
+      if (!isEnrichmentAllowed(license)) {
+        log.info(`\xBB Skipping Jira enrichment \u2014 ${upgradeMessage("Jira enrichment")}`);
+        continue;
+      }
+      log.info("\xBB Enriching from Jira...");
       const enricher = new JiraEnricher(config.jira);
       const jiraTickets = await enricher.enrich(diff);
       tickets.push(...jiraTickets);
-      console.log(`\xBB Jira: found ${jiraTickets.length} tickets`);
+      log.info(`\xBB Jira: found ${jiraTickets.length} tickets`);
     }
     if (source === "linear") {
-      console.log("\xBB Enriching from Linear...");
+      if (!isEnrichmentAllowed(license)) {
+        log.info(`\xBB Skipping Linear enrichment \u2014 ${upgradeMessage("Linear enrichment")}`);
+        continue;
+      }
+      log.info("\xBB Enriching from Linear...");
       const enricher = new LinearEnricher(config.linear?.apiKey);
       const linearTickets = await enricher.enrich(diff);
       tickets.push(...linearTickets);
-      console.log(`\xBB Linear: found ${linearTickets.length} issues`);
+      log.info(`\xBB Linear: found ${linearTickets.length} issues`);
     }
   }
   const context = { diff, tickets };
@@ -1171,7 +1490,7 @@ async function runPipeline(from, to, config, options = {}) {
   };
   const providerName = providerNames[config.ai.provider] || config.ai.provider;
   const modelName = config.ai.provider === "none" ? "template" : config.ai.model || DEFAULT_MODELS[config.ai.provider] || "default";
-  console.log(`\xBB Generating with ${providerName} (${modelName})...`);
+  log.info(`\xBB Generating with ${providerName} (${modelName})...`);
   let notes;
   if (config.ai.provider === "none") {
     const generator = new TemplateGenerator();
@@ -1180,12 +1499,16 @@ async function runPipeline(from, to, config, options = {}) {
     const generator = new AIGenerator(config.openclaw);
     notes = await generator.generate(context, config.ai);
   }
-  console.log(`\xBB Generated ${notes.changes.length} change entries`);
+  log.info(`\xBB Generated ${notes.changes.length} change entries`);
   const formatted = formatNotes(notes, format);
   const publishedTo = [];
   if (!options.dryRun) {
     for (const target of config.publish) {
       try {
+        if (!isPublisherAllowed(target.type, license)) {
+          log.info(`\xBB Skipping ${target.type} \u2014 ${upgradeMessage(`${target.type} publishing`)}`);
+          continue;
+        }
         switch (target.type) {
           case "stdout":
             await new StdoutPublisher().publish(notes, format);
@@ -1215,16 +1538,16 @@ async function runPipeline(from, to, config, options = {}) {
             break;
         }
       } catch (err) {
-        console.error(`\u2717 Failed to publish to ${target.type}: ${err.message}`);
+        log.error(`\u2717 Failed to publish to ${target.type}: ${err.message}`);
       }
     }
   } else {
-    console.log("\n[DRY RUN \u2014 Not publishing]\n");
-    console.log(formatted);
+    log.info("\n[DRY RUN \u2014 Not publishing]\n");
+    log.info(formatted);
     publishedTo.push("dry-run");
   }
   const duration = Date.now() - startTime;
-  console.log(`
+  log.info(`
 \u2713 Done in ${(duration / 1e3).toFixed(1)}s`);
   return { notes, formatted, publishedTo, duration };
 }
@@ -1244,8 +1567,15 @@ export {
   StdoutPublisher,
   TemplateGenerator,
   VERSION,
+  analyzeReleaseReadiness,
+  createLogger,
   formatNotes,
   getLatestTag,
   getRecentTags,
-  runPipeline
+  isEnrichmentAllowed,
+  isProviderAllowed,
+  isPublisherAllowed,
+  resolveLicense,
+  runPipeline,
+  upgradeMessage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cullit/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Core engine for Cullit — AI-powered release note generation.",
   "license": "MIT",
@@ -27,8 +27,11 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
-    "@cullit/config": "0.1.0"
+    "@cullit/config": "0.3.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",