pm-changelog 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## Unreleased - 2026-05-23
+
+### Added
+
+- Regenerate release changelog from pm items (pmc-a6qg)
+- Harden npm package metadata and CI release gates (pmc-otpe)
+
+### Security
+
+- Audit git history for private data exposure (pmc-91po)
+
+### Other
+
+- Final release verification and npm publication audit (pmc-jk1a)
+- Release pm-changelog 0.1.0 as a production-ready pm package (pmc-ysps)
+- Document pm governance for the package lifecycle (pmc-xl68)
+- Align GitHub repository settings for public package release (pmc-w1sp)
+- Verify pm-changelog in a clean temporary project (pmc-800h)
+
+## 0.1.0 - 2026-05-17
+
+### Added
+
+- Initial `pm-changelog` CLI for generating `CHANGELOG.md` from pm item JSON or `pm list-all --json`.
+- Programmatic APIs for creating, merging, reading, and writing changelogs from Node.js scripts and CI runners.
+- Package metadata for `pm install github.com/unbraind/pm-changelog --project`, `pm install npm:pm-changelog --project`, and catalog discovery.
+- `--release-version` for the pm extension command so release headings do not collide with the global `pm --version` flag.
+- Custom pm executable support via `--pm-bin` and `readPmItems({ pmBin })`.
+- Programmatic runner wrapper support with `readPmItems({ pmArgs, cwd, env })`.
+- pm-cli extension command: `pm changelog generate`.
+- GitHub Actions support with JSON summaries, check mode, prepend mode, and `$GITHUB_OUTPUT` fields.
+- Optional `$GITHUB_STEP_SUMMARY` publishing via `--github-step-summary`.
+- GitHub Actions CI workflow for validating package builds and tests.
+- Release and milestone grouping for projects that store release metadata on pm items.
+- Tracked built runtime output so GitHub and local pm package installs work without a separate build step.
+
+### Security
+
+- Item URLs are omitted by default.
+- Opt-in item links strip credentials, query strings, and fragments before markdown output.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unbraind
+
+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/README.md

@@ -0,0 +1,318 @@
+# pm-changelog
+
+Generate `CHANGELOG.md` from pm-cli items for local releases, GitHub Actions, runners, and scripts.
+
+The package provides:
+
+- `pm-changelog`, a standalone CLI that reads `pm list-all --json` or JSON input
+- `createChangelog()`, `generateChangelog()`, `mergeChangelog()`, and `writeChangelog()` programmatic APIs
+- `pm changelog generate`, a pm-cli extension command
+
+## Install
+
+Install as a pm package from GitHub:
+
+```bash
+pm install github.com/unbraind/pm-changelog --project
+```
+
+Then run the extension command:
+
+```bash
+pm changelog generate --mode prepend --output CHANGELOG.md
+```
+
+Install the standalone CLI/API package from npm:
+
+```bash
+npm install --save-dev pm-changelog @unbrained/pm-cli
+```
+
+Use the local checkout for development:
+
+```bash
+npm install
+npm run build
+```
+
+Local checkout extension install:
+
+```bash
+pm install ./pm-changelog --project
+```
+
+The repository tracks `dist/` intentionally so GitHub and local pm package installs work without a build step. npm packaging still runs `npm run build` through `prepack`.
+
+Package metadata is declared in `package.json` under `pm`, and the runtime extension manifest is `manifest.json` at the package root.
+
+Supported package-manager sources:
+
+```bash
+pm install github.com/unbraind/pm-changelog --project
+pm install npm:pm-changelog --project
+pm install ./pm-changelog --project
+```
+
+## Package Layout
+
+```text
+pm-changelog/
+  manifest.json       # pm extension manifest loaded by the package manager
+  package.json        # npm metadata plus pm package catalog/install metadata
+  LICENSE             # MIT license for npm and public repository consumers
+  dist/               # built CLI, API, and extension runtime tracked for pm installs
+  src/                # TypeScript source
+  test/               # node:test coverage for generator, CLI, and runner behavior
+```
+
+## Release Verification
+
+Run the full local release gate before tagging or publishing:
+
+```bash
+npm run release:check
+```
+
+The release gate type-checks the TypeScript source, runs the full test suite, audits production dependencies, verifies the npm package contents with a dry run, and checks that `CHANGELOG.md` is current.
+
+## CLI
+
+Generate `CHANGELOG.md` from the current pm project:
+
+```bash
+pm-changelog
+```
+
+Generate release notes for a CI release:
+
+```bash
+pm-changelog --pm-root . --version "$GITHUB_REF_NAME" --since 2026-05-01
+```
+
+Create or update `CHANGELOG.md` while preserving older entries:
+
+```bash
+pm-changelog --mode prepend --version "$GITHUB_REF_NAME" --output CHANGELOG.md
+```
+
+After building, the package also exposes npm scripts for projects that install it locally:
+
+```bash
+npm run changelog -- --version "$GITHUB_REF_NAME"
+npm run changelog:check -- --version "$GITHUB_REF_NAME"
+```
+
+Emit runner-readable metadata:
+
+```bash
+pm-changelog --mode prepend --version "$GITHUB_REF_NAME" --json
+```
+
+Fail CI if the committed changelog is stale without rewriting it:
+
+```bash
+pm-changelog --mode prepend --version "$GITHUB_REF_NAME" --check
+```
+
+Expose summary values to later GitHub Actions steps:
+
+```bash
+pm-changelog --mode prepend --version "$GITHUB_REF_NAME" --json --github-output
+```
+
+Append the generated changelog markdown to the GitHub Actions job summary:
+
+```bash
+pm-changelog --mode prepend --version "$GITHUB_REF_NAME" --github-step-summary
+```
+
+Print markdown instead of writing a file:
+
+```bash
+pm-changelog --stdout --version 1.2.0
+```
+
+Read JSON from a previous step:
+
+```bash
+pm list-all --json | pm-changelog --stdin --stdout
+```
+
+Use a pinned or wrapped pm executable in a runner:
+
+```bash
+pm-changelog --pm-bin ./node_modules/.bin/pm --mode prepend --version "$GITHUB_REF_NAME"
+```
+
+Pass runner-specific arguments and a working directory to wrapped pm commands:
+
+```bash
+pm-changelog --pm-bin ./pm-wrapper --pm-arg --profile --pm-arg ci --pm-cwd "$GITHUB_WORKSPACE" --mode prepend
+```
+
+Generate one section per `release` metadata value from pm items:
+
+```bash
+pm-changelog --group-by release --mode prepend --output CHANGELOG.md
+```
+
+Useful options:
+
+| Option | Default | Description |
+|---|---:|---|
+| `--output <file>` | `CHANGELOG.md` | Output path |
+| `--stdout` | false | Print markdown instead of writing a file |
+| `--input <file>` | - | Read pm JSON from a file |
+| `--stdin` | false | Read pm JSON from stdin |
+| `--pm-root <dir>` | - | Run `pm --path <dir> list-all --json` |
+| `--pm-bin <file>` | `pm` | pm executable to run, useful for pinned local installs and runner wrappers |
+| `--pm-arg <arg>` | - | Extra argument passed before `list-all --json`; repeat for multiple args |
+| `--pm-cwd <dir>` | - | Working directory for running pm |
+| `--version <version>` | `Unreleased` | Version heading |
+| `--date <date>` | today | Release date |
+| `--since <date>` | - | Include items changed on or after date |
+| `--until <date>` | - | Include items changed on or before date |
+| `--status <list>` | `closed` | Comma-separated statuses |
+| `--group-by <mode>` | `version` | `version`, `release`, or `milestone` |
+| `--mode <mode>` | `replace` | `replace` or `prepend` existing changelog |
+| `--json` | false | Print JSON summary for automation |
+| `--check` | false | Do not write; exit 1 if the output file would change |
+| `--github-output` | false | Write `output`, `mode`, `action`, `changed`, `item_count`, and `bytes` to `$GITHUB_OUTPUT` |
+| `--github-step-summary` | false | Append generated markdown to `$GITHUB_STEP_SUMMARY` |
+| `--include-empty` | false | Emit an empty section when no items match |
+| `--include-links` | false | Include item `url` values in generated entries |
+
+## pm-cli command
+
+```bash
+pm changelog generate
+pm changelog generate --release-version 1.2.0 --output CHANGELOG.md
+pm changelog generate --stdout --group-by milestone
+pm changelog generate --stdout --group-by release
+pm changelog generate --mode prepend --release-version "$GITHUB_REF_NAME"
+pm changelog generate --check --mode prepend --release-version "$GITHUB_REF_NAME"
+```
+
+The pm extension command uses `--release-version` because `pm --version` is a global CLI flag. The standalone `pm-changelog` binary uses `--version`.
+
+## Programmatic API
+
+```ts
+import { readPmItems, writeChangelog } from "pm-changelog";
+
+const items = readPmItems({
+  pmRoot: process.cwd(),
+  pmBin: "./node_modules/.bin/pm",
+});
+const result = writeChangelog({
+  items,
+  output: "CHANGELOG.md",
+  mode: "prepend",
+  groupBy: "release",
+  since: process.env.CHANGELOG_SINCE,
+  includeLinks: false,
+});
+
+console.log({
+  action: result.action,
+  changed: result.changed,
+  items: result.itemCount,
+  output: result.output,
+});
+```
+
+Use `version` when a runner is generating one release section from the current job context. Use `groupBy: "release"` or `--group-by release` when pm items already carry release metadata and a runner should rebuild multiple sections in one pass.
+
+Item links are omitted by default so public CI jobs do not accidentally publish private tracker URLs. Pass `--include-links` or `includeLinks: true` when item URLs are safe to expose. When links are included, credentials, query strings, and fragments are stripped before markdown is emitted.
+
+You can also pass items directly:
+
+```ts
+import { generateChangelog } from "pm-changelog";
+
+const markdown = generateChangelog({
+  version: "1.2.0",
+  items: [
+    {
+      id: "pm-123",
+      title: "Fix CSV import status handling",
+      status: "closed",
+      type: "Bug",
+      tags: ["fix"],
+      updated_at: "2026-05-17T09:00:00Z",
+    },
+  ],
+});
+```
+
+Runner wrappers can provide extra pm arguments, a working directory, and environment:
+
+```ts
+import { readPmItems } from "pm-changelog";
+
+const items = readPmItems({
+  pmBin: process.env.PM_BIN ?? "pm",
+  pmArgs: ["--profile", "ci"],
+  cwd: process.env.GITHUB_WORKSPACE,
+  env: process.env,
+});
+```
+
+## Categorization
+
+Items are grouped into Keep a Changelog-style sections using `type`, `tags`, and title keywords:
+
+- `Added`: feature, feat, added, add, new
+- `Changed`: change, refactor, update, improve
+- `Fixed`: fix, bug, hotfix, regression
+- `Removed`: removed, delete
+- `Security`: security, CVE, vulnerability
+- `Deprecated`: deprecated, deprecation
+- `Other`: anything else
+
+## GitHub Actions Example
+
+```yaml
+name: Changelog
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+      - name: Generate changelog
+        id: changelog
+        run: node dist/cli.js --mode prepend --version "${GITHUB_REF_NAME}" --output CHANGELOG.md --json --github-output --github-step-summary
+      - name: Commit changelog
+        if: steps.changelog.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          git commit -m "docs: update changelog"
+          git push
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+TypeScript 5, ES2022 target, NodeNext module resolution.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { stdin } from "node:process";
+import { createChangelog, mergeChangelog, parsePmItemsJson, readPmItems, writeChangelog, } from "./generator.js";
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    const items = await loadItems(options);
+    const outputPath = resolve(options.output);
+    if (!options.stdout) {
+        const result = writeChangelog({
+            items,
+            output: outputPath,
+            title: options.title,
+            version: options.version,
+            date: options.date,
+            since: options.since,
+            until: options.until,
+            includeStatuses: options.statuses,
+            groupBy: options.groupBy,
+            includeEmpty: options.includeEmpty,
+            includeLinks: options.includeLinks,
+            mode: options.mode,
+            check: options.check,
+        });
+        const summary = buildSummary(options, result, outputPath);
+        if (options.githubOutput)
+            writeGitHubOutput(summary);
+        if (options.githubStepSummary)
+            writeGitHubStepSummary(result.markdown);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(summary) + "\n");
+        }
+        else if (options.check) {
+            console.error(result.changed ? `Changelog is out of date: ${outputPath}` : `Changelog is up to date: ${outputPath}`);
+        }
+        else {
+            console.error(`Wrote ${outputPath}`);
+        }
+        if (options.check && result.changed)
+            process.exit(1);
+        return;
+    }
+    const generated = createChangelog({
+        items,
+        title: options.title,
+        version: options.version,
+        date: options.date,
+        since: options.since,
+        until: options.until,
+        includeStatuses: options.statuses,
+        groupBy: options.groupBy,
+        includeEmpty: options.includeEmpty,
+        includeLinks: options.includeLinks,
+    });
+    const existing = options.mode === "prepend" && existsSync(outputPath)
+        ? readFileSync(outputPath, "utf-8")
+        : undefined;
+    const merged = options.mode === "prepend"
+        ? mergeChangelog(existing, generated.markdown, { title: options.title })
+        : { markdown: generated.markdown, action: "replaced", changed: true };
+    if (options.stdout) {
+        if (options.json) {
+            const summary = buildSummary(options, {
+                output: outputPath,
+                markdown: merged.markdown,
+                action: merged.action,
+                changed: merged.changed,
+                itemCount: generated.itemCount,
+                bytes: Buffer.byteLength(merged.markdown, "utf-8"),
+            });
+            if (options.githubOutput)
+                writeGitHubOutput(summary);
+            if (options.githubStepSummary)
+                writeGitHubStepSummary(merged.markdown);
+            process.stdout.write(JSON.stringify(summary) + "\n");
+            return;
+        }
+        if (options.githubStepSummary)
+            writeGitHubStepSummary(merged.markdown);
+        process.stdout.write(merged.markdown);
+        return;
+    }
+}
+function parseArgs(args) {
+    const options = {
+        output: "CHANGELOG.md",
+        stdout: false,
+        json: false,
+        stdin: false,
+        pmArgs: [],
+        groupBy: "version",
+        includeEmpty: false,
+        includeLinks: false,
+        mode: "replace",
+        check: false,
+        githubOutput: false,
+        githubStepSummary: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case "--help":
+            case "-h":
+                printHelp();
+                process.exit(0);
+            case "--output":
+            case "-o":
+                options.output = requireValue(args, ++i, arg);
+                break;
+            case "--stdout":
+                options.stdout = true;
+                break;
+            case "--json":
+                options.json = true;
+                break;
+            case "--check":
+                options.check = true;
+                break;
+            case "--github-output":
+            case "--set-output":
+                options.githubOutput = true;
+                break;
+            case "--github-step-summary":
+                options.githubStepSummary = true;
+                break;
+            case "--input":
+            case "-i":
+                options.input = requireValue(args, ++i, arg);
+                break;
+            case "--stdin":
+                options.stdin = true;
+                break;
+            case "--pm-root":
+                options.pmRoot = requireValue(args, ++i, arg);
+                break;
+            case "--pm-bin":
+                options.pmBin = requireValue(args, ++i, arg);
+                break;
+            case "--pm-arg":
+                options.pmArgs.push(requireAnyValue(args, ++i, arg));
+                break;
+            case "--pm-cwd":
+                options.pmCwd = requireValue(args, ++i, arg);
+                break;
+            case "--title":
+                options.title = requireValue(args, ++i, arg);
+                break;
+            case "--version":
+                options.version = requireValue(args, ++i, arg);
+                break;
+            case "--date":
+                options.date = requireValue(args, ++i, arg);
+                break;
+            case "--since":
+                options.since = requireValue(args, ++i, arg);
+                break;
+            case "--until":
+                options.until = requireValue(args, ++i, arg);
+                break;
+            case "--status":
+            case "--statuses":
+                options.statuses = requireValue(args, ++i, arg)
+                    .split(",")
+                    .map((status) => status.trim())
+                    .filter(Boolean);
+                break;
+            case "--group-by":
+                options.groupBy = parseGroupBy(requireValue(args, ++i, arg));
+                break;
+            case "--mode":
+                options.mode = parseMode(requireValue(args, ++i, arg));
+                break;
+            case "--include-empty":
+                options.includeEmpty = true;
+                break;
+            case "--include-links":
+                options.includeLinks = true;
+                break;
+            case "--no-links":
+                options.includeLinks = false;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+async function loadItems(options) {
+    if (options.stdin) {
+        return parsePmItemsJson(await readStdin());
+    }
+    if (options.input) {
+        return parsePmItemsJson(readFileSync(resolve(options.input), "utf-8"));
+    }
+    return readPmItems({
+        pmRoot: options.pmRoot,
+        pmBin: options.pmBin,
+        pmArgs: options.pmArgs,
+        cwd: options.pmCwd ? resolve(options.pmCwd) : undefined,
+    });
+}
+function readStdin() {
+    return new Promise((resolvePromise, reject) => {
+        let data = "";
+        stdin.setEncoding("utf-8");
+        stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        stdin.on("end", () => resolvePromise(data));
+        stdin.on("error", reject);
+    });
+}
+function parseGroupBy(value) {
+    if (value === "version" || value === "release" || value === "milestone")
+        return value;
+    throw new Error("--group-by must be 'version', 'release', or 'milestone'");
+}
+function parseMode(value) {
+    if (value === "replace" || value === "prepend")
+        return value;
+    throw new Error("--mode must be 'replace' or 'prepend'");
+}
+function buildSummary(options, result, output = result.output) {
+    return {
+        output,
+        mode: options.mode,
+        action: result.action,
+        changed: result.changed,
+        itemCount: result.itemCount,
+        bytes: result.bytes,
+        check: options.check,
+        markdown: options.stdout ? result.markdown : undefined,
+    };
+}
+function writeGitHubOutput(summary) {
+    const githubOutput = process.env.GITHUB_OUTPUT;
+    if (!githubOutput) {
+        throw new Error("--github-output requires the GITHUB_OUTPUT environment variable");
+    }
+    const lines = [
+        `output=${String(summary.output ?? "")}`,
+        `mode=${String(summary.mode ?? "")}`,
+        `action=${String(summary.action ?? "")}`,
+        `changed=${String(summary.changed ?? "")}`,
+        `item_count=${String(summary.itemCount ?? "")}`,
+        `bytes=${String(summary.bytes ?? "")}`,
+    ];
+    appendFileSync(githubOutput, `${lines.join("\n")}\n`, "utf-8");
+}
+function writeGitHubStepSummary(markdown) {
+    const githubStepSummary = process.env.GITHUB_STEP_SUMMARY;
+    if (!githubStepSummary) {
+        throw new Error("--github-step-summary requires the GITHUB_STEP_SUMMARY environment variable");
+    }
+    appendFileSync(githubStepSummary, `${markdown.trimEnd()}\n`, "utf-8");
+}
+function requireValue(args, index, flag) {
+    const value = args[index];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function requireAnyValue(args, index, flag) {
+    const value = args[index];
+    if (!value) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function printHelp() {
+    process.stdout.write(`pm-changelog
+
+Generate CHANGELOG.md from pm-cli items.
+
+Usage:
+  pm-changelog [options]
+
+Options:
+  -o, --output <file>       Write changelog to a file (default: CHANGELOG.md)
+      --stdout              Print markdown instead of writing a file
+      --json                Print a JSON summary for CI/runners
+      --check               Do not write; exit 1 when output would change
+      --github-output       Write summary fields to $GITHUB_OUTPUT
+      --github-step-summary Append generated markdown to $GITHUB_STEP_SUMMARY
+  -i, --input <file>        Read pm JSON from a file instead of running pm
+      --stdin               Read pm JSON from stdin
+      --pm-root <dir>       pm project root for "pm --path <dir> list-all --json"
+      --pm-bin <file>       pm executable to run (default: pm)
+      --pm-arg <arg>        Extra argument passed before "list-all --json" (repeatable)
+      --pm-cwd <dir>        Working directory for running pm
+      --title <text>        Changelog title (default: Changelog)
+      --version <version>   Version heading (default: Unreleased)
+      --date <date>         Release date (default: today)
+      --since <date>        Include items changed on or after this date
+      --until <date>        Include items changed on or before this date
+      --status <list>       Comma-separated statuses (default: closed)
+      --group-by <mode>     version, release, or milestone (default: version)
+      --mode <mode>         replace or prepend existing changelog (default: replace)
+      --include-empty       Emit an empty release section when no items match
+      --include-links       Include item URLs in generated entries (default: false)
+`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map