@cullit/core 1.17.0 → 1.18.1

package/LICENSE

@@ -1,21 +1,12 @@
-MIT License
+Copyright (c) 2026 Cullit (Matt). All rights reserved.
 
-Copyright (c) 2026 Cullit (Matt)
+This software and its source code are proprietary to Cullit.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+You may view and fork this repository for evaluation purposes. You may not
+use, copy, modify, merge, publish, distribute, sublicense, or sell copies
+of this software without explicit written permission from the copyright holder.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Commercial use requires a valid Cullit license. See https://cullit.io/pricing
+for available plans.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+For full terms of use, see TERMS.md.

package/dist/index.d.ts

@@ -71,7 +71,7 @@ interface PipelineResult {
     duration: number;
 }
 
-declare const VERSION = "1.17.0";
+declare const VERSION = "1.18.1";
 declare const DEFAULT_CATEGORIES: string[];
 declare const DEFAULT_MODELS: Record<string, string>;
 declare const AI_PROVIDERS: readonly ["anthropic", "openai", "gemini", "ollama", "none"];
@@ -312,6 +312,62 @@ declare function listPublishers(): string[];
  */
 declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs?: number): Promise<Response>;
 
+/**
+ * Rate Limiter — Sliding-window rate limiter with pluggable backends.
+ *
+ * Usage:
+ *   const limiter = createRateLimiter({ limit: 30, windowMs: 60_000 });
+ *   const result = limiter.check('user-ip-or-key');
+ *   if (!result.allowed) { // reject }
+ */
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    /** Unix timestamp (seconds) when the window resets */
+    resetAt: number;
+}
+interface RateLimiter {
+    check(key: string): RateLimitResult;
+    /** Remove all tracked entries */
+    reset(): void;
+}
+interface RateLimiterOptions {
+    /** Max requests per window (default: 30) */
+    limit?: number;
+    /** Window duration in ms (default: 60_000) */
+    windowMs?: number;
+    /** Max tracked keys before eviction (default: 10_000) */
+    maxBuckets?: number;
+}
+declare function createRateLimiter(opts?: RateLimiterOptions): RateLimiter;
+
+/**
+ * Structured error codes for the Cullit core pipeline.
+ * Used in CullitError instances so callers can branch on code rather than message parsing.
+ */
+declare const CoreErrorCode: {
+    readonly GIT_REF_INVALID: "GIT_REF_INVALID";
+    readonly GIT_LOG_FAILED: "GIT_LOG_FAILED";
+    readonly MULTI_REPO_EMPTY: "MULTI_REPO_EMPTY";
+    readonly MULTI_REPO_MISSING_TARGET: "MULTI_REPO_MISSING_TARGET";
+    readonly MULTI_REPO_INVALID_URL: "MULTI_REPO_INVALID_URL";
+    readonly PIPELINE_NO_CHANGES: "PIPELINE_NO_CHANGES";
+    readonly PIPELINE_COLLECTOR_MISSING: "PIPELINE_COLLECTOR_MISSING";
+    readonly PIPELINE_GENERATOR_MISSING: "PIPELINE_GENERATOR_MISSING";
+    readonly LICENSE_INVALID: "LICENSE_INVALID";
+    readonly LICENSE_TIER_INSUFFICIENT: "LICENSE_TIER_INSUFFICIENT";
+    readonly FETCH_TIMEOUT: "FETCH_TIMEOUT";
+    readonly PUBLISHER_PATH_TRAVERSAL: "PUBLISHER_PATH_TRAVERSAL";
+};
+type CoreErrorCodeValue = typeof CoreErrorCode[keyof typeof CoreErrorCode];
+/**
+ * Error class carrying a structured code alongside the human-readable message.
+ */
+declare class CullitError extends Error {
+    readonly code: CoreErrorCodeValue;
+    constructor(code: CoreErrorCodeValue, message: string);
+}
+
 /**
  * Main pipeline: Collect → Enrich → Generate → Format → Publish
  */
@@ -322,4 +378,4 @@ declare function runPipeline(from: string, to: string, config: CullConfig, optio
     templateProfile?: string;
 }): Promise<PipelineResult>;
 
-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, MultiRepoCollector, OUTPUT_FORMATS, PUBLISHER_TYPES, type PipelineResult, type Publisher, type PublisherFactory, type ReleaseAdvisory, type ReleaseNotes, SOURCE_TYPES, type SemverBump, StdoutPublisher, TONES, type TeamFeature, TemplateGenerator, type UsageLimits, VERSION, analyzeReleaseReadiness, createLogger, escapeHtml, fetchWithTimeout, formatNotes, getCollector, getEnricher, getFeatureGating, getFormatter, getGenerator, getLatestTag, getPublisher, getRecentTags, getTierLimits, hasCollector, hasEnricher, hasGenerator, hasPublisher, isEnrichmentAllowed, isFeatureAllowed, isProviderAllowed, isPublisherAllowed, listCollectors, listEnrichers, listFormatters, listGenerators, listPublishers, registerCollector, registerEnricher, registerFormatter, registerGenerator, registerPublisher, reportUsage, resolveLicense, runPipeline, upgradeMessage, validateLicense };
+export { AI_PROVIDERS, AUDIENCES, CHANGE_CATEGORIES, type ChangeCategory, type ChangeEntry, type Collector, type CollectorFactory, CoreErrorCode, type CoreErrorCodeValue, CullitError, 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, MultiRepoCollector, OUTPUT_FORMATS, PUBLISHER_TYPES, type PipelineResult, type Publisher, type PublisherFactory, type RateLimitResult, type RateLimiter, type RateLimiterOptions, type ReleaseAdvisory, type ReleaseNotes, SOURCE_TYPES, type SemverBump, StdoutPublisher, TONES, type TeamFeature, TemplateGenerator, type UsageLimits, VERSION, analyzeReleaseReadiness, createLogger, createRateLimiter, escapeHtml, fetchWithTimeout, formatNotes, getCollector, getEnricher, getFeatureGating, getFormatter, getGenerator, getLatestTag, getPublisher, getRecentTags, getTierLimits, hasCollector, hasEnricher, hasGenerator, hasPublisher, isEnrichmentAllowed, isFeatureAllowed, 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 = "1.17.0";
+var VERSION = "1.18.1";
 var DEFAULT_CATEGORIES = ["features", "fixes", "breaking", "improvements", "chores"];
 var DEFAULT_MODELS = {
   anthropic: "claude-sonnet-4-20250514",
@@ -36,12 +36,44 @@ function createLogger(level = "normal") {
 
 // src/collectors/git.ts
 import { execFileSync } from "child_process";
+
+// src/errors.ts
+var CoreErrorCode = {
+  // Git / Source
+  GIT_REF_INVALID: "GIT_REF_INVALID",
+  GIT_LOG_FAILED: "GIT_LOG_FAILED",
+  // Multi-repo
+  MULTI_REPO_EMPTY: "MULTI_REPO_EMPTY",
+  MULTI_REPO_MISSING_TARGET: "MULTI_REPO_MISSING_TARGET",
+  MULTI_REPO_INVALID_URL: "MULTI_REPO_INVALID_URL",
+  // Pipeline
+  PIPELINE_NO_CHANGES: "PIPELINE_NO_CHANGES",
+  PIPELINE_COLLECTOR_MISSING: "PIPELINE_COLLECTOR_MISSING",
+  PIPELINE_GENERATOR_MISSING: "PIPELINE_GENERATOR_MISSING",
+  // License
+  LICENSE_INVALID: "LICENSE_INVALID",
+  LICENSE_TIER_INSUFFICIENT: "LICENSE_TIER_INSUFFICIENT",
+  // Fetch
+  FETCH_TIMEOUT: "FETCH_TIMEOUT",
+  // Publisher
+  PUBLISHER_PATH_TRAVERSAL: "PUBLISHER_PATH_TRAVERSAL"
+};
+var CullitError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CullitError";
+    this.code = code;
+  }
+};
+
+// src/collectors/git.ts
 function validateRef(ref) {
   if (!ref || ref.length > 256) {
-    throw new Error(`Invalid git ref: too ${ref ? "long" : "short"}`);
+    throw new CullitError(CoreErrorCode.GIT_REF_INVALID, `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`);
+    throw new CullitError(CoreErrorCode.GIT_REF_INVALID, `Invalid git ref "${ref}" \u2014 only alphanumeric, dots, dashes, underscores, slashes, tildes, and carets are allowed`);
   }
 }
 var GitCollector = class {
@@ -74,7 +106,8 @@ var GitCollector = class {
       const errWithStderr = typeof error === "object" && error !== null && "stderr" in error ? error : void 0;
       const stderr = errWithStderr?.stderr?.toString?.() || "";
       const hint = stderr.includes("unknown revision") ? 'Check that both refs exist (run "cullit tags" to see tags).' : stderr.includes("not a git repository") ? "Run this command inside a git repository." : `Make sure both refs exist and you're in a git repository.`;
-      throw new Error(
+      throw new CullitError(
+        CoreErrorCode.GIT_LOG_FAILED,
         `Failed to read git log between ${from} and ${to}. ${hint}`
       );
     }
@@ -194,7 +227,7 @@ var MultiRepoCollector = class {
   repos;
   tempDirs = [];
   constructor(repos) {
-    if (!repos.length) throw new Error("Multi-repo collector requires at least one repo");
+    if (!repos.length) throw new CullitError(CoreErrorCode.MULTI_REPO_EMPTY, "Multi-repo collector requires at least one repo");
     this.repos = repos;
   }
   async collect(from, to) {
@@ -229,10 +262,10 @@ var MultiRepoCollector = class {
   async resolveRepoPath(repo) {
     if (repo.path) return repo.path;
     if (!repo.url) {
-      throw new Error('Each repo must have either "url" or "path"');
+      throw new CullitError(CoreErrorCode.MULTI_REPO_MISSING_TARGET, 'Each repo must have either "url" or "path"');
     }
     if (!/^(https?:\/\/|git@|ssh:\/\/)/.test(repo.url)) {
-      throw new Error(`Invalid repo URL: ${repo.url}`);
+      throw new CullitError(CoreErrorCode.MULTI_REPO_INVALID_URL, `Invalid repo URL: ${repo.url}`);
     }
     const tempDir = mkdtempSync(join(tmpdir(), "cullit-repo-"));
     this.tempDirs.push(tempDir);
@@ -560,7 +593,7 @@ var FilePublisher = class {
     const cwd = resolve(".");
     const rel = relative(cwd, resolved);
     if (rel.startsWith("..") || isAbsolute(rel)) {
-      throw new Error(`File output path must be within the project directory. Got: ${path}`);
+      throw new CullitError(CoreErrorCode.PUBLISHER_PATH_TRAVERSAL, `File output path must be within the project directory. Got: ${path}`);
     }
   }
   async publish(notes, format, preformatted) {
@@ -706,7 +739,7 @@ async function fetchWithTimeout(url, init, timeoutMs = DEFAULT_TIMEOUT) {
     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 new CullitError(CoreErrorCode.FETCH_TIMEOUT, `Request to ${new URL(url).hostname} timed out after ${timeoutMs / 1e3}s`);
     }
     throw err;
   } finally {
@@ -746,6 +779,14 @@ async function validateLicense() {
   if (!validationUrl) {
     return { tier: "pro", valid: true };
   }
+  try {
+    const parsed = new URL(validationUrl);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && parsed.hostname === "localhost")) {
+      return { tier: "pro", valid: true, message: "CULLIT_LICENSE_URL must use https." };
+    }
+  } catch {
+    return { tier: "pro", valid: true, message: "CULLIT_LICENSE_URL is not a valid URL." };
+  }
   try {
     const res = await fetchWithTimeout(validationUrl, {
       method: "POST",
@@ -902,6 +943,52 @@ function listPublishers() {
   return Array.from(publishers.keys());
 }
 
+// src/rate-limiter.ts
+var MemoryRateLimiter = class {
+  limit;
+  windowMs;
+  maxBuckets;
+  buckets = /* @__PURE__ */ new Map();
+  pruneTimer;
+  constructor(opts = {}) {
+    this.limit = opts.limit ?? 30;
+    this.windowMs = opts.windowMs ?? 6e4;
+    this.maxBuckets = opts.maxBuckets ?? 1e4;
+    this.pruneTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [key, times] of this.buckets) {
+        const active = times.filter((t) => now - t < this.windowMs);
+        if (active.length === 0) this.buckets.delete(key);
+        else this.buckets.set(key, active);
+      }
+    }, 12e4);
+    this.pruneTimer.unref();
+  }
+  check(key) {
+    const now = Date.now();
+    const timestamps = this.buckets.get(key) || [];
+    const recent = timestamps.filter((t) => now - t < this.windowMs);
+    const remaining = Math.max(0, this.limit - recent.length);
+    const resetAt = recent.length > 0 ? Math.ceil((recent[0] + this.windowMs) / 1e3) : Math.ceil((now + this.windowMs) / 1e3);
+    if (recent.length >= this.limit) {
+      return { allowed: false, remaining: 0, resetAt };
+    }
+    if (!this.buckets.has(key) && this.buckets.size >= this.maxBuckets) {
+      const oldest = this.buckets.keys().next().value;
+      if (oldest) this.buckets.delete(oldest);
+    }
+    recent.push(now);
+    this.buckets.set(key, recent);
+    return { allowed: true, remaining: remaining - 1, resetAt };
+  }
+  reset() {
+    this.buckets.clear();
+  }
+};
+function createRateLimiter(opts) {
+  return new MemoryRateLimiter(opts);
+}
+
 // src/index.ts
 registerCollector("local", (config) => new GitCollector(config.source?.repoPath));
 registerCollector("multi-repo", (config) => {
@@ -979,16 +1066,17 @@ async function runPipeline(from, to, config, options = {}) {
   const license = await validateLicense();
   if (!license.valid) {
     if (!isProviderAllowed(config.ai.provider, license)) {
-      throw new Error(license.message || "Invalid CULLIT_API_KEY");
+      throw new CullitError(CoreErrorCode.LICENSE_INVALID, license.message || "Invalid CULLIT_API_KEY");
     }
     log.warn(`\u26A0 ${license.message || "Invalid CULLIT_API_KEY \u2014 running in free mode."}`);
   }
   if (!isProviderAllowed(config.ai.provider, license)) {
-    throw new Error(upgradeMessage(`AI provider "${config.ai.provider}"`));
+    throw new CullitError(CoreErrorCode.LICENSE_TIER_INSUFFICIENT, upgradeMessage(`AI provider "${config.ai.provider}"`));
   }
   const collectorFactory = getCollector(config.source.type);
   if (!collectorFactory) {
-    throw new Error(
+    throw new CullitError(
+      CoreErrorCode.PIPELINE_COLLECTOR_MISSING,
       `Source type "${config.source.type}" is not available. ` + (config.source.type !== "local" ? "Install @cullit/licensed (private distribution) to use this source." : "Valid sources: local")
     );
   }
@@ -1000,7 +1088,7 @@ async function runPipeline(from, to, config, options = {}) {
   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}`);
+    throw new CullitError(CoreErrorCode.PIPELINE_NO_CHANGES, `No ${itemLabel} found from ${source}`);
   }
   const tickets = [];
   const enrichmentSources = config.source.enrichment || [];
@@ -1033,7 +1121,8 @@ async function runPipeline(from, to, config, options = {}) {
   log.info(`\xBB Generating with ${providerName} (${modelName})...`);
   const generatorFactory = getGenerator(config.ai.provider);
   if (!generatorFactory) {
-    throw new Error(
+    throw new CullitError(
+      CoreErrorCode.PIPELINE_GENERATOR_MISSING,
       `AI provider "${config.ai.provider}" is not available. ` + (config.ai.provider !== "none" ? "Install @cullit/licensed (private distribution) to use AI providers." : "")
     );
   }
@@ -1112,6 +1201,8 @@ export {
   AI_PROVIDERS,
   AUDIENCES,
   CHANGE_CATEGORIES,
+  CoreErrorCode,
+  CullitError,
   DEFAULT_CATEGORIES,
   DEFAULT_MODELS,
   ENRICHMENT_TYPES,
@@ -1127,6 +1218,7 @@ export {
   VERSION,
   analyzeReleaseReadiness,
   createLogger,
+  createRateLimiter,
   escapeHtml,
   fetchWithTimeout,
   formatNotes,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@cullit/core",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "type": "module",
   "description": "Core engine for Cullit — AI-powered release note generation.",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "author": "Cullit <matt@cullit.io>",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cullit/config": "1.17.0"
+    "@cullit/config": "1.18.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",