@opndev/rzilla 0.0.1

package/Changes

@@ -0,0 +1,5 @@
+Revision history for @opndev/rzilla
+
+{{ NEXT }}
+
+    * First release to an unsuspecting world

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2016 Wesley Schwengle <wesleys@opperschaap.net>
+
+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,279 @@
+<!--
+SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+
+SPDX-License-Identifier: MIT
+-->
+
+# @opndev/rzilla
+
+Release zilla for npm packages.
+
+`rzil` lets you replace manual `package.json` maintenance with a
+declarative `dist.toml` file.\
+Inspired by Dist::Zilla, but for npm.
+
+## Philosophy
+
+- `dist.toml` is the source of truth.
+- `package.json` is a generated artifact.
+- Strict where ambiguity is dangerous.
+- Ergonomic where it does not matter.
+- No automatic pushing.
+- Deterministic releases.
+
+## Commands
+
+The following commands are listed, but maybe incomplete. Please run the actual
+script for an update to date listing.
+
+``` bash
+rzil pkg       # Generate package.json from dist.toml
+rzil release   # Run release workflow
+rzil test      # npm test
+rzil build     # Run build workflow
+rzil clean     # Clean the .build dir
+rzil prereqs   # List all the dependencies
+```
+
+# dist.toml Example
+
+``` toml
+name = "@opndev/rzilla"
+description = "Release zilla for npm packages"
+type = "module"
+keywords = ["release","npm","changes","git"]
+
+[license]
+spdx = "MIT"
+file = "LICENSES/MIT.txt"
+
+[author]
+name = "Your Name"
+email = "you@example.com"
+
+[repository]
+remote = "origin"
+
+[prereqs]
+node = ">= 18 < 22"
+npm  = ">= 9"
+lodash = "^4.17.0"
+
+[prereqs.dev]
+tap = "latest"
+jsdoc = "0"
+
+[prereqs.peer]
+left-pad = "latest"
+
+[gather]
+main = "lib/index.mjs"
+bin = "bin"
+files = "lib/**/*.mjs"
+include = ["README.md"]
+
+[exports]
+__DOT__ = "lib/index.mjs"
+foo = "lib/foo.mjs"
+
+[release]
+changes = "Changes"
+tagPrefix = "v"
+bump = "patch"
+access = "public"
+
+[release.preflight]
+dirty = "dist.toml"
+airplane = false
+
+[release.after]
+commit = ["Changes", "dist.toml", "package.json"]
+bump = true
+```
+
+# Key Concepts
+
+## package.json is generated
+
+Run:
+
+``` bash
+rzil pkg
+```
+
+This creates:
+
+- `package.json`
+- `bin` entries from `gather.bin`
+- `exports` map
+- dependencies from `[prereqs]`
+- engines from `node` and `npm`
+- repository + homepage derived from git remote
+
+Do not edit `package.json` manually.
+
+
+## Prereqs
+
+Prereqs or dependencies can be set via `[prereqs]` and friends:
+
+``` toml
+[prereqs]
+node = ">= 18 < 22"
+npm  = ">= 9"
+foo  = "^1.2.3"
+bar  = 0
+baz  = "latest"
+```
+
+Mapping:
+
+- `node` → `engines.node`
+- `npm` → `engines.npm`
+- others → `dependencies`
+- `0` → `"*"`
+- Spaces in ranges are normalized (`"> 18 < 22"` → `">18 <22"`)
+
+```toml
+[prereqs.test]
+tap = "latest"
+
+[prereqs.peer]
+left-pad = "latest"
+```
+
+## Autoprereqs
+
+When enabled, rzil scans your source tree and fills in missing dependencies:
+
+``` toml
+[autoprereqs]
+# enabled when the table exists
+# enabled = true
+ignore = ["node:fs"]
+```
+
+- Runtime imports (uses the `[gather]` paths/globs) are added to
+  `dependencies`.
+- Test imports (from `t/`, `test/`, `tests/`, `__tests__/`) are added to
+  `devDependencies`.
+- Inferred versions default to `"latest"`.
+- Explicit entries in `[prereqs]` always win.
+- Relative imports and Node builtins are ignored.
+
+## Gather
+
+``` toml
+[gather]
+main = "lib/index.mjs"
+bin  = ["bin", "cli"]
+files = "lib/**/*.mjs"
+include = ["README.md"]
+```
+
+- `main` defines the root export `"."`
+- `bin` auto-discovers CLI files
+- `files` and `include` populate `package.json.files`
+- `bin` supports string or array
+- You don't need to add your license file, it is taken from `license.file`.
+
+
+## License
+
+``` toml
+[license]
+spdx = "MIT"
+file = "LICENSES/MIT.txt"
+```
+
+- `spdx` becomes `package.json.license`.
+- `file` is written as `LICENSE` in the build artifact.
+
+
+## Exports
+
+``` toml
+[exports]
+__DOT__ = "lib/index.mjs"
+foo = "lib/foo.mjs"
+
+[exports.deny]
+testing = true
+```
+
+Rules:
+
+- `__DOT__` → `"."`
+- other keys → `"./key"`
+- `exports.deny` removes subpaths
+- `exports.deny.__DOT__` is forbidden
+
+If `[exports]` exists, you fully control the export surface.
+
+
+## Repository
+
+``` toml
+[repository]
+remote = "origin"
+provider = "github"   # optional
+```
+
+rzil:
+
+- reads `git remote`
+- derives `repository.url`
+- derives `repository.homepage`
+- derives `bugs.url` if `[bugtracker]` exists
+- supports github, gitlab, codeberg, bitbucket
+- supports private hosts with `provider`
+
+rzil never pushes automatically.
+
+
+## Release Workflow
+
+``` bash
+rzil release
+```
+
+Steps:
+
+1.  Check `{{ NEXT }}` in Changes has entries
+2.  Run tests
+3.  Check git dirty state (with allowlist)
+4.  Create a build directory (`.build/<id>/` and `.build/current`)
+5.  Copy only publishable files into the build directory
+6.  Generate `package.json` (and other build artifacts) into the build
+    directory
+7.  Finalize Changes
+8.  Commit release
+9.  Tag release
+10. `npm publish` from `.build/current` (unless airplane mode)
+11. Restore `{{ NEXT }}`
+12. Bump version (optional)
+13. Commit post-release files
+
+
+You push manually.
+
+Airplane mode disables network actions.
+
+## Status
+
+Early-stage but functional.
+
+## Developer notes
+
+### Semver
+
+This package does not adhere to semver. It's just a version number.
+
+### Lock files
+
+Ignored. Keep your deps minimal and I'll promise to not break your code.
+
+### Code of Conduct
+
+Be human.
+

package/lib/builddir.mjs

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+async function mkdirp(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function rmForce(p) {
+  await fs.rm(p, { recursive: true, force: true });
+}
+
+function randId() {
+  // short, readable, collision-resistant enough for builds
+  return crypto.randomBytes(8).toString("hex");
+}
+
+/**
+ * Creates .build/<id>/ and updates .build/current -> <id>
+ * Returns { buildRoot, buildDir, currentPath }
+ */
+export async function createBuildDir({ buildRoot = ".build" } = {}) {
+  const id = randId();
+  const buildDir = path.join(buildRoot, id);
+  const currentPath = path.join(buildRoot, "current");
+
+  await mkdirp(buildDir);
+
+  // Replace current pointer atomically-ish:
+  // Create a temp symlink then rename it into place.
+  const tmpLink = path.join(buildRoot, `.current-tmp-${id}`);
+
+  // Ensure buildRoot exists
+  await mkdirp(buildRoot);
+
+  // Remove any stale temp link
+  await rmForce(tmpLink);
+
+  // Create symlink pointing to the *id directory*, relative for readability
+  // current -> <id>
+  await fs.symlink(id, tmpLink, "dir");
+
+  // Remove old current, then move tmp into place
+  await rmForce(currentPath);
+  await fs.rename(tmpLink, currentPath);
+
+  return { buildRoot, buildDir, currentPath, id };
+}
+

package/lib/changes.mjs

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs/promises";
+
+export async function readChanges(path) {
+  return fs.readFile(path, "utf8");
+}
+
+export async function writeChanges(path, text) {
+  await fs.writeFile(path, text, "utf8");
+}
+
+function formatUtcStamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const y = date.getUTCFullYear();
+  const m = pad(date.getUTCMonth() + 1);
+  const d = pad(date.getUTCDate());
+  const hh = pad(date.getUTCHours());
+  const mm = pad(date.getUTCMinutes());
+  const ss = pad(date.getUTCSeconds());
+  return `${y}-${m}-${d} ${hh}:${mm}:${ss}Z`;
+}
+
+export function extractNextSection(changesText) {
+  const marker = "{{ NEXT }}";
+  const idx = changesText.indexOf(marker);
+  if (idx === -1) throw new Error(`Could not find ${marker} in Changes`);
+
+  const after = changesText.slice(idx + marker.length);
+
+  // End NEXT section at the first blank line before a version header like:
+  // 0.0.8       2024-06-04 ...
+  const match = after.match(/\n\s*\n(?=\d+\.\d+\.\d+\s+)/);
+  const endRel = match ? match.index + match[0].length : after.length;
+
+  const nextBody = after.slice(0, endRel);
+  return { nextBody };
+}
+
+export function nextHasEntries(changesText) {
+  const { nextBody } = extractNextSection(changesText);
+  const lines = nextBody.split("\n").map((l) => l.trim());
+  return lines.some((l) => l.startsWith("* ") || l.startsWith("- "));
+}
+
+export function finalizeNextToVersion(changesText, version) {
+  const marker = "{{ NEXT }}";
+  const stamp = formatUtcStamp();
+  const replacement = `${version}       ${stamp}`;
+
+  if (!changesText.includes(marker)) {
+    throw new Error(`Could not find ${marker} in Changes`);
+  }
+
+  // Replace only the first occurrence
+  return changesText.replace(marker, replacement);
+}
+
+export function ensureNextInserted(changesText) {
+  const marker = "{{ NEXT }}";
+  if (changesText.includes(marker)) return changesText;
+
+  const lines = changesText.split("\n");
+
+  // Insert after the first blank line (usually after "Revision history for ...")
+  let insertAt = 1;
+  for (let i = 0; i < Math.min(lines.length, 20); i++) {
+    if (lines[i].trim() === "" && i > 0) {
+      insertAt = i + 1;
+      break;
+    }
+  }
+
+  const block = [
+    "{{ NEXT }}",
+    "",
+    "  * ",
+    "",
+  ];
+
+  lines.splice(insertAt, 0, ...block);
+  return lines.join("\n");
+}

package/lib/cmd/build.mjs

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readDistToml } from "../config.mjs";
+import { asArray } from "@opndev/util";
+
+import { createBuildDir } from "../builddir.mjs";
+import { populateBuildDir } from "../populate.mjs";
+import { runPkg } from "./pkg.mjs";
+
+async function writeBuildLicense({ buildDir, license }) {
+  // dist.toml:
+  // [license]
+  // spdx = "MIT"
+  // file = "LICENSES/MIT.txt"
+  if (!license?.file) return;
+
+  const text = await fs.readFile(license.file, "utf8");
+  await fs.writeFile(path.join(buildDir, "LICENSE"), text, "utf8");
+}
+
+async function copyAfterBuild({ buildDir, copyList }) {
+  for (const rel of copyList) {
+    const src = path.join(buildDir, rel);
+    const dst = path.join(process.cwd(), rel);
+    await fs.mkdir(path.dirname(dst), { recursive: true });
+    await fs.copyFile(src, dst);
+  }
+}
+
+export async function runBuild() {
+  const { cfg } = await readDistToml("dist.toml");
+
+  // 1) Create build dir + .build/current
+  const { buildDir, currentPath } = await createBuildDir({ buildRoot: ".build" });
+
+  // 2) Populate build dir with publishable files only
+  {
+    const g = cfg.gather ?? {};
+    const files = asArray(g.files ?? "lib/**/*.{mjs,cjs,js}");
+    const include = asArray(g.include ?? []);
+    const bin = asArray(g.bin ?? []);
+    await populateBuildDir({
+      buildDir,
+      files,
+      include,
+      binDirs: bin, // NOTE: your populateBuildDir should treat these as globs if that's your gather model
+    });
+  }
+
+  // 3) Generate package.json into build dir (emitFiles=false because build dir is already pruned)
+  await runPkg({ outDir: buildDir, emitFiles: false });
+
+  // 4) Materialize LICENSE into build dir
+  await writeBuildLicense({ buildDir, license: cfg.license });
+
+  // 5) build.after.copy back into repo root (optional)
+  {
+    const copyList = asArray(cfg.build?.after?.copy ?? []);
+    if (copyList.length) {
+      await copyAfterBuild({ buildDir, copyList });
+    }
+  }
+
+  console.log(`Built distribution in ${currentPath}`);
+}
+

package/lib/cmd/clean.mjs

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function runClean() {
+  const buildDir = path.join(process.cwd(), ".build");
+
+  try {
+    await fs.rm(buildDir, { recursive: true, force: true });
+    console.log("Removed .build directory.");
+  } catch (err) {
+    throw new Error(`Failed to clean .build: ${err.message}`);
+  }
+}
+

package/lib/cmd/pkg.mjs

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesleys@opperschaap.net>
+//
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs/promises";
+import { readDistToml } from "../config.mjs";
+import { uniq } from "@opndev/util";
+import { deriveRepoAndBugs } from "../plugins/repository.mjs";
+import { applyPrereqs } from "../plugins/prereqs.mjs";
+import { buildExports } from "../plugins/exports.mjs";
+import { gatherConfig, discoverBins, buildFilesList } from "../plugins/gather.mjs";
+import { applyAutoPrereqs } from "../plugins/autoprereqs.mjs";
+import { readVersion } from "../version.mjs";
+
+
+async function basePkgFromCfg(cfg) {
+  const version = await readVersion(cfg);
+  const pkg = {
+    name: cfg.name,
+    version: version,
+    description: cfg.description,
+    type: cfg.type ?? "module",
+    keywords: cfg.keywords,
+  };
+
+
+  pkg.sideEffects = cfg.sideEffects ?? false;
+
+  if (typeof pkg.sideEffects !== "boolean")
+    throw new Error(`sideEffects must be boolean (true/false)`);
+
+  if (cfg.private != null && typeof cfg.private !== "boolean") {
+    throw new Error(`private must be boolean (true/false), got ${typeof cfg.private}`);
+  }
+
+  if (cfg.author) pkg.author = cfg.author;
+
+  if (cfg.license?.spdx) {
+    pkg.license = cfg.license.spdx;
+    if (cfg.private == null) cfg.private = false;
+  }
+  else {
+    pkg.license = "UNLICENSED";
+    if (cfg.private == null) cfg.private = true;
+  }
+
+  if (cfg.private) pkg.private = cfg.private;
+
+  if (cfg.scripts) pkg.scripts = cfg.scripts;
+
+  return pkg;
+}
+
+function sortKeysDeep(obj) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return obj;
+  const out = {};
+  for (const k of Object.keys(obj).sort()) out[k] = sortKeysDeep(obj[k]);
+  return out;
+}
+
+export async function runPkg({ outDir = ".", emitFiles = true, msg = true } = {}) {
+  const { cfg } = await readDistToml("dist.toml");
+
+  const pkg = await basePkgFromCfg(cfg);
+
+  const g = gatherConfig(cfg);
+  const { bin } = await discoverBins(g.binGlob);
+  if (Object.keys(bin).length) pkg.bin = bin;
+
+  if (emitFiles) {
+    const files = buildFilesList({
+      files: g.files,
+      include: g.include,
+      binGlob: g.binGlob,
+    });
+    if (files.length) pkg.files = files;
+  }
+
+  const ex = buildExports(cfg);
+  if (ex) pkg.exports = ex;
+
+  applyPrereqs(cfg, pkg);
+
+  const ap = cfg.autoprereqs;
+  if (ap && ap.enabled !== false) {
+    await applyAutoPrereqs(cfg, pkg);
+  }
+
+  if (cfg.repository) {
+    const info = await deriveRepoAndBugs({
+      repository: cfg.repository,
+      bugtracker: cfg.bugtracker ?? null,
+    });
+
+    pkg.repository = { type: cfg.repository.type ?? "git", url: `git+${info.remoteUrl ?? cfg.repository.url}` };
+    if (info.web) pkg.homepage = info.web;
+
+    if (cfg.bugtracker && info.bugsUrl) pkg.bugs = { url: info.bugsUrl };
+  }
+
+  // Fall back to cfg.bugtracker.url where needed
+  if (cfg.bugtracker && cfg.bugtracker.url) pkg.bugs = { url: cfg.bugtracker.url };
+
+  // cleanup empties
+  if (pkg.keywords && Array.isArray(pkg.keywords)) pkg.keywords = uniq(pkg.keywords);
+
+  const finalPkg = sortKeysDeep(pkg);
+
+  const outPath = `${outDir}/package.json`;
+  await fs.writeFile(outPath, JSON.stringify(finalPkg, null, 2) + "\n", "utf8");
+
+  if (msg) console.log("Generated package.json from dist.toml");
+}
+

package/lib/cmd/prereqs.mjs

@@ -0,0 +1,47 @@
+import { readDistToml } from "../config.mjs";
+import { applyPrereqs } from "../plugins/prereqs.mjs";
+import { applyAutoPrereqs } from "../plugins/autoprereqs.mjs";
+
+function sortedEntries(obj) {
+  return Object.entries(obj ?? {}).sort(([a], [b]) => a.localeCompare(b));
+}
+
+function printSection(title, obj) {
+  const entries = sortedEntries(obj);
+  if (!entries.length) return;
+  console.log(`${title}:`);
+  for (const [k, v] of entries) console.log(`  ${k}  ${v}`);
+  console.log("");
+}
+
+export async function runPrereqs(opts = {}) {
+  const { cfg } = await readDistToml("dist.toml");
+
+  // Build a pkg-like object using the same merge logic as pkg generation.
+  const pkg = {};
+  applyPrereqs(cfg, pkg);
+
+  // autoprereqs is opt-in by table presence, and enabled unless enabled=false
+  const ap = cfg.autoprereqs;
+  if (ap && ap.enabled !== false) {
+    await applyAutoPrereqs(cfg, pkg);
+  }
+
+  const out = {
+    engines: pkg.engines ?? {},
+    dependencies: pkg.dependencies ?? {},
+    devDependencies: pkg.devDependencies ?? {},
+    peerDependencies: pkg.peerDependencies ?? {},
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  printSection("Engines", out.engines);
+  printSection("Runtime dependencies", out.dependencies);
+  printSection("Dev dependencies", out.devDependencies);
+  printSection("Peer dependencies", out.peerDependencies);
+}
+