@releasekit/notes 0.3.1 → 0.4.0

package/dist/cli.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import {
   NotesError,
-  getDefaultConfig,
   getExitCode,
   loadConfig,
   parseVersionOutput,
   runPipeline,
   saveAuth
-} from "./chunk-ENAWZXFG.js";
+} from "./chunk-QX23CBNW.js";
 import {
   EXIT_CODES,
   error,
@@ -15,8 +14,9 @@ import {
   readPackageVersion,
   setLogLevel,
   setQuietMode,
-  success
-} from "./chunk-E4454SIS.js";
+  success,
+  warn
+} from "./chunk-7TJSPQPW.js";
 
 // src/cli.ts
 import * as fs from "fs";
@@ -27,50 +27,98 @@ function createNotesCommand() {
   const cmd = new Command("notes").description(
     "Generate changelogs with LLM-powered enhancement and flexible templating"
   );
-  cmd.command("generate", { isDefault: true }).description("Generate changelog from input data").option("-i, --input <file>", "Input file (default: stdin)").option("-o, --output <spec>", "Output spec (format:file)", collectOutputs, []).option("-t, --template <path>", "Template file or directory").option("-e, --engine <engine>", "Template engine (handlebars|liquid|ejs)").option("--monorepo <mode>", "Monorepo mode (root|packages|both)").option("--llm-provider <provider>", "LLM provider").option("--llm-model <model>", "LLM model").option("--llm-base-url <url>", "LLM base URL (for openai-compatible provider)").option("--llm-tasks <tasks>", "Comma-separated LLM tasks").option("--no-llm", "Disable LLM processing").option("--target <package>", "Filter to a specific package name").option("--config <path>", "Config file path").option("--dry-run", "Preview without writing").option("--regenerate", "Regenerate entire changelog").option("-v, --verbose", "Increase verbosity", increaseVerbosity, 0).option("-q, --quiet", "Suppress non-error output").action(async (options) => {
+  cmd.command("generate", { isDefault: true }).description("Generate changelog from input data").option("-i, --input <file>", "Input file (default: stdin)").option("--no-changelog", "Disable changelog generation").option("--changelog-mode <mode>", "Changelog location mode (root|packages|both)").option("--changelog-file <name>", "Changelog file name override").option("--release-notes-mode <mode>", "Enable release notes and set location (root|packages|both)").option("--release-notes-file <name>", "Release notes file name override").option("--no-release-notes", "Disable release notes generation").option("-t, --template <path>", "Template file or directory").option("-e, --engine <engine>", "Template engine (handlebars|liquid|ejs)").option("--monorepo <mode>", "Monorepo mode (root|packages|both)").option("--llm-provider <provider>", "LLM provider").option("--llm-model <model>", "LLM model").option("--llm-base-url <url>", "LLM base URL (for openai-compatible provider)").option("--llm-tasks <tasks>", "Comma-separated LLM tasks").option("--no-llm", "Disable LLM processing").option("--target <package>", "Filter to a specific package name").option("--config <path>", "Config file path").option("--regenerate", "Regenerate entire changelog instead of prepending new entries").option("--dry-run", "Preview without writing").option("-v, --verbose", "Increase verbosity", increaseVerbosity, 0).option("-q, --quiet", "Suppress non-error output").action(async (options) => {
     setVerbosity(options.verbose);
     if (options.quiet) setQuietMode(true);
     try {
-      const config = loadConfig(process.cwd(), options.config);
-      if (options.output.length > 0) {
-        config.output = options.output;
+      const loadedConfig = loadConfig({ cwd: process.cwd(), configPath: options.config });
+      const config = loadedConfig?.notes ?? {};
+      if (loadedConfig?.monorepo && !config.monorepo) {
+        config.monorepo = loadedConfig.monorepo;
       }
-      if (config.output.length === 0) {
-        config.output = getDefaultConfig().output;
+      if (options.changelog === false) {
+        config.changelog = false;
+      } else if (options.changelogMode || options.changelogFile) {
+        const existing = config.changelog !== false ? config.changelog ?? {} : {};
+        const mode = options.changelogMode ?? existing.mode ?? "root";
+        config.changelog = {
+          ...existing,
+          mode,
+          ...options.changelogFile ? { file: options.changelogFile } : {}
+        };
       }
-      if (options.regenerate) {
-        config.updateStrategy = "regenerate";
+      if (options.releaseNotes === false) {
+        config.releaseNotes = false;
+      } else if (options.releaseNotesMode || options.releaseNotesFile) {
+        const existing = config.releaseNotes !== false ? config.releaseNotes ?? {} : {};
+        const mode = options.releaseNotesMode ?? existing.mode ?? "root";
+        config.releaseNotes = {
+          ...existing,
+          mode,
+          ...options.releaseNotesFile ? { file: options.releaseNotesFile } : {}
+        };
+      }
+      if (config.changelog === false && (options.template || options.engine)) {
+        const ignored = [options.template && "--template", options.engine && "--engine"].filter(Boolean).join(" and ");
+        warn(`${ignored} ignored: changelog is disabled via --no-changelog`);
       }
-      if (options.template) {
-        config.templates = { ...config.templates, path: options.template };
+      if (options.template && config.changelog !== false) {
+        const existing = config.changelog ?? {};
+        config.changelog = {
+          ...existing,
+          templates: { ...existing.templates, path: options.template }
+        };
       }
-      if (options.engine) {
-        config.templates = { ...config.templates, engine: options.engine };
+      if (options.engine && config.changelog !== false) {
+        const existing = config.changelog ?? {};
+        config.changelog = {
+          ...existing,
+          templates: { ...existing.templates, engine: options.engine }
+        };
+      }
+      if (options.regenerate) {
+        config.updateStrategy = "regenerate";
       }
       if (options.llm === false) {
-        info("LLM processing disabled via --no-llm flag");
-        delete config.llm;
+        if (config.releaseNotes && typeof config.releaseNotes !== "boolean" && config.releaseNotes.llm) {
+          info("LLM processing disabled via --no-llm flag");
+          config.releaseNotes = { ...config.releaseNotes, llm: void 0 };
+        }
       } else if (options.llmProvider || options.llmModel || options.llmBaseUrl || options.llmTasks) {
-        config.llm = config.llm ?? { provider: "openai-compatible", model: "" };
-        if (options.llmProvider) config.llm.provider = options.llmProvider;
-        if (options.llmModel) config.llm.model = options.llmModel;
-        if (options.llmBaseUrl) config.llm.baseURL = options.llmBaseUrl;
-        if (options.llmTasks) {
-          const taskNames = options.llmTasks.split(",").map((t) => t.trim());
-          config.llm.tasks = {
-            enhance: taskNames.includes("enhance"),
-            summarize: taskNames.includes("summarize"),
-            categorize: taskNames.includes("categorize"),
-            releaseNotes: taskNames.includes("release-notes") || taskNames.includes("releaseNotes")
+        if (config.releaseNotes === false) {
+          warn("--llm-* flags ignored: release notes are disabled via --no-release-notes");
+        } else {
+          const existingRn = typeof config.releaseNotes === "object" ? config.releaseNotes : {};
+          const existingLlm = existingRn.llm;
+          const llm = {
+            provider: existingLlm?.provider ?? "openai-compatible",
+            model: existingLlm?.model ?? "",
+            ...existingLlm ?? {}
           };
-        }
-        info(`LLM configured: ${config.llm.provider}${config.llm.model ? ` (${config.llm.model})` : ""}`);
-        if (config.llm.baseURL) {
-          info(`LLM base URL: ${config.llm.baseURL}`);
-        }
-        const taskList = Object.entries(config.llm.tasks || {}).filter(([, enabled]) => enabled).map(([name]) => name).join(", ");
-        if (taskList) {
-          info(`LLM tasks: ${taskList}`);
+          if (options.llmProvider) llm.provider = options.llmProvider;
+          if (options.llmModel) llm.model = options.llmModel;
+          if (options.llmBaseUrl) llm.baseURL = options.llmBaseUrl;
+          if (options.llmTasks) {
+            const taskNames = options.llmTasks.split(",").map((t) => t.trim());
+            llm.tasks = {
+              enhance: taskNames.includes("enhance"),
+              summarize: taskNames.includes("summarize"),
+              categorize: taskNames.includes("categorize"),
+              releaseNotes: taskNames.includes("release-notes") || taskNames.includes("releaseNotes")
+            };
+          }
+          config.releaseNotes = {
+            ...existingRn,
+            llm
+          };
+          info(`LLM configured: ${llm.provider}${llm.model ? ` (${llm.model})` : ""}`);
+          if (llm.baseURL) {
+            info(`LLM base URL: ${llm.baseURL}`);
+          }
+          const taskList = Object.entries(llm.tasks || {}).filter(([, enabled]) => enabled).map(([name]) => name).join(", ");
+          if (taskList) {
+            info(`LLM tasks: ${taskList}`);
+          }
         }
       }
       let inputJson;
@@ -90,7 +138,14 @@ function createNotesCommand() {
         info(`Filtered to package: ${options.target}`);
       }
       if (options.monorepo) {
-        config.monorepo = { ...config.monorepo, mode: options.monorepo };
+        const monoMode = options.monorepo;
+        config.monorepo = { ...config.monorepo, mode: monoMode };
+        if (config.changelog !== false && !options.changelogMode) {
+          config.changelog = { ...config.changelog ?? {}, mode: monoMode };
+        }
+        if (config.releaseNotes !== false && config.releaseNotes !== void 0 && !options.releaseNotesMode) {
+          config.releaseNotes = { ...config.releaseNotes, mode: monoMode };
+        }
       }
       await runPipeline(input, config, options.dryRun ?? false);
       if (options.dryRun) {
@@ -102,22 +157,6 @@ function createNotesCommand() {
       handleError(err);
     }
   });
-  cmd.command("init").description("Create default configuration file").option("-f, --force", "Overwrite existing config").action((options) => {
-    const configPath = "releasekit.config.json";
-    if (fs.existsSync(configPath) && !options.force) {
-      error(`Config file already exists at ${configPath}. Use --force to overwrite.`);
-      process.exit(EXIT_CODES.GENERAL_ERROR);
-    }
-    const defaultConfig = {
-      $schema: "https://releasekit.dev/schema.json",
-      notes: {
-        output: [{ format: "markdown", file: "CHANGELOG.md" }],
-        updateStrategy: "prepend"
-      }
-    };
-    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2), "utf-8");
-    success(`Created config file at ${configPath}`);
-  });
   cmd.command("auth <provider>").description("Configure API key for an LLM provider").option("--key <key>", "API key (omit to be prompted)").action(async (provider, options) => {
     let apiKey;
     if (options.key) {
@@ -141,16 +180,6 @@ function createNotesCommand() {
   });
   return cmd;
 }
-function collectOutputs(value, previous) {
-  const parts = value.split(":");
-  const format = parts[0] ?? "markdown";
-  const file = parts[1];
-  const spec = { format };
-  if (file) {
-    spec.file = file;
-  }
-  return [...previous, spec];
-}
 function increaseVerbosity(_, previous) {
   return previous + 1;
 }

package/dist/index.js

@@ -9,26 +9,63 @@ import {
   getDefaultConfig,
   getExitCode,
   loadAuth,
-  loadConfig,
+  loadConfig2 as loadConfig,
   parseVersionOutput,
   parseVersionOutputFile,
   parseVersionOutputStdin,
   processInput,
-  renderJson,
   runPipeline,
-  saveAuth,
-  writeJson
-} from "./chunk-ENAWZXFG.js";
+  saveAuth
+} from "./chunk-QX23CBNW.js";
 import {
   aggregateToRoot,
   detectMonorepo,
   writeMonorepoChangelogs
-} from "./chunk-DCQ32FVH.js";
+} from "./chunk-F7MUVHZ2.js";
 import {
+  debug,
   formatVersion,
+  info,
   renderMarkdown,
+  success,
   writeMarkdown
-} from "./chunk-E4454SIS.js";
+} from "./chunk-7TJSPQPW.js";
+
+// src/output/json.ts
+import * as fs from "fs";
+import * as path from "path";
+function renderJson(contexts) {
+  return JSON.stringify(
+    {
+      versions: contexts.map((ctx) => ({
+        packageName: ctx.packageName,
+        version: ctx.version,
+        previousVersion: ctx.previousVersion,
+        date: ctx.date,
+        entries: ctx.entries,
+        compareUrl: ctx.compareUrl
+      }))
+    },
+    null,
+    2
+  );
+}
+function writeJson(outputPath, contexts, dryRun) {
+  const content = renderJson(contexts);
+  if (dryRun) {
+    info(`Would write JSON output to ${outputPath}`);
+    debug("--- JSON Output Preview ---");
+    debug(content);
+    debug("--- End Preview ---");
+    return;
+  }
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(outputPath, content, "utf-8");
+  success(`JSON output written to ${outputPath}`);
+}
 export {
   ConfigError,
   GitHubError,

package/docs/configuration.md

@@ -0,0 +1,276 @@
+# Notes Configuration Reference
+
+All options live under the `notes` key in `releasekit.config.json`. Add `$schema` for editor autocompletion:
+
+```json
+{
+  "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
+  "notes": {}
+}
+```
+
+---
+
+## `notes.changelog`
+
+Controls whether and where changelog files are written.
+
+**Type:** `false | object`
+**Default:** generates `CHANGELOG.md` at the repo root
+
+Set to `false` to disable changelog generation entirely.
+
+```json
+{
+  "notes": {
+    "changelog": false
+  }
+}
+```
+
+When an object, the following properties are available:
+
+### `notes.changelog.mode`
+
+| Value | Behaviour |
+|-------|-----------|
+| `"root"` | Write a single changelog at the repo root (default) |
+| `"packages"` | Write one changelog per package inside each package directory |
+| `"both"` | Write both root and per-package changelogs |
+
+```json
+{
+  "notes": {
+    "changelog": { "mode": "packages" }
+  }
+}
+```
+
+### `notes.changelog.file`
+
+Override the changelog file name.
+
+**Type:** `string`
+**Default:** `"CHANGELOG.md"`
+
+```json
+{
+  "notes": {
+    "changelog": { "mode": "root", "file": "CHANGES.md" }
+  }
+}
+```
+
+### `notes.changelog.templates`
+
+Custom template for changelog rendering.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` | Path to a template file or directory |
+| `engine` | `"handlebars" \| "liquid" \| "ejs"` | Template engine |
+
+```json
+{
+  "notes": {
+    "changelog": {
+      "mode": "root",
+      "templates": {
+        "path": "./templates/changelog/",
+        "engine": "liquid"
+      }
+    }
+  }
+}
+```
+
+See the [templates guide](./templates.md) for authoring details.
+
+---
+
+## `notes.releaseNotes`
+
+Controls release notes generation. Release notes are a separate output from the changelog — typically prose-formatted and suitable for GitHub release bodies.
+
+**Type:** `false | object`
+**Default:** `undefined` (release notes not generated)
+
+Set to `false` to explicitly disable when it has been enabled via config inheritance.
+
+When an object with a `mode` or `file` property, release notes are written to a file. When only `llm` is present (no `mode`/`file`), the LLM runs but no file is written — the generated content is passed to the publish step for use as a GitHub release body.
+
+### `notes.releaseNotes.mode`
+
+| Value | Behaviour |
+|-------|-----------|
+| `"root"` | Write `RELEASE_NOTES.md` at the repo root |
+| `"packages"` | Write one release notes file per package |
+| `"both"` | Write both root and per-package files |
+
+### `notes.releaseNotes.file`
+
+Override the release notes file name.
+
+**Type:** `string`
+**Default:** `"RELEASE_NOTES.md"`
+
+### `notes.releaseNotes.templates`
+
+Same structure as `notes.changelog.templates`. See the [templates guide](./templates.md).
+
+### `notes.releaseNotes.llm`
+
+LLM configuration for release notes enhancement. Requires `provider` and `model`.
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "llm": {
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "tasks": { "enhance": true, "summarize": true }
+      }
+    }
+  }
+}
+```
+
+See the full LLM option reference below.
+
+---
+
+## `notes.updateStrategy`
+
+How existing changelog files are updated when new entries are generated.
+
+**Type:** `"prepend" | "regenerate"`
+**Default:** `"prepend"`
+
+| Value | Behaviour |
+|-------|-----------|
+| `"prepend"` | New entries are inserted at the top of the existing file |
+| `"regenerate"` | The entire file is rewritten from scratch using all available history |
+
+```json
+{
+  "notes": {
+    "updateStrategy": "regenerate"
+  }
+}
+```
+
+---
+
+## LLM options (`notes.releaseNotes.llm`)
+
+### Required
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `provider` | `string` | LLM provider key. See [LLM providers](./llm-providers.md). |
+| `model` | `string` | Model identifier (e.g. `"gpt-4o-mini"`, `"claude-sonnet-4-5"`) |
+
+### Connection
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `baseURL` | `string` | Custom API base URL (for `openai-compatible` providers) |
+| `apiKey` | `string` | API key inline. Prefer env var or `releasekit-notes auth` over this. |
+
+### Behaviour
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `concurrency` | `integer` | `3` | Maximum parallel LLM requests when enhancing entries |
+
+### Model options (`options`)
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `timeout` | `integer` (ms) | Request timeout |
+| `maxTokens` | `integer` | Maximum tokens to generate |
+| `temperature` | `number` | Sampling temperature (0–2) |
+
+```json
+{
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4o",
+    "options": { "temperature": 0.3, "maxTokens": 1000 }
+  }
+}
+```
+
+### Tasks (`tasks`)
+
+| Task | Type | Description |
+|------|------|-------------|
+| `enhance` | `boolean` | Rewrite each entry description to be clearer and more user-facing |
+| `summarize` | `boolean` | Generate a one-paragraph summary of the release |
+| `categorize` | `boolean` | Group entries into user-friendly categories (Features, Fixes, …) |
+| `releaseNotes` | `boolean` | Generate full prose release notes suitable for a GitHub release body |
+
+### Categories (`categories`)
+
+Provide hints to the `categorize` task for how to group entries.
+
+```json
+{
+  "llm": {
+    "tasks": { "categorize": true },
+    "categories": [
+      { "name": "Features", "description": "New user-facing functionality" },
+      { "name": "Bug Fixes", "description": "Corrections to existing behaviour" },
+      { "name": "Performance", "description": "Speed or resource improvements" }
+    ]
+  }
+}
+```
+
+Each category object:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Display name used in template rendering |
+| `description` | yes | Hint sent to the LLM to guide grouping |
+| `scopes` | no | Commit scopes that always map to this category |
+
+### Style (`style`)
+
+A brief style instruction appended to every LLM prompt.
+
+```json
+{
+  "llm": {
+    "style": "Use concise, non-technical language suitable for end users."
+  }
+}
+```
+
+### Retry (`retry`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxAttempts` | `integer` | `3` | Maximum retries on failure |
+| `initialDelay` | `integer` (ms) | `500` | Delay before first retry |
+| `maxDelay` | `integer` (ms) | `10000` | Maximum delay between retries |
+| `backoffFactor` | `number` | `2` | Exponential backoff multiplier |
+
+### Prompt overrides (`prompts`)
+
+Override the built-in prompt instructions or templates for any task. The key is the task name (`enhance`, `categorize`, `summarize`, `releaseNotes`).
+
+```json
+{
+  "llm": {
+    "prompts": {
+      "instructions": {
+        "enhance": "Rewrite the description from a developer's perspective, keeping it technical."
+      }
+    }
+  }
+}
+```
+
+See the [LLM providers guide](./llm-providers.md) for examples.