@chamoji/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chamoji contributors
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { run } from './run.js';
+process.exitCode = await run(process.argv.slice(2), {
+    cwd: process.cwd(),
+    stdout: text => process.stdout.write(text),
+    stderr: text => process.stderr.write(text),
+});
+//# sourceMappingURL=cli.js.map

package/dist/run.d.ts

@@ -0,0 +1,9 @@
+export type Io = {
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** `YYYY-MM-DD` used for `--release`; defaults to today. */
+    today?: string;
+};
+export declare const NO_RELEASE_NEEDED = 3;
+export declare function run(argv: string[], io: Io): Promise<number>;

package/dist/run.js

@@ -0,0 +1,112 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildChangelog, loadConfig, render, } from '@chamoji/core';
+import meow from 'meow';
+const HELP = `
+	Usage
+	  $ chamoji changelog [options]    Generate a changelog from git history
+	  $ chamoji next-version [options] Print the next semver version
+	                                   (exits 3 when no release is needed)
+
+	Options
+	  --format   markdown (default), md, json or html
+	  --output   Write to this file instead of stdout
+	  --from     Leave out this release tag and everything older
+	  --to       Ref to treat as the head of history (default: HEAD)
+	  --release  Name the unreleased section with this version
+	  --config   Config file (default: chamoji.config.json if present)
+
+	Examples
+	  $ chamoji changelog --output CHANGELOG.md
+	  $ version=$(chamoji next-version) && chamoji changelog --release "$version" -o CHANGELOG.md
+	  $ chamoji changelog --format html --output changelog.html
+`;
+export const NO_RELEASE_NEEDED = 3;
+const FORMATS = {
+    markdown: 'markdown',
+    md: 'markdown',
+    json: 'json',
+    html: 'html',
+};
+export async function run(argv, io) {
+    const cli = meow(HELP, {
+        importMeta: import.meta,
+        argv,
+        autoHelp: false,
+        autoVersion: false,
+        flags: {
+            format: { type: 'string', default: 'markdown' },
+            output: { type: 'string', shortFlag: 'o' },
+            from: { type: 'string' },
+            to: { type: 'string', default: 'HEAD' },
+            release: { type: 'string' },
+            config: { type: 'string' },
+            help: { type: 'boolean', shortFlag: 'h' },
+            version: { type: 'boolean', shortFlag: 'v' },
+        },
+    });
+    const { flags } = cli;
+    if (flags.help) {
+        io.stdout(`${cli.help}\n`);
+        return 0;
+    }
+    if (flags.version) {
+        io.stdout(`${cli.pkg.version ?? 'unknown'}\n`);
+        return 0;
+    }
+    const [command] = cli.input;
+    try {
+        switch (command) {
+            case 'changelog': {
+                const format = Object.hasOwn(FORMATS, flags.format)
+                    ? FORMATS[flags.format]
+                    : undefined;
+                if (!format) {
+                    throw new Error(`Unknown format "${flags.format}" (use markdown, json or html)`);
+                }
+                const changelog = await buildChangelog({
+                    cwd: io.cwd,
+                    config: await loadConfig(io.cwd, flags.config),
+                    to: flags.to,
+                    from: flags.from,
+                    release: flags.release,
+                    today: io.today,
+                });
+                const output = render(changelog, format);
+                if (flags.output) {
+                    await writeFile(path.resolve(io.cwd, flags.output), output);
+                    io.stderr(`Wrote ${flags.output}\n`);
+                }
+                else {
+                    io.stdout(output);
+                }
+                return 0;
+            }
+            case 'next-version': {
+                const { releases } = await buildChangelog({
+                    cwd: io.cwd,
+                    config: await loadConfig(io.cwd, flags.config),
+                    to: flags.to,
+                });
+                const next = releases.find(release => release.tag === null)?.nextVersion;
+                if (!next) {
+                    // Non-zero and silent on stdout, so `$(chamoji next-version)` in a
+                    // release script stops instead of producing a release called "none".
+                    io.stderr('chamoji: no release needed (no commits since the last tag imply a version bump)\n');
+                    return NO_RELEASE_NEEDED;
+                }
+                io.stdout(`${next}\n`);
+                return 0;
+            }
+            default: {
+                io.stderr(`${command ? `chamoji: unknown command "${command}"\n` : ''}${cli.help}\n`);
+                return 2;
+            }
+        }
+    }
+    catch (error) {
+        io.stderr(`chamoji: ${error.message}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=run.js.map

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@chamoji/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Changelogs from gitmoji and Conventional Commits",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "chamoji": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "dependencies": {
+    "meow": "^14.1.0",
+    "@chamoji/core": "0.1.0"
+  },
+  "keywords": [
+    "changelog",
+    "gitmoji",
+    "conventional-commits",
+    "semver",
+    "release",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p ."
+  }
 }

package/readme.md

@@ -0,0 +1,94 @@
+# chamoji
+
+Changelogs from your git history. Chamoji reads [gitmoji](https://gitmoji.dev) and [Conventional Commits](https://www.conventionalcommits.org) messages, groups them into Keep a Changelog sections, and suggests the next semver version.
+
+## Install
+
+```bash
+npm install --global @chamoji/cli
+```
+
+Or run it without installing: `npx @chamoji/cli changelog`.
+
+Requires Node.js 22 or newer and git.
+
+## Usage
+
+```bash
+chamoji changelog                          # Markdown to stdout
+chamoji changelog --output CHANGELOG.md    # write a file
+chamoji changelog --format html --output changelog.html
+chamoji changelog --format json            # machine-readable
+chamoji next-version                       # e.g. 1.3.0
+```
+
+`next-version` exits with code 3 and prints nothing to stdout when no commit since the last tag implies a version bump (only docs, tests or refactors, say).
+
+| Option                | Meaning                                                                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format`            | `markdown` (default), `md`, `json` or `html`                                                                                                            |
+| `--output`, `-o`      | Write to a file instead of stdout                                                                                                                       |
+| `--from <tag>`        | Leave out this release and everything older                                                                                                             |
+| `--to <ref>`          | Ref to treat as the head of history (default `HEAD`)                                                                                                    |
+| `--release <version>` | Name and date the unreleased section, e.g. when cutting a release. Its compare link targets the tag it will get (`v<version>` when your tags use a `v`) |
+| `--config <file>`     | Config file (default `chamoji.config.json` when present)                                                                                                |
+
+Typical release flow:
+
+```bash
+set -e
+version=$(chamoji next-version)   # stops here when nothing needs releasing
+chamoji changelog --release "$version" --output CHANGELOG.md
+git commit -am "🔖 Release v$version"
+git tag "v$version"
+```
+
+## How commits are read
+
+- **Releases** are semver tags reachable from `--to` (`v1.2.0` or `1.2.0`, prereleases included), ordered by semver. Commits after the newest tag form the Unreleased section.
+- **Merge commits** are skipped.
+- **`git revert` commits** (`Revert "✨ Add login"`) are listed as ⏪ reverts, not by the emoji of the commit they undo.
+- **The gitmoji** can be a character (`✨`, with or without the invisible U+FE0F variation selector) or a shortcode (`:sparkles:`). Chamoji uses the earliest one in the subject. The list comes from the official [`gitmojis`](https://www.npmjs.com/package/gitmojis) package.
+- **These subject forms all work:**
+  - `✨ Add login`
+  - `✨ (auth): Add login`
+  - `feat(auth): ✨ Add login`
+  - `feat: Add login`. A Conventional type without an emoji maps to one: `feat`→✨, `fix`→🐛, `docs`→📝, and so on.
+- **Breaking changes** are 💥, a `!` after any type (`feat!:`, `deps!:`), or a `BREAKING CHANGE:` footer. They are listed under Breaking changes and give a major bump.
+- **The next version** comes from each gitmoji's `semver` field (✨ minor, 🐛 patch, …).
+- **Commit trailers** (`Key: value` lines at the end of a message) are parsed and included in the JSON output.
+
+## Config
+
+`chamoji.config.json`:
+
+```json
+{
+	"repositoryUrl": "https://github.com/acme/widgets",
+	"groups": [
+		{"group": "added", "label": "Added", "emojis": ["sparkles", "tada"]},
+		{"group": "fixed", "label": "Fixed", "emojis": ["bug", "ambulance"]},
+		{
+			"group": "useless",
+			"label": "Useless",
+			"emojis": ["bookmark"],
+			"hidden": true
+		},
+		{"group": "misc", "label": "Miscellaneous", "emojis": []}
+	]
+}
+```
+
+- `repositoryUrl` defaults to the `origin` remote. It is used for commit, issue (`#12`) and compare links.
+- `groups` replaces the default sections. Emojis are gitmoji codes without colons. Commits that match no group go to `misc` when that group exists. Hidden groups are left out of the output.
+- A plain JSON array of groups, the older format, is also accepted.
+
+## Development
+
+```bash
+pnpm install
+pnpm test     # vitest
+pnpm check    # build (type-check) + prettier
+```
+
+`packages/core` is the engine: git reading, parsing, grouping and rendering, with no UI. `packages/cli` is the `chamoji` command. See `docs/research/` for where the project is heading.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.