@doryski/release 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominik Rycharski
+
+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,101 @@
+# @doryski/release
+
+A conventional-commit release CLI and a reusable GitHub Actions workflow, shared
+across npm packages. One source of truth for "bump, tag, push, publish".
+
+The CLI runs in a consuming repo's root, inspects git history since the latest
+tag, proposes a semver bump derived from conventional commits, bumps
+`package.json`, commits `release: vX.Y.Z`, and pushes the branch then the tag —
+which triggers the reusable workflow to build, test, and publish to npm.
+
+## Install
+
+```bash
+pnpm add -D @doryski/release
+```
+
+Add a `release` script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "release": "doryski-release"
+  }
+}
+```
+
+Then run:
+
+```bash
+pnpm release
+```
+
+## CLI flags
+
+| Flag | Description |
+| --- | --- |
+| `-r, --release-version <ver>` | Exact release version (`0.2.0` or `v0.2.0`). Highest precedence. |
+| `--bump <major\|minor\|patch>` | Force the bump level. Overrides the auto-detected level; ignored when `--release-version` is set. |
+| `-y, --yes` | Skip the confirmation prompt (required for non-interactive runs). |
+| `-n, --dry-run` | Preview actions without modifying files, committing, tagging, or pushing. |
+| `-h, --help` | Show help. |
+
+Version precedence: `--release-version` > `--bump` > auto-detected from commits.
+
+The auto-detected bump follows conventional commits since the latest tag:
+
+- a `!`-marked type (e.g. `feat!:`) or a `BREAKING CHANGE:` footer → **major**
+- any `feat:` → **minor**
+- everything else (`fix`, `chore`, `docs`, …) → **patch**
+
+## Programmatic use
+
+```ts
+import { release } from "@doryski/release";
+
+await release({ bump: "minor", yes: true });
+```
+
+## Reusable release workflow
+
+This package ships a reusable workflow at
+`Doryski/release/.github/workflows/release.yml`. Consumers add a caller workflow
+that triggers on `v*` tags:
+
+```yaml
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    uses: Doryski/release/.github/workflows/release.yml@v1
+    permissions:
+      contents: write
+      id-token: write
+    with:
+      run-lint: true
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Workflow inputs:
+
+| Input | Type | Default | Description |
+| --- | --- | --- | --- |
+| `node-version` | string | `"20"` | Node version for setup-node. |
+| `run-lint` | boolean | `true` | Whether to run `pnpm lint`. |
+
+The workflow runs `install → build → lint (gated) → type-check → test`, verifies
+`package.json` matches the tag, publishes with `npm publish --access public
+--provenance`, and creates a GitHub Release with generated notes.
+
+The consuming repo must expose `build`, `type-check`, `test`, and (if
+`run-lint`) `lint` scripts, and provide an `NPM_TOKEN` secret.
+
+## License
+
+MIT © Dominik Rycharski

package/dist/chunk-67J7X3FS.js

@@ -0,0 +1,255 @@
+// src/release.ts
+import { spawnSync } from "child_process";
+import path from "path";
+import { createInterface } from "readline/promises";
+import { stdin, stdout } from "process";
+
+// src/git.ts
+import { execSync } from "child_process";
+var sh = (cmd) => execSync(cmd, { encoding: "utf8" }).trim();
+var getRecentTags = () => {
+  try {
+    const out = sh("git tag --sort=-v:refname");
+    return out ? out.split("\n").filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+};
+var getCommitsSince = (ref) => {
+  try {
+    const range = ref ? `${ref}..HEAD` : "HEAD";
+    const out = sh(`git log ${range} --format=%B%x00`);
+    return out ? out.split("\0").map((msg) => msg.trim()).filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+};
+var ensureCleanTree = () => {
+  const status = sh("git status --porcelain");
+  if (status) {
+    console.error(
+      "\n\u2717 Working tree is not clean. Commit or stash changes first:\n"
+    );
+    console.error(status);
+    process.exit(1);
+  }
+};
+var ensureOnDefaultBranch = () => {
+  const branch = sh("git rev-parse --abbrev-ref HEAD");
+  if (branch !== "main" && branch !== "master") {
+    console.warn(`
+\u26A0 You are on branch "${branch}", not main/master.`);
+  }
+  return branch;
+};
+var parseActionsUrl = (remoteUrl) => {
+  const trimmed = remoteUrl.trim();
+  if (!trimmed) return null;
+  const ssh = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/.exec(trimmed);
+  if (ssh) return `https://github.com/${ssh[1]}/${ssh[2]}/actions`;
+  const https = /^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/.exec(trimmed);
+  if (https) return `https://github.com/${https[1]}/${https[2]}/actions`;
+  return null;
+};
+var getRemoteActionsUrl = () => {
+  try {
+    const remote = sh("git remote get-url origin");
+    return parseActionsUrl(remote);
+  } catch {
+    return null;
+  }
+};
+
+// src/pkg.ts
+import { readFile, writeFile } from "fs/promises";
+var readJson = async (file) => JSON.parse(await readFile(file, "utf8"));
+var writeJson = async (file, data) => {
+  await writeFile(file, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+};
+var updateVersionFile = async (file, newVersion) => {
+  const json = await readJson(file);
+  if (json.version === newVersion) return false;
+  json.version = newVersion;
+  await writeJson(file, json);
+  return true;
+};
+
+// src/semver.ts
+var parseSemver = (tag) => {
+  const match = /^v(\d+)\.(\d+)\.(\d+)(?:-([\w.-]+))?$/.exec(tag);
+  if (!match) return null;
+  const [, major, minor, patch, prerelease] = match;
+  return {
+    major: Number(major),
+    minor: Number(minor),
+    patch: Number(patch),
+    prerelease: prerelease ?? null
+  };
+};
+var applyBump = (v, type) => {
+  if (type === "major") return `v${v.major + 1}.0.0`;
+  if (type === "minor") return `v${v.major}.${v.minor + 1}.0`;
+  return `v${v.major}.${v.minor}.${v.patch + 1}`;
+};
+var determineBump = (commits) => {
+  let bump = "patch";
+  const subjectRe = /^(\w+)(?:\([^)]*\))?(!)?:/;
+  for (const msg of commits) {
+    const subject = msg.split("\n")[0];
+    const match = subjectRe.exec(subject);
+    const breaking = match?.[2] === "!" || /^BREAKING CHANGE:/m.test(msg);
+    if (breaking) return "major";
+    if (match?.[1] === "feat") bump = "minor";
+  }
+  return bump;
+};
+var stripV = (tag) => tag.startsWith("v") ? tag.slice(1) : tag;
+
+// src/release.ts
+var PACKAGE_JSON = path.join(process.cwd(), "package.json");
+var makeRunStep = (dryRun) => (label, cmd, args) => {
+  if (dryRun) {
+    console.log(`\u2192 [dry-run] ${label}`);
+    return;
+  }
+  console.log(`\u2192 ${label}`);
+  const result = spawnSync(cmd, args, { stdio: "inherit" });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+};
+var release = async (options = {}) => {
+  const flags = {
+    releaseVersion: options.releaseVersion,
+    bump: options.bump,
+    yes: options.yes ?? false,
+    dryRun: options.dryRun ?? false
+  };
+  ensureCleanTree();
+  const branch = ensureOnDefaultBranch();
+  const tags = getRecentTags();
+  const pkg = await readJson(PACKAGE_JSON);
+  console.log(`
+\u{1F4E6} ${pkg.name} \u2014 release
+`);
+  console.log(`Package:           ${pkg.name}`);
+  console.log(`Current branch:    ${branch}`);
+  console.log(`package.json:      ${pkg.version}`);
+  console.log(
+    `Recent tags:       ${tags.length ? tags.slice(0, 5).join(", ") : "(none)"}`
+  );
+  const latest = tags.find((t) => parseSemver(t));
+  const latestParsed = latest ? parseSemver(latest) : null;
+  const commitsSinceTag = getCommitsSince(latest ?? null);
+  const detectedBump = determineBump(commitsSinceTag);
+  const bumpType = flags.bump ?? detectedBump;
+  const proposed = latestParsed ? applyBump(latestParsed, bumpType) : `v${stripV(pkg.version)}`;
+  const bumpSource = flags.bump ? `${bumpType} bump, forced` : `${bumpType} bump`;
+  console.log(`Commits since tag: ${commitsSinceTag.length} (${bumpSource})`);
+  console.log(`Proposed new tag:  ${proposed}
+`);
+  const interactive = stdin.isTTY === true;
+  const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
+  const askVersion = async () => {
+    if (flags.releaseVersion) {
+      console.log(`Version (from --release-version):  ${flags.releaseVersion}`);
+      return flags.releaseVersion;
+    }
+    if (!rl) return proposed;
+    return (await rl.question(`Enter version (press Enter to accept ${proposed}): `)).trim();
+  };
+  const askConfirm = async () => {
+    if (flags.yes) {
+      console.log(`Proceed? [y/N]  y  (from --yes)`);
+      return true;
+    }
+    if (!rl) {
+      console.error(
+        "\n\u2717 Non-interactive run: pass --yes to skip the confirmation prompt."
+      );
+      process.exit(1);
+    }
+    const ans = (await rl.question(`Proceed? [y/N] `)).trim().toLowerCase();
+    return ans === "y" || ans === "yes";
+  };
+  const input = await askVersion();
+  const chosen = input || proposed;
+  const normalized = chosen.startsWith("v") ? chosen : `v${chosen}`;
+  const bareVersion = stripV(normalized);
+  if (!parseSemver(normalized)) {
+    console.error(`
+\u2717 Invalid semver tag: ${normalized}`);
+    rl?.close();
+    process.exit(1);
+  }
+  if (tags.includes(normalized)) {
+    console.error(`
+\u2717 Tag ${normalized} already exists.`);
+    rl?.close();
+    process.exit(1);
+  }
+  console.log(`
+This will:`);
+  console.log(`  1. Bump package.json   ${pkg.version}  \u2192  ${bareVersion}`);
+  console.log(`  2. Commit on ${branch}`);
+  console.log(`  3. Tag ${normalized} and push ${branch} + tag`);
+  console.log(`  4. GitHub Actions will build, test, and publish to npm
+`);
+  if (flags.dryRun) console.log("Dry-run mode: no changes will be made.\n");
+  const confirmed = await askConfirm();
+  rl?.close();
+  if (!confirmed) {
+    console.log("Aborted.");
+    process.exit(0);
+  }
+  const runStep = makeRunStep(flags.dryRun);
+  if (flags.dryRun) {
+    console.log(`\u2192 [dry-run] would bump package.json to ${bareVersion}`);
+  } else {
+    const pkgChanged = await updateVersionFile(PACKAGE_JSON, bareVersion);
+    if (!pkgChanged) {
+      console.warn("\n\u26A0 package.json already at target version.");
+    } else {
+      runStep(`git add package.json`, "git", ["add", "package.json"]);
+      runStep(`git commit -m "release: ${normalized}"`, "git", [
+        "commit",
+        "-m",
+        `release: ${normalized}`
+      ]);
+    }
+  }
+  runStep(`git tag ${normalized}`, "git", ["tag", normalized]);
+  runStep(`git push origin ${branch}`, "git", ["push", "origin", branch]);
+  if (!flags.dryRun) {
+    const pushTag = spawnSync("git", ["push", "origin", normalized], {
+      stdio: "inherit"
+    });
+    if (pushTag.status !== 0) {
+      console.error("\n\u2717 Tag push failed. Clean up local tag with:");
+      console.error(`  git tag -d ${normalized}`);
+      process.exit(pushTag.status ?? 1);
+    }
+  } else {
+    runStep(`git push origin ${normalized}`, "git", [
+      "push",
+      "origin",
+      normalized
+    ]);
+  }
+  if (flags.dryRun) {
+    console.log(
+      `
+\u2713 Dry-run complete. Re-run without --dry-run to actually release ${normalized}.`
+    );
+    return;
+  }
+  console.log(
+    `
+\u2713 Tag ${normalized} pushed. GitHub Actions will build, test, and publish to npm.`
+  );
+  const actionsUrl = getRemoteActionsUrl();
+  if (actionsUrl) console.log(`  Watch: ${actionsUrl}`);
+};
+
+export {
+  release
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import {
+  release
+} from "./chunk-67J7X3FS.js";
+
+// src/cli.ts
+import { Command, InvalidArgumentError } from "commander";
+var BUMP_LEVELS = ["major", "minor", "patch"];
+var parseBump = (value) => {
+  if (BUMP_LEVELS.includes(value)) {
+    return value;
+  }
+  throw new InvalidArgumentError("--bump must be one of: major, minor, patch");
+};
+var program = new Command().name("doryski-release").description("Bump package.json, tag, and push to trigger the npm release.").option(
+  "-r, --release-version <ver>",
+  "release version (e.g. 0.2.0 or v0.2.0); defaults to a conventional-commit bump of the latest tag"
+).option(
+  "--bump <major|minor|patch>",
+  "force the bump level (overrides the auto-detected level; ignored when --release-version is set)",
+  parseBump
+).option("-y, --yes", "skip the confirmation prompt", false).option(
+  "-n, --dry-run",
+  "preview the actions without modifying files, committing, tagging, or pushing",
+  false
+).helpOption("-h, --help", "show help");
+program.parse();
+var flags = program.opts();
+release({
+  releaseVersion: flags.releaseVersion,
+  bump: flags.bump,
+  yes: flags.yes,
+  dryRun: flags.dryRun
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+type BumpType = "major" | "minor" | "patch";
+type ParsedSemver = {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string | null;
+};
+
+type ReleaseOptions = {
+    releaseVersion?: string;
+    bump?: BumpType;
+    yes?: boolean;
+    dryRun?: boolean;
+};
+declare const release: (options?: ReleaseOptions) => Promise<void>;
+
+export { type BumpType, type ParsedSemver, type ReleaseOptions, release };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  release
+} from "./chunk-67J7X3FS.js";
+export {
+  release
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@doryski/release",
+  "version": "1.0.0",
+  "description": "A conventional-commit release CLI and reusable GitHub Actions workflow for npm packages",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "doryski-release": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts --format esm --dts --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --maxWorkers=1 --bail=5",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build",
+    "release": "tsx src/cli.ts"
+  },
+  "keywords": [
+    "release",
+    "semver",
+    "conventional-commits",
+    "cli",
+    "npm",
+    "publish",
+    "github-actions",
+    "workflow"
+  ],
+  "author": "Dominik Rycharski (https://github.com/Doryski)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Doryski/release.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Doryski/release/issues"
+  },
+  "homepage": "https://github.com/Doryski/release#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.2.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.1.5"
+  }
+}