cngpac 0.0.1

package/dist/src/publishers/npm.mjs

@@ -0,0 +1,42 @@
+import { dirname } from "node:path";
+import { execSync } from "node:child_process";
+import * as semver from "semver";
+//#region src/publishers/npm.ts
+/**
+* Creates an npm publisher plugin.
+* Publishes the package to the npm registry.
+* Supports GitHub Actions Provenance (SLSA attestation) for signed releases.
+*/
+function createNpmPublisher(options = {}) {
+	return async ({ pkgJsonPath, versionBump }) => {
+		execSync("npm pack", {
+			cwd: dirname(pkgJsonPath),
+			stdio: "inherit"
+		});
+		const { registry, env = {}, args = [], provenance = true } = options;
+		const publishArgs = ["publish"];
+		if (registry) publishArgs.push("--registry", registry);
+		if (provenance) publishArgs.push("--provenance");
+		const ver = semver.parse(versionBump.newVersion);
+		if (ver?.prerelease?.length) {
+			const tag = String(ver.prerelease[0]);
+			publishArgs.push("--tag", tag);
+		}
+		publishArgs.push(...args);
+		const command = `npm ${publishArgs.join(" ")}`;
+		try {
+			execSync(command, {
+				cwd: dirname(pkgJsonPath),
+				stdio: "inherit",
+				env: {
+					...process.env,
+					...env
+				}
+			});
+		} catch (error) {
+			throw new Error(`Failed to publish ${versionBump.packageName}@${versionBump.newVersion} to npm: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+}
+//#endregion
+export { createNpmPublisher };

package/dist/src/releasers/github.d.mts

@@ -0,0 +1,10 @@
+import { ReleaserPlugin } from "../types.mjs";
+
+//#region src/releasers/github.d.ts
+interface GitHubReleaserOptions {
+  /** GitHub token for authentication */
+  token: string;
+}
+declare function createGitHubReleaser(options: GitHubReleaserOptions): ReleaserPlugin;
+//#endregion
+export { GitHubReleaserOptions, createGitHubReleaser };

package/dist/src/releasers/github.mjs

@@ -0,0 +1,20 @@
+import { Octokit } from "../node_modules/.pnpm/@octokit_rest@22.0.1/node_modules/@octokit/rest/dist-src/index.mjs";
+import * as semver from "semver";
+//#region src/releasers/github.ts
+function createGitHubReleaser(options) {
+	const octokit = new Octokit({ auth: options.token });
+	return async ({ versionBump, tagName, changelog, config }) => {
+		const releaseName = `${versionBump.packageName}@${versionBump.newVersion}`;
+		await octokit.repos.createRelease({
+			owner: config.repository.owner,
+			repo: config.repository.name,
+			tag_name: tagName,
+			name: releaseName,
+			body: changelog,
+			draft: false,
+			prerelease: semver.parse(versionBump.newVersion)?.prerelease?.length !== 0
+		});
+	};
+}
+//#endregion
+export { createGitHubReleaser };

package/dist/src/saver.d.mts

@@ -0,0 +1,42 @@
+import { ChangelogSaver, VersionBump } from "./types.mjs";
+
+//#region src/saver.d.ts
+interface ChangelogSaverOptions {
+  /**
+   * Filepath for saving the changelog.
+   * Can be a string (static path) or a function that receives the VersionBump
+   * and returns the filepath. Supports template variables:
+   * - {packageName}: The package name
+   * - {version}: The new version
+   *
+   * Examples:
+   * - "./CHANGELOG.md"
+   * - "./CHANGELOG-{packageName}.md"
+   * - (bump) => `./changelogs/{bump.packageName}-${bump.newVersion}.md`
+   */
+  filepath: string | ((bump: VersionBump) => string);
+}
+/**
+ * Creates a changelog saver that writes to the filesystem.
+ *
+ * @param options Configuration for the file saver
+ * @returns A ChangelogSaver plugin function
+ *
+ * @example
+ * ```ts
+ * const saver = createChangelogSaver({ filepath: "./CHANGELOG.md" });
+ *
+ * // Or with dynamic filepath:
+ * const saver = createChangelogSaver({
+ *   filepath: (bump) => `./changelogs/CHANGELOG-${bump.packageName}.md`
+ * });
+ *
+ * // Or with template variables:
+ * const saver = createChangelogSaver({
+ *   filepath: "./changelogs/CHANGELOG-{packageName}-{version}.md"
+ * });
+ * ```
+ */
+declare function createChangelogSaver(options: ChangelogSaverOptions): ChangelogSaver;
+//#endregion
+export { ChangelogSaverOptions, createChangelogSaver };

package/dist/src/saver.mjs

@@ -0,0 +1,39 @@
+import { escapePackageName } from "./utils.mjs";
+import { dirname, join } from "node:path";
+import { promises } from "node:fs";
+//#region src/saver.ts
+/**
+* Creates a changelog saver that writes to the filesystem.
+*
+* @param options Configuration for the file saver
+* @returns A ChangelogSaver plugin function
+*
+* @example
+* ```ts
+* const saver = createChangelogSaver({ filepath: "./CHANGELOG.md" });
+*
+* // Or with dynamic filepath:
+* const saver = createChangelogSaver({
+*   filepath: (bump) => `./changelogs/CHANGELOG-${bump.packageName}.md`
+* });
+*
+* // Or with template variables:
+* const saver = createChangelogSaver({
+*   filepath: "./changelogs/CHANGELOG-{packageName}-{version}.md"
+* });
+* ```
+*/
+function createChangelogSaver(options) {
+	return async ({ changelog, versionBump, configDir }) => {
+		let filepath;
+		if (typeof options.filepath === "function") filepath = options.filepath(versionBump);
+		else filepath = options.filepath.replace("{packageName}", escapePackageName(versionBump.packageName)).replace("{version}", versionBump.newVersion);
+		const absolutePath = filepath.startsWith("/") ? filepath : join(configDir, filepath);
+		const dir = dirname(absolutePath);
+		await promises.mkdir(dir, { recursive: true });
+		await promises.writeFile(absolutePath, changelog, "utf-8");
+		return absolutePath;
+	};
+}
+//#endregion
+export { createChangelogSaver };

package/dist/src/types.d.mts

@@ -0,0 +1,150 @@
+//#region src/types.d.ts
+/** A package in the monorepo */
+type Package = {
+  /** Package name */name: string; /** Package version */
+  version: string;
+};
+/** Branded string type representing a package file path */
+type PkgFileAbsPath = string & {
+  readonly __brand: "PkgFileAbsPath";
+};
+/** Branded string type representing a dirty file path */
+type DirtyFileAbsPath = string & {
+  readonly __brand: "DirtyFileAbsPath";
+};
+/** Semantic version bump type */
+type BumpType = "major" | "minor" | "patch";
+/** Parsed changenote from a markdown file */
+type Changenote = {
+  /** Unique ID derived from the filename (without extension) */id: string; /** YAML frontmatter metadata */
+  meta: ChangenoteMetadata; /** Heading from the changenote markdown */
+  title: string; /** Markdown body content after the title heading */
+  body: string; /** Relative file path to the changenote markdown file */
+  filePath: string;
+};
+type ChangenoteMetadata = {
+  /** Semantic versioning bump information */bump: BumpType;
+};
+/** Commit metadata extracted from git history */
+interface ChangenoteCommit {
+  /** Commit hash that introduced the changenote file */
+  hash: string;
+  /** Commit subject for the changenote file */
+  subject: string;
+}
+/** A Contributor who added/edited the changenote file */
+interface CommitAuthor {
+  name: string;
+  email: string;
+}
+/** A resolved version bump for a single package */
+interface VersionBump {
+  packageName: string;
+  /** Current version from package.json */
+  currentVersion: string;
+  /** New version after applying the bump */
+  newVersion: string;
+  /** The highest bump type applied */
+  bump: BumpType;
+}
+/** Prepare configuration written by the `prepare` command */
+type PrepareConfig = {
+  newVersion: string;
+  attempt: number;
+};
+/**
+ * A changelog generator plugin function.
+ * Receives a VersionBump and returns formatted changelog content.
+ */
+type ChangelogGenerator = (bump: VersionBump, changenotes: (Changenote & {
+  commit: ChangenoteCommit;
+  authors: CommitAuthor[];
+})[], config: CngpacConfig) => Promise<string>;
+/**
+ * A changelog saver plugin function.
+ * Called before git commit during the version command.
+ * Receives the generated changelog markdown and version bump info,
+ * and is responsible for persisting the changelog in the codebase.
+ */
+type ChangelogSaver = (props: {
+  changelog: string;
+  versionBump: VersionBump;
+  configDir: string;
+}) => Promise<DirtyFileAbsPath | DirtyFileAbsPath[] | undefined> | DirtyFileAbsPath | DirtyFileAbsPath[] | undefined;
+/**
+ * A releaser plugin function.
+ * Called after the "Publisher" plugins during the version command.
+ * Responsible for publishing a release (e.g. creating a GitHub release).
+ */
+type ReleaserPlugin = (props: {
+  versionBump: VersionBump;
+  tagName: string;
+  changelog: string;
+  config: CngpacConfig;
+}) => Promise<void> | void;
+/**
+ * A publisher plugin function.
+ * Called after the git push during the version command.
+ * Responsible for publishing the package to a registry (e.g. npm publish).
+ */
+type PublisherPlugin = (props: {
+  pkgJsonPath: string;
+  versionBump: VersionBump;
+  config: CngpacConfig;
+}) => Promise<void> | void;
+/**
+ * A pre-stage plugin function.
+ * Called during the version command, before staging dirty files.
+ * Can perform side effects (e.g. copy docs to a versioned directory)
+ * and return additional file paths that need to be staged.
+ */
+type PreStagePlugin = (props: {
+  versionBump: VersionBump;
+  config: CngpacConfig;
+  configDir: string;
+}) => Promise<DirtyFileAbsPath | DirtyFileAbsPath[] | undefined> | DirtyFileAbsPath | DirtyFileAbsPath[] | undefined;
+/**
+ * A changenote name generator function.
+ * Returns a unique string used as the changenote filename.
+ */
+type NoteNameGenerator = () => string;
+/**
+ * A formatter plugin.
+ * Declares which file extensions it handles and a function that formats them in place.
+ * Called after CLI commands create or modify files.
+ */
+type FormatterPlugin = {
+  /** File extensions this formatter handles (without leading dot, e.g. ["json", "md"]) */extensions: string[]; /** Format the given files in place */
+  format: (filePaths: string[], rootDir: string) => Promise<void> | void;
+};
+/** Configuration for Cngpac */
+interface CngpacConfig {
+  /** Relative path to the package file */
+  package: string;
+  repository: {
+    owner: string;
+    name: string;
+  };
+  changelog: {
+    /**
+     * A plugin that generates the changelog from changenotes.
+     */
+    generator: ChangelogGenerator;
+    /**`
+     * A plugin that saves the generated changelog in the codebase.
+     */
+    saver?: ChangelogSaver;
+  };
+  /** List of publisher plugins called after git push during the version command */
+  publishers?: PublisherPlugin[];
+  /** List of releaser plugins called after publishers during the version command */
+  releasers?: ReleaserPlugin[];
+  /** Formatter plugins called on files created/changed by CLI commands */
+  formatters?: FormatterPlugin[];
+  /** Pre-stage plugins called before staging dirty files during the version command */
+  preStage?: PreStagePlugin[];
+  /** Optional custom generator for changenote filenames */
+  noteNameGenerator?: NoteNameGenerator;
+}
+//#endregion
+export { BumpType, ChangelogGenerator, ChangelogSaver, Changenote, ChangenoteCommit, ChangenoteMetadata, CngpacConfig, CommitAuthor, DirtyFileAbsPath, FormatterPlugin, NoteNameGenerator, Package, PkgFileAbsPath, PreStagePlugin, PrepareConfig, PublisherPlugin, ReleaserPlugin, VersionBump };

package/dist/src/utils.d.mts

@@ -0,0 +1,7 @@
+import { CngpacConfig } from "./types.mjs";
+
+//#region src/utils.d.ts
+/** Load the Cngpac config */
+declare function loadConfig(path: string): Promise<CngpacConfig>;
+//#endregion
+export { loadConfig };

package/dist/src/utils.mjs

@@ -0,0 +1,47 @@
+import { access } from "node:fs/promises";
+import { extname } from "node:path";
+//#region src/utils.ts
+const CONFIG_EXTENSIONS = [
+	".ts",
+	".mts",
+	".js",
+	".mjs"
+];
+/** Load the Cngpac config */
+async function loadConfig(path) {
+	const ext = extname(path);
+	const base = ext ? path.slice(0, -ext.length) : path;
+	let resolvedPath;
+	for (const candidate of CONFIG_EXTENSIONS) {
+		const full = `${base}${candidate}`;
+		try {
+			await access(full);
+			resolvedPath = full;
+			break;
+		} catch {}
+	}
+	if (!resolvedPath) throw new Error(`Config file not found: tried ${CONFIG_EXTENSIONS.map((e) => `${base}${e}`).join(", ")}`);
+	const config = (await import(resolvedPath)).default;
+	if (!config || typeof config !== "object") throw new Error();
+	return config;
+}
+/**
+* Escape a package name to a safe file system name.
+*
+* "@myapp/core" → "myapp-core"
+*
+* "my-app" → "my-app"
+*/
+function escapePackageName(name) {
+	return name.replace(/^@/, "").replace(/\//g, "-");
+}
+/** Detect indentation from JSON content */
+function detectIndentation(content) {
+	const match = content.match(/\n([ \t]+)["'{]/);
+	if (!match) return 2;
+	const indent = match[1];
+	if (indent.includes("	")) return "	";
+	return indent.length;
+}
+//#endregion
+export { detectIndentation, escapePackageName, loadConfig };

package/dist/src/version.d.mts

@@ -0,0 +1,9 @@
+import { Changenote, VersionBump } from "./types.mjs";
+
+//#region src/version.d.ts
+/** Apply version bump to package.json */
+declare function applyVersionBump(versionBump: VersionBump, pkgJsonPath: string): void;
+/** Remove consumed changenote files */
+declare function consumeChangenotes(changenotes: Changenote[]): void;
+//#endregion
+export { applyVersionBump, consumeChangenotes };

package/dist/src/version.mjs

@@ -0,0 +1,18 @@
+import { detectIndentation } from "./utils.mjs";
+import fs from "node:fs";
+//#region src/version.ts
+/** Apply version bump to package.json */
+function applyVersionBump(versionBump, pkgJsonPath) {
+	const { newVersion } = versionBump;
+	const packageJsonRaw = fs.readFileSync(pkgJsonPath, "utf-8");
+	const indent = detectIndentation(packageJsonRaw);
+	const pkgJson = JSON.parse(packageJsonRaw);
+	pkgJson.version = newVersion;
+	fs.writeFileSync(pkgJsonPath, `${JSON.stringify(pkgJson, null, indent)}\n`, "utf-8");
+}
+/** Remove consumed changenote files */
+function consumeChangenotes(changenotes) {
+	for (const cn of changenotes) fs.unlinkSync(cn.filePath);
+}
+//#endregion
+export { applyVersionBump, consumeChangenotes };

package/package.json

@@ -0,0 +1,156 @@
+{
+  "name": "cngpac",
+  "version": "0.0.1",
+  "description": "A highly configurable package release manager",
+  "license": "Apache-2.0",
+  "homepage": "https://cngpac.dev",
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cngpac/cngpac.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cngpac/cngpac/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/src/index.mjs",
+    "./publishers/npm": "./dist/src/publishers/npm.mjs",
+    "./releasers/github": "./dist/src/releasers/github.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "cngpac": "dist/bin.mjs"
+  },
+  "scripts": {
+    "format": "biome format --write && oxfmt **/*.{md,yml,css}",
+    "format:check": "biome format --check && oxfmt --check **/*.{md,yml,css}",
+    "lint": "biome lint --write",
+    "typecheck-src": "tsc --noEmit --project tsconfig.json",
+    "typecheck-cli": "tsc --noEmit --project src/cli/tsconfig.json",
+    "typecheck-web": "tsc --noEmit --project website/tsconfig.json",
+    "typecheck": "npm run typecheck-src && npm run typecheck-cli && npm run typecheck-web",
+    "build-src": "tsdown --config tsdown.config.ts --exports",
+    "build-cli": "tsdown --config src/cli/tsdown.config.ts",
+    "build": "npm run build-src && npm run build-cli",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "web": "cd website && npm run start"
+  },
+  "dependencies": {
+    "semver": "^7.7.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.11",
+    "@clack/prompts": "^1.2.0",
+    "@octokit/rest": "^22.0.1",
+    "@prettier/plugin-xml": "^3.4.2",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.12.2",
+    "@types/semver": "^7.7.1",
+    "commander": "^14.0.3",
+    "glob": "^13.0.6",
+    "localstorage-polyfill": "^1.0.1",
+    "open": "^11.0.0",
+    "oxfmt": "^0.44.0",
+    "prettier": "^3.8.1",
+    "rehype-stringify": "^10.0.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "remark-stringify": "^11.0.0",
+    "simple-git": "^3.35.2",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "unified": "^11.0.5",
+    "vitest": "^4.1.4",
+    "yaml": "^2.8.3"
+  },
+  "inlinedDependencies": {
+    "@clack/core": "1.2.0",
+    "@clack/prompts": "1.2.0",
+    "@kwsites/file-exists": "1.1.1",
+    "@kwsites/promise-deferred": "1.1.1",
+    "@octokit/auth-token": "6.0.0",
+    "@octokit/core": "7.0.6",
+    "@octokit/endpoint": "11.0.3",
+    "@octokit/graphql": "9.0.3",
+    "@octokit/plugin-paginate-rest": "14.0.0",
+    "@octokit/plugin-request-log": "6.0.0",
+    "@octokit/plugin-rest-endpoint-methods": "17.0.0",
+    "@octokit/request": "10.0.8",
+    "@octokit/request-error": "7.1.0",
+    "@octokit/rest": "22.0.1",
+    "@simple-git/args-pathspec": "1.0.2",
+    "@simple-git/argv-parser": "1.0.3",
+    "bail": "2.0.2",
+    "before-after-hook": "4.0.0",
+    "character-entities": "2.0.2",
+    "debug": "4.4.3",
+    "decode-named-character-reference": "1.3.0",
+    "devlop": "1.1.0",
+    "escape-string-regexp": "5.0.0",
+    "extend": "3.0.2",
+    "fast-content-type-parse": "3.0.0",
+    "fast-string-truncated-width": "1.2.1",
+    "fast-string-width": "1.1.0",
+    "fast-wrap-ansi": "0.1.6",
+    "fault": "2.0.1",
+    "format": "0.2.2",
+    "glob": "13.0.6",
+    "has-flag": "4.0.0",
+    "is-plain-obj": "4.1.0",
+    "json-with-bigint": "3.5.8",
+    "localstorage-polyfill": "1.0.1",
+    "longest-streak": "3.1.0",
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-frontmatter": "2.0.1",
+    "mdast-util-phrasing": "4.1.0",
+    "mdast-util-to-markdown": "2.1.2",
+    "mdast-util-to-string": "4.0.0",
+    "micromark": "4.0.2",
+    "micromark-core-commonmark": "2.0.3",
+    "micromark-extension-frontmatter": "2.0.0",
+    "micromark-factory-destination": "2.0.1",
+    "micromark-factory-label": "2.0.1",
+    "micromark-factory-space": "2.0.1",
+    "micromark-factory-title": "2.0.1",
+    "micromark-factory-whitespace": "2.0.1",
+    "micromark-util-character": "2.1.1",
+    "micromark-util-chunked": "2.0.1",
+    "micromark-util-classify-character": "2.0.1",
+    "micromark-util-combine-extensions": "2.0.1",
+    "micromark-util-decode-numeric-character-reference": "2.0.2",
+    "micromark-util-decode-string": "2.0.1",
+    "micromark-util-html-tag-name": "2.0.1",
+    "micromark-util-normalize-identifier": "2.0.1",
+    "micromark-util-resolve-all": "2.0.1",
+    "micromark-util-subtokenize": "2.1.0",
+    "ms": "2.1.3",
+    "remark-frontmatter": "5.0.0",
+    "remark-parse": "11.0.0",
+    "remark-stringify": "11.0.0",
+    "simple-git": "3.35.2",
+    "sisteransi": "1.0.5",
+    "supports-color": "7.2.0",
+    "trough": "2.2.0",
+    "unified": "11.0.5",
+    "unist-util-is": "6.0.1",
+    "unist-util-stringify-position": "4.0.0",
+    "unist-util-visit": "5.1.0",
+    "unist-util-visit-parents": "6.0.2",
+    "universal-user-agent": "7.0.3",
+    "vfile": "6.0.3",
+    "vfile-message": "4.0.3",
+    "yaml": "2.8.3",
+    "zwitch": "2.0.4"
+  }
+}

package/templates/cngpac.config.ts

@@ -0,0 +1,33 @@
+import {
+	createChangelogGenerator,
+	createFormatter,
+	createGitHubReleaser,
+	createNpmPublisher,
+	defineConfig,
+} from "cngpac";
+
+export default defineConfig({
+	package: "__PACKAGE__",
+	repository: {
+		owner: "__OWNER__",
+		name: "__REPO__",
+	},
+	changelog: {
+		generator: createChangelogGenerator({
+			githubToken: process.env.GITHUB_TOKEN!,
+		}),
+	},
+	publishers: [
+		createNpmPublisher({
+			provenance: true,
+		}),
+	],
+	releasers: [
+		createGitHubReleaser({
+			token: process.env.GITHUB_TOKEN!,
+		}),
+	],
+	// formatters: [
+	//   createFormatter({ extensions: ["json", "md"], command: "oxfmt" }),
+	// ],
+});

package/templates/version.yml

@@ -0,0 +1,30 @@
+name: Cngpac Version
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".changenotes/prepare.json"
+
+permissions:
+  id-token: write
+  contents: write
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - run: npm install -g corepack
+      - run: corepack enable
+      - name: Setup runtime
+        uses: __RUNTIME_ACTION__
+      - name: Install dependencies
+        run: __INSTALL__
+      - name: Build package
+        run: npm run build
+      - name: Version
+        run: npx cngpac version --commit --tag --push --publish --release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}