localbadge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Teplostanski Igor (https://github.com/teplostanski)
+
+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

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# localbadge
 
-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.
+**You need a badge. Why does it need a service?**
+
+Generate SVG badges right in your repository, locally or in GitHub Actions.
+No sign-ups, external service tokens, or API rate limits.
+Customize colors, labels, and styles in your project.
+
+Your badge lives alongside your README. Displaying it requires no requests to
+Codecov, Bundlephobia, or shields.io.
+
+Currently supports **coverage** for Vitest through a CLI and a programmatic API.
+**bundle-size** with a CLI and API is planned.
+
+## Quick start
+
+Add `localbadge` to a project using Vitest and `@vitest/coverage-v8`.
+Vitest and the coverage provider must have matching versions, at least 5.1.0.
+
+```sh
+pnpm add -D localbadge
+pnpm exec localbadge coverage --output-dir .github/badges --file-name coverage
+```
+
+The command runs your tests, calculates line coverage, and saves an SVG.
+Add it to your README:
+
+```md
+![coverage](.github/badges/coverage.svg)
+```
+
+Run the same command in GitHub Actions. To update the badge in your README,
+commit the generated SVG to your repository.
+
+## Configuration
+
+Create `localbadge.config.ts`:
+
+```ts
+import { defineConfig } from 'localbadge'
+
+export default defineConfig({
+  outputDir: '.github/badges',
+  coverage: {
+    fileName: 'coverage',
+    badge: {
+      label: 'coverage',
+      color: 'brightgreen',
+      labelColor: 'black',
+      style: 'flat',
+    },
+  },
+})
+```
+
+Duplicate settings inherit from the nearest ancestor. The deeper an explicit
+value is defined, the higher its priority. For example:
+`coverage.badge.color` > `coverage.color` > `color` > built-in default.
+At the same depth, CLI arguments override configuration values.
+
+```sh
+pnpm exec localbadge coverage --debug-config
+pnpm exec localbadge coverage --dry-run
+pnpm exec localbadge coverage --help
+```
+
+`--debug-config` shows resolved values and their sources.
+`--dry-run` calculates coverage and generates the SVG without writing the badge.
+
+## Programmatic API
+
+```ts
+import { generateBadge, resolveOptions } from 'localbadge'
+
+const options = await resolveOptions()
+await generateBadge(options)
+```
+
+Only need the number? Use `getCoveragePercent()` from `localbadge`.
+
+## Agent skills
+
+The npm package includes skills for configuring coverage badges and integrating
+badge generation into CI under `skills/`. Both work from the installed package
+without downloading additional instructions.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for CI checks, trusted publishing setup,
+and the dependency update schedule.

package/dist/badge--GDl23Q5.js

@@ -0,0 +1,184 @@
+import pc from "picocolors";
+import defu from "defu";
+import { loadConfig } from "unconfig";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { makeBadge } from "badge-maker";
+import boxen from "boxen";
+import { startVitest } from "vitest/node";
+// src/config.ts
+const defaultOptions = {
+	cwd: "",
+	outputDir: "",
+	coverage: {
+		cwd: "",
+		silentMode: false,
+		noColor: false,
+		outputDir: "",
+		fileName: "coverage-badge",
+		badge: {
+			label: "coverage",
+			color: "green",
+			labelColor: "gray",
+			style: "flat"
+		}
+	}
+};
+const defineConfig = (options) => {
+	return options;
+};
+const resolveOptionsWithSources = async (overrides = {}) => {
+	const files = /* @__PURE__ */ new Map();
+	const cwd = overrides.cwd || process.cwd();
+	const { config, sources } = await loadConfig({
+		cwd,
+		sources: [{
+			files: ["localbadge.config"],
+			extensions: [
+				"ts",
+				"mts",
+				"cts",
+				"js",
+				"mjs",
+				"cjs",
+				"json"
+			],
+			rewrite: (values, filepath) => {
+				const options = values;
+				files.set(filepath, options);
+				return options;
+			}
+		}],
+		merge: true
+	});
+	const runtimeDefaults = {
+		...defaultOptions,
+		cwd: process.cwd()
+	};
+	const explicit = defu(overrides, config ?? {});
+	const shape = defu(explicit, runtimeDefaults);
+	const layers = [
+		{
+			source: "CLI",
+			values: overrides
+		},
+		...sources.map((source) => ({
+			source,
+			values: files.get(source) ?? {}
+		})),
+		{
+			source: "default",
+			values: runtimeDefaults
+		}
+	];
+	const entries = [];
+	const read = (values, keys) => {
+		let value = values;
+		for (const key of keys) {
+			if (value === null || typeof value !== "object") return void 0;
+			value = value[key];
+		}
+		return value;
+	};
+	const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+	const visit = (values, keys = []) => {
+		const result = {};
+		for (const [key, value] of Object.entries(values)) {
+			const path = [...keys, key];
+			if (isRecord(value)) result[key] = visit(value, path);
+			else {
+				let selected = value;
+				let source = "default";
+				for (let depth = keys.length; depth >= 0; depth--) {
+					const candidate = [...keys.slice(0, depth), key];
+					const inherited = read(explicit, candidate);
+					if (inherited == null || isRecord(inherited)) continue;
+					selected = inherited;
+					source = layers.find(({ values }) => read(values, candidate) != null)?.source ?? "default";
+					break;
+				}
+				result[key] = selected;
+				entries.push({
+					setting: path.join("."),
+					value: selected,
+					source
+				});
+			}
+		}
+		return result;
+	};
+	return {
+		options: visit(shape),
+		entries
+	};
+};
+const resolveOptions = async (overrides = {}) => {
+	return (await resolveOptionsWithSources(overrides)).options;
+};
+// src/coverage/coverage.ts
+const getCoveragePercent = async (cwd = process.cwd()) => {
+	let linesPercent;
+	await startVitest([], {
+		root: cwd,
+		run: true,
+		reporters: ["dot", { onCoverage(coverage) {
+			const pct = coverage.getCoverageSummary().lines.pct;
+			if (typeof pct !== "number") throw new Error("Vitest coverage \"lines\": Unknown");
+			linesPercent = pct;
+		} }],
+		silent: true,
+		coverage: {
+			enabled: true,
+			clean: false,
+			reporter: [],
+			reportOnFailure: true
+		}
+	});
+	if (linesPercent === void 0) throw new Error("Vitest did not provide coverage data");
+	return linesPercent;
+};
+// src/coverage/badge.ts
+const escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+const generateBadge = async (options, { dryRun = false } = {}) => {
+	const cwd = options.coverage.cwd || options.cwd || process.cwd();
+	const pct = Math.floor(await getCoveragePercent(cwd));
+	const svg = makeBadge({
+		label: options.coverage.badge.label,
+		message: `${pct}%`,
+		color: options.coverage.badge.color,
+		labelColor: options.coverage.badge.labelColor,
+		style: options.coverage.badge.style
+	});
+	const dirParts = (options.coverage.outputDir || options.outputDir).split(/[\\/]+/).filter(Boolean);
+	if (dirParts.includes("..")) throw new Error("\"outputDir\" must not contain \"..\"");
+	const outputDir = path.join(cwd, ...dirParts);
+	const fileName = `${options.coverage.fileName}.svg`;
+	if (!dryRun) {
+		await mkdir(outputDir, { recursive: true });
+		await writeFile(path.join(outputDir, fileName), svg, "utf8");
+	}
+	if (options.coverage.silentMode) return;
+	const color = pc.createColors(!options.coverage.noColor);
+	const markdownPath = [...dirParts, fileName].join("/");
+	const safePath = escapeHtml(markdownPath);
+	const safeLabel = escapeHtml(options.coverage.badge.label);
+	const hint = `
+${dryRun ? `Dry run: coverage ${pct}%. Badge would be written to:` : "Coverage badge created at:"}
+${color.cyan(color.underline(`${outputDir}/${fileName}`))}
+
+${color.gray("Markdown:")}
+${color.blue("!")}[${options.coverage.badge.label}]${color.cyan(`(${color.redBright(markdownPath)})`)}
+
+${color.gray("HTML:")}
+<${color.blue("img")} ${color.red("src")}=${color.yellow(`"${safePath}"`)} ${color.red("alt")}=${color.yellow(`"${safeLabel}"`)}>
+`;
+	console.log(boxen(hint, {
+		borderStyle: "round",
+		borderColor: "cyan",
+		padding: {
+			left: 2,
+			right: 2
+		}
+	}));
+};
+export { resolveOptions as a, defineConfig as i, getCoveragePercent as n, resolveOptionsWithSources as o, defaultOptions as r, generateBadge as t };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+type DeepRequired<T> = T extends object ? { [K in keyof T]-?: NonNullable<T[K]> extends object ? DeepRequired<NonNullable<T[K]>> : T[K]; } : T;
+type BadgeOptions = {
+  label?: string;
+  color?: string;
+  labelColor?: string;
+  style?: 'flat' | 'plastic' | 'flat-square' | 'for-the-badge' | 'social';
+};
+type SharedOptions = BadgeOptions & {
+  cwd?: string;
+  outputDir?: string;
+  silentMode?: boolean;
+  noColor?: boolean;
+  fileName?: string;
+};
+type Options = SharedOptions & {
+  coverage?: SharedOptions & {
+    badge?: BadgeOptions;
+  };
+};
+type ResolvedOptions = {
+  cwd: string;
+  outputDir: string;
+  coverage: DeepRequired<Omit<SharedOptions, keyof BadgeOptions>> & {
+    badge: DeepRequired<BadgeOptions>;
+  };
+};
+export declare const defaultOptions: {
+  cwd: string;
+  outputDir: string;
+  coverage: {
+    cwd: string;
+    silentMode: false;
+    noColor: false;
+    outputDir: string;
+    fileName: string;
+    badge: {
+      label: string;
+      color: string;
+      labelColor: string;
+      style: "flat";
+    };
+  };
+};
+export declare const defineConfig: (options: Options) => Options;
+export declare const resolveOptionsWithSources: (overrides?: Options) => Promise<{
+  options: ResolvedOptions;
+  entries: {
+    setting: string;
+    value: unknown;
+    source: string;
+  }[];
+}>;
+export declare const resolveOptions: (overrides?: Options) => Promise<ResolvedOptions>;
+export declare const generateBadge: (options: ResolvedOptions, { dryRun }?: {
+  dryRun?: boolean;
+}) => Promise<void>;
+export declare const getCoveragePercent: (cwd?: string) => Promise<number>;
+export type { Options, ResolvedOptions };

package/dist/index.js

@@ -0,0 +1 @@
+export { r as defaultOptions, i as defineConfig, t as generateBadge, n as getCoveragePercent, a as resolveOptions, o as resolveOptionsWithSources } from "./badge--GDl23Q5.js";

package/dist/localbadge.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/localbadge.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { o as resolveOptionsWithSources, r as defaultOptions, t as generateBadge } from "./badge--GDl23Q5.js";
+import { defineCommand, runMain } from "citty";
+import pc from "picocolors";
+// package.json
+var name = "localbadge";
+var version = "0.1.0";
+var description = "Generate coverage badges in your repo. No external services.";
+// src/cli.ts
+const coverage = defineCommand({
+	meta: {
+		name: "coverage",
+		description: "coverage command"
+	},
+	args: {
+		"output-dir": {
+			type: "string",
+			description: `Output directory ${pc.dim(`(Default: cwd)`)}`,
+			valueHint: "dir"
+		},
+		"file-name": {
+			type: "string",
+			description: `Output file name without extension ${pc.dim(`(Default: ${defaultOptions.coverage.fileName})`)}`,
+			valueHint: "name"
+		},
+		cwd: {
+			type: "string",
+			description: `Project root ${pc.dim(`(Default: process.cwd())`)}`,
+			valueHint: "dir"
+		},
+		silent: {
+			type: "boolean",
+			description: `Suppress output ${pc.dim(`(Default: ${defaultOptions.coverage.silentMode})`)}`
+		},
+		"no-color": {
+			type: "boolean",
+			description: `Disable cli output colors ${pc.dim(`(Default: ${defaultOptions.coverage.noColor})`)}`
+		},
+		label: {
+			type: "string",
+			description: `Badge label ${pc.dim(`(Default: ${defaultOptions.coverage.badge.label})`)}`,
+			valueHint: "text"
+		},
+		color: {
+			type: "string",
+			description: `Badge color ${pc.dim(`(Default: ${defaultOptions.coverage.badge.color})`)}`
+		},
+		"label-color": {
+			type: "string",
+			description: `Badge label color ${pc.dim(`(Default: ${defaultOptions.coverage.badge.labelColor})`)}`,
+			valueHint: "color"
+		},
+		style: {
+			type: "enum",
+			description: `Badge style ${pc.dim(`(Default: ${defaultOptions.coverage.badge.style})`)}`,
+			options: [
+				"flat",
+				"plastic",
+				"flat-square",
+				"for-the-badge",
+				"social"
+			],
+			valueHint: "style"
+		},
+		mode: {
+			type: "enum",
+			description: `Badge style mode ${pc.dim(`(Default: shields-io)`)}`,
+			options: ["shields-io"]
+		},
+		"debug-config": {
+			type: "boolean",
+			description: `Print resolved settings and their sources`
+		},
+		"dry-run": {
+			type: "boolean",
+			description: `Run coverage and generate a badge without writing it`
+		}
+	},
+	run: async ({ args }) => {
+		const overrides = {
+			cwd: args.cwd,
+			coverage: {
+				silentMode: args.silent,
+				noColor: args["no-color"],
+				outputDir: args["output-dir"],
+				fileName: args["file-name"],
+				badge: {
+					label: args.label,
+					color: args.color,
+					labelColor: args["label-color"],
+					style: args.style
+				}
+			}
+		};
+		try {
+			const { options, entries } = await resolveOptionsWithSources(overrides);
+			if (args["debug-config"]) console.table(entries);
+			await generateBadge(options, { dryRun: args["dry-run"] });
+		} catch (error) {
+			console.error(pc.red(`Error: ${error.message}`));
+			process.exit(1);
+		}
+	}
+});
+const main = defineCommand({
+	meta: {
+		name: `${name}`,
+		version: `${version}`,
+		description: `${description}`
+	},
+	subCommands: { coverage }
+});
+runMain(main);
+export {};

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "localbadge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Generate coverage badges in your repo. No external services.",
+  "author": "Teplostanski Igor <hi@teplostanski.me> (https://teplostanski.me)",
+  "license": "MIT",
+  "homepage": "https://github.com/teplostanski/localbadge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teplostanski/localbadge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/teplostanski/localbadge/issues"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build",
+    "prepack": "pnpm typecheck && pnpm build",
+    "check": "pnpm lint && pnpm typecheck",
+    "check:fix": "pnpm lint:fix && pnpm typecheck",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "prepare": "husky",
+    "smoke": "node scripts/package-smoke.mjs",
+    "check:ci": "pnpm lint && pnpm typecheck && pnpm exec vitest run && pnpm build && pnpm smoke"
+  },
+  "peerDependencies": {
+    "@vitest/coverage-v8": ">=5.1.0",
+    "vitest": ">=5.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.7",
+    "@teplostanski/biome-config": "^2.0.3",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-v8": "^5.1.0",
+    "@vitest/istanbul-lib-coverage": "^2.1.0",
+    "husky": "^9.1.7",
+    "tsdown": "^0.23.7",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "dependencies": {
+    "badge-maker": "^6.0.0",
+    "boxen": "^9.0.0",
+    "citty": "^0.2.2",
+    "defu": "^6.1.7",
+    "picocolors": "^1.1.1",
+    "unconfig": "^7.5.0"
+  },
+  "packageManager": "pnpm@12.21.0",
+  "bin": {
+    "localbadge": "dist/localbadge.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/localbadge-ci/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: localbadge-ci
+description: Integrate localbadge coverage badge generation into GitHub Actions or other CI. Use when replacing hosted coverage badge services or deciding how to persist a generated SVG; use localbadge-coverage for styling and API configuration.
+---
+
+# Coverage badges in CI
+
+Inspect the project's workflow, package manager and Vitest configuration before
+editing. Use its existing installation and Node setup. Vitest and
+@vitest/coverage-v8 must have matching versions, at least 5.1.0.
+
+After dependency installation, run:
+
+```sh
+pnpm exec localbadge coverage --output-dir .github/badges --file-name coverage
+```
+
+This command already runs the tests with coverage. Avoid adding another identical
+test run solely to produce the badge. It does not upload results to a service.
+A dry run executes tests but does not persist a badge.
+
+A README link to `.github/badges/coverage.svg` reads the file from the repository,
+not from the runner. A generated runner file or downloadable Actions artifact
+does not update that README badge. Agree on how the SVG will be persisted before
+adding write credentials or automatic commits. Do not create commits or PRs unless
+the user has authorized them. Keep untrusted pull-request runs read-only.
+
+For an initial verification, use `--dry-run --debug-config` to inspect the selected
+settings and test the calculation. To generate an artifact, omit `--dry-run` and
+use the project's artifact upload step with the actual output path. Report whether
+the result is only an artifact or has been made available to the README.

package/skills/localbadge-coverage/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: localbadge-coverage
+description: Generate and customize repository-local Vitest coverage badges with localbadge through its CLI or TypeScript API. Use when adding a coverage SVG to a README or configuring localbadge; use localbadge-ci for release and CI integration.
+---
+
+# Local coverage badges
+
+Read the installed localbadge package version and the project's Vitest setup.
+Vitest and @vitest/coverage-v8 must have identical versions, at least 5.1.0.
+Reuse the project's package manager and tests. Coverage measures lines and the
+badge rounds the result down to a whole percentage.
+
+Run `localbadge coverage --output-dir .github/badges --file-name coverage` through
+the package manager. Add `![coverage](.github/badges/coverage.svg)` to the README.
+No coverage service credentials or uploads are needed.
+
+For persistent settings, create `localbadge.config.ts`:
+
+```ts
+import { defineConfig } from 'localbadge'
+
+export default defineConfig({
+  outputDir: '.github/badges',
+  coverage: {
+    fileName: 'coverage',
+    badge: { label: 'coverage', color: 'brightgreen', style: 'flat' },
+  },
+})
+```
+
+Explicit duplicate values inherit from their nearest ancestor. For example,
+coverage.badge.color overrides coverage.color, which overrides root color.
+Depth wins across sources; CLI wins at the same depth. Defaults apply last.
+The root cwd controls config discovery; coverage.cwd controls tests and output.
+
+Use `--debug-config` to inspect values and their sources. `--dry-run` still runs
+tests and creates the SVG in memory, but does not create the badge directory or
+write the SVG. It does not suppress side effects inside tests.
+
+For TypeScript integration:
+
+```ts
+import { generateBadge, getCoveragePercent, resolveOptions } from 'localbadge'
+
+const options = await resolveOptions()
+await generateBadge(options)
+// Alternatively, skip writing the badge:
+await generateBadge(options, { dryRun: true })
+// Or retrieve only the numeric line coverage:
+const percentage = await getCoveragePercent(options.coverage.cwd || options.cwd)
+```
+
+Do not advertise bundle-size as implemented. It is planned.