dev-dump 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,189 @@
+# dev-dump
+
+Flexible, semver-compliant snapshot & prerelease version generator.
+
+Generate deterministic, sortable prerelease versions for CI/CD pipelines, canary releases, feature branch deploys, and multi-stage release workflows — with zero dependencies.
+
+## Install
+
+```bash
+npm install -g dev-dump   # global
+npm install -D dev-dump   # devDependency
+npx dev-dump              # one-off
+```
+
+## Quick Start
+
+```bash
+# Default: {preid}.{timestamp}.{hash}
+npx dev-dump
+# → 1.2.3-dev.202603171950.abc1234
+
+# Alpha prerelease
+npx dev-dump -p alpha
+# → 1.2.3-alpha.202603171950.abc1234
+
+# Auto-increment from npm registry
+npx dev-dump -f "{preid}.{inc}" --from-registry
+# → 1.2.3-dev.0  (next time: dev.1, dev.2, …)
+
+# Canary release
+npx dev-dump -f "canary.{hash}"
+# → 1.2.3-canary.abc1234
+
+# Feature branch snapshot
+npx dev-dump -f "{branch}.{timestamp}.{hash}"
+# → 1.2.3-feat-login.202603171950.abc1234
+
+# Dry run (don't write package.json)
+npx dev-dump --dry-run
+
+# Capture for CI pipelines
+VERSION=$(npx dev-dump --stdout-only)
+echo "Publishing $VERSION"
+```
+
+## Template Variables
+
+The `-f` / `--format` flag defines the **prerelease** portion of the version. The base `MAJOR.MINOR.PATCH` is read from `package.json` (or overridden with `--base`).
+
+| Variable | Description | Example |
+|---|---|---|
+| `{preid}` | Prerelease identifier (`--preid`) | `dev`, `alpha`, `beta`, `rc` |
+| `{timestamp}` | `YYYYMMDDHHmm` | `202603171950` |
+| `{ts}` | `YYMMDDHHmm` | `2603171950` |
+| `{date}` | `YYYYMMDD` | `20260317` |
+| `{time}` | `HHmm` | `1950` |
+| `{hash}` | Git short hash (7 chars) | `abc1234` |
+| `{hash-long}` | Git full hash (40 chars) | `abc1234567890…` |
+| `{inc}` | Auto-increment counter (needs `--from-registry`) | `0`, `1`, `2` |
+| `{branch}` | Git branch name (sanitised) | `feat-login` |
+| `{base}` | `MAJOR.MINOR.PATCH` | `1.2.3` |
+
+## Options
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--preid <id>` | `-p` | `dev` | Prerelease identifier |
+| `--format <tpl>` | `-f` | `{preid}.{timestamp}.{hash}` | Prerelease template |
+| `--base <ver>` | `-b` | from `package.json` | Override base version |
+| `--from-registry` | `-r` | `false` | Resolve base / `{inc}` from npm registry |
+| `--tag <tag>` | `-t` | `latest` | dist-tag for `--from-registry` |
+| `--dry-run` | `-d` | `false` | Print version without writing files |
+| `--stdout-only` | `-s` | `false` | Only output version to stdout |
+| `--no-git-tag` | | `true` | Don't create a git tag |
+| `--cwd <path>` | | `.` | Working directory |
+| `--help` | `-h` | | Show help |
+| `--version` | `-v` | | Show tool version |
+
+## Common Recipes
+
+### CI/CD Snapshot (default)
+
+```bash
+npx dev-dump
+# 1.2.3-dev.202603171950.abc1234
+npm publish --tag dev
+```
+
+### Standard Prerelease Cycle
+
+```bash
+# alpha phase
+npx dev-dump -p alpha -f "{preid}.{inc}" -r
+# 1.2.3-alpha.0 → alpha.1 → alpha.2
+
+# beta phase
+npx dev-dump -p beta -f "{preid}.{inc}" -r
+# 1.2.3-beta.0 → beta.1
+
+# release candidate
+npx dev-dump -p rc -f "{preid}.{inc}" -r
+# 1.2.3-rc.0 → rc.1
+
+# final release
+npm version 1.2.3
+```
+
+### Feature Branch Deploy
+
+```bash
+npx dev-dump -f "{branch}.{timestamp}.{hash}"
+# 1.2.3-feat-login.202603171950.abc1234
+npm publish --tag "$(git branch --show-current | tr '/' '-')"
+```
+
+### Canary Release
+
+```bash
+npx dev-dump -f "canary.{hash}"
+# 1.2.3-canary.abc1234
+npm publish --tag canary
+```
+
+### Override Base for Next Major
+
+```bash
+npx dev-dump -b 2.0.0 -p alpha
+# 2.0.0-alpha.202603171950.abc1234
+```
+
+### GitHub Actions Example
+
+```yaml
+- name: Publish snapshot
+  run: |
+    VERSION=$(npx dev-dump --stdout-only)
+    npm version "$VERSION" --no-git-tag-version
+    npm publish --tag dev
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## SemVer Compliance
+
+All generated versions are fully compliant with [Semantic Versioning 2.0.0](https://semver.org/):
+
+- Prerelease identifiers use only `[0-9A-Za-z-]`
+- No leading zeros on numeric identifiers
+- Empty identifiers are automatically removed
+- Branch names and custom strings are sanitised (`/` `_` → `-`)
+- Versions are validated with a strict SemVer regex before output
+- Ordering is verified: timestamps naturally sort correctly, `{inc}` is monotonically increasing
+
+## Programmatic API
+
+```js
+const {
+  parseSemver,
+  isValidSemver,
+  semverCompare,
+  sanitise,
+  interpolate,
+  buildVariables,
+  resolveInc,
+  resolveBaseFromRegistry,
+} = require('dev-dump');
+
+// Parse
+parseSemver('1.2.3-dev.1');
+// → { major: 1, minor: 2, patch: 3, prerelease: 'dev.1', build: '', base: '1.2.3' }
+
+// Compare
+semverCompare('1.0.0-alpha', '1.0.0-beta'); // → -1
+
+// Sanitise branch names
+sanitise('feature/my_branch'); // → 'feature-my-branch'
+
+// Interpolate custom template
+interpolate('{preid}.{timestamp}', { preid: 'dev', timestamp: '202603171950' });
+// → 'dev.202603171950'
+```
+
+## Zero Dependencies
+
+This package has **no runtime dependencies**. It includes a built-in semver parser, comparator, and validator — everything needed in a single `index.js` file.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,529 @@
+#!/usr/bin/env node
+
+/**
+ * dev-dump
+ *
+ * A flexible CLI tool for generating semver-compliant snapshot / prerelease
+ * version strings.  Supports customisable templates with variables such as
+ * {preid}, {timestamp}, {hash}, {branch}, {inc} and more.
+ *
+ * Usage:
+ *   npx dev-dump [options]
+ *
+ * Options:
+ *   -p, --preid <id>        Prerelease identifier (default: "dev")
+ *   -f, --format <tpl>      Prerelease template  (default: "{preid}.{timestamp}.{hash}")
+ *   -b, --base <ver>        Override base MAJOR.MINOR.PATCH
+ *   -r, --from-registry     Resolve base / inc from the npm registry
+ *   -t, --tag <tag>         dist-tag used with --from-registry (default: "latest")
+ *   -d, --dry-run           Print the version without writing package.json
+ *   -s, --stdout-only       Only print the version string to stdout (implies --dry-run)
+ *       --no-git-tag        Skip creating a git tag (default: true)
+ *       --cwd <path>        Working directory (default: ".")
+ *   -h, --help              Show this help message
+ *   -v, --version           Show tool version
+ *
+ * Template variables:
+ *   {preid}      --preid value                         e.g. dev, alpha, beta
+ *   {timestamp}  YYYYMMDDHHmm                          e.g. 202603171950
+ *   {ts}         YYMMDDHHmm                            e.g. 2603171950
+ *   {date}       YYYYMMDD                              e.g. 20260317
+ *   {time}       HHmm                                  e.g. 1950
+ *   {hash}       git short hash (7)                    e.g. abc1234
+ *   {hash-long}  git full hash (40)                    e.g. abc1234...
+ *   {inc}        auto-increment (needs --from-registry or local scan)
+ *   {branch}     current git branch (sanitised)        e.g. feat-login
+ *   {base}       MAJOR.MINOR.PATCH                     e.g. 1.2.3
+ *
+ * @license MIT
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+
+// ────────────────────────────────────────────────────────────────────────────
+// Minimal semver helpers (no external dependency)
+// ────────────────────────────────────────────────────────────────────────────
+
+const SEMVER_RE =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[\da-zA-Z-]*[a-zA-Z-][\da-zA-Z-]*)(?:\.(?:0|[1-9]\d*|[\da-zA-Z-]*[a-zA-Z-][\da-zA-Z-]*))*))?(?:\+([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?$/;
+
+function parseSemver(v) {
+  const m = String(v).replace(/^[=v]+/, '').match(SEMVER_RE);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] || '',
+    build: m[5] || '',
+    base: `${m[1]}.${m[2]}.${m[3]}`,
+    raw: m[0],
+  };
+}
+
+function isValidSemver(v) {
+  return parseSemver(v) !== null;
+}
+
+/**
+ * Compare two semver strings.  Returns -1 | 0 | 1.
+ * Implements the full SemVer 2.0.0 precedence rules including prerelease.
+ */
+function semverCompare(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return 0;
+
+  // Compare MAJOR.MINOR.PATCH
+  for (const k of ['major', 'minor', 'patch']) {
+    if (pa[k] > pb[k]) return 1;
+    if (pa[k] < pb[k]) return -1;
+  }
+
+  // Both have no prerelease → equal
+  if (!pa.prerelease && !pb.prerelease) return 0;
+  // One has prerelease, the other doesn't → the one WITHOUT is greater
+  if (!pa.prerelease) return 1;
+  if (!pb.prerelease) return -1;
+
+  // Compare prerelease identifiers
+  const aParts = pa.prerelease.split('.');
+  const bParts = pb.prerelease.split('.');
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i++) {
+    if (i >= aParts.length) return -1; // fewer fields → lower
+    if (i >= bParts.length) return 1;
+    const ai = aParts[i];
+    const bi = bParts[i];
+    const aNum = /^\d+$/.test(ai);
+    const bNum = /^\d+$/.test(bi);
+    if (aNum && bNum) {
+      const diff = Number(ai) - Number(bi);
+      if (diff !== 0) return diff > 0 ? 1 : -1;
+    } else if (aNum) {
+      return -1; // numeric < alphanumeric
+    } else if (bNum) {
+      return 1;
+    } else {
+      if (ai > bi) return 1;
+      if (ai < bi) return -1;
+    }
+  }
+  return 0;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+function run(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, stdio: ['pipe', 'pipe', 'pipe'] })
+      .toString()
+      .trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Sanitise a string so that it only contains characters allowed by SemVer in
+ * prerelease identifiers: [0-9A-Za-z-].
+ */
+function sanitise(str) {
+  return str
+    .replace(/[^0-9A-Za-z-]+/g, '-') // replace illegal chars
+    .replace(/--+/g, '-')            // collapse repeated dashes
+    .replace(/^-|-$/g, '');           // trim leading/trailing dash
+}
+
+/**
+ * Remove leading zeros from a pure-numeric identifier (SemVer rule: numeric
+ * identifiers MUST NOT include leading zeroes).
+ * Non-numeric identifiers are returned as-is.
+ */
+function stripLeadingZero(id) {
+  if (/^\d+$/.test(id)) {
+    return String(Number(id));
+  }
+  return id;
+}
+
+/**
+ * Pad a number to `n` digits.
+ */
+const pad = (v, n = 2) => String(v).padStart(n, '0');
+
+/**
+ * Build a map of all template variables available for the current environment.
+ */
+function buildVariables(opts) {
+  const now = new Date();
+  const yyyy = now.getFullYear();
+  const MM   = pad(now.getMonth() + 1);
+  const dd   = pad(now.getDate());
+  const HH   = pad(now.getHours());
+  const mm   = pad(now.getMinutes());
+
+  const timestamp = `${yyyy}${MM}${dd}${HH}${mm}`;
+  const ts        = `${String(yyyy).slice(2)}${MM}${dd}${HH}${mm}`;
+  const date      = `${yyyy}${MM}${dd}`;
+  const time      = `${HH}${mm}`;
+
+  const hash     = run('git rev-parse --short HEAD', opts.cwd);
+  const hashLong = run('git rev-parse HEAD', opts.cwd);
+  const rawBranch = run('git rev-parse --abbrev-ref HEAD', opts.cwd);
+  const branch   = sanitise(rawBranch || 'unknown');
+
+  return {
+    preid: sanitise(opts.preid),
+    timestamp,
+    ts,
+    date,
+    time,
+    hash: hash || '0000000',
+    'hash-long': hashLong || '0'.repeat(40),
+    branch,
+    base: opts._resolvedBase || '0.0.0',
+    inc: String(opts._resolvedInc ?? 0),
+  };
+}
+
+/**
+ * Resolve {inc} by scanning the npm registry for existing versions that share
+ * the same base and preid pattern, then returning max + 1.
+ */
+function resolveInc(pkgName, base, preid, cwd) {
+  if (!pkgName) return 0;
+  const raw = run(`npm view ${pkgName} versions --json 2>/dev/null`, cwd);
+  if (!raw) return 0;
+
+  let versions;
+  try {
+    versions = JSON.parse(raw);
+  } catch {
+    return 0;
+  }
+  if (!Array.isArray(versions)) {
+    versions = [versions]; // single version comes as string
+  }
+
+  // Filter to versions whose base matches and prerelease starts with preid
+  const prefix = `${base}-${preid}.`;
+  let maxInc = -1;
+  for (const v of versions) {
+    if (!v.startsWith(prefix)) continue;
+    const rest = v.slice(prefix.length);
+    // Try to extract leading numeric inc value
+    const firstDotOrEnd = rest.indexOf('.');
+    const candidate = firstDotOrEnd === -1 ? rest : rest.slice(0, firstDotOrEnd);
+    if (/^\d+$/.test(candidate)) {
+      const n = Number(candidate);
+      if (n > maxInc) maxInc = n;
+    }
+  }
+  return maxInc + 1;
+}
+
+/**
+ * Resolve the base version from the npm registry when --from-registry is set.
+ */
+function resolveBaseFromRegistry(pkgName, tag, cwd) {
+  if (!pkgName) return null;
+  const v = run(
+    `npm view ${pkgName}@${tag} version 2>/dev/null`,
+    cwd,
+  );
+  if (v && isValidSemver(v)) {
+    return parseSemver(v).base;
+  }
+  return null;
+}
+
+/**
+ * Interpolate the format template with the variable map, then validate &
+ * clean each prerelease identifier.
+ */
+function interpolate(format, vars) {
+  let result = format.replace(/\{([^}]+)\}/g, (_, key) => {
+    const k = key.trim().toLowerCase();
+    if (vars.hasOwnProperty(k)) return vars[k];
+    // Unknown variable – leave as sanitised literal
+    return sanitise(key);
+  });
+
+  // Split into identifiers, sanitise each, drop empties
+  const ids = result.split('.').map(id => {
+    const s = sanitise(id);
+    return stripLeadingZero(s);
+  }).filter(Boolean);
+
+  return ids.join('.');
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// CLI argument parser
+// ────────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const opts = {
+    preid: 'dev',
+    format: '{preid}.{timestamp}.{hash}',
+    base: null,
+    fromRegistry: false,
+    tag: 'latest',
+    dryRun: false,
+    stdoutOnly: false,
+    noGitTag: true,
+    cwd: process.cwd(),
+    help: false,
+    showVersion: false,
+  };
+
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '-p': case '--preid':
+        opts.preid = args[++i] || 'dev';
+        break;
+      case '-f': case '--format':
+        opts.format = args[++i] || opts.format;
+        break;
+      case '-b': case '--base':
+        opts.base = args[++i] || null;
+        break;
+      case '-r': case '--from-registry':
+        opts.fromRegistry = true;
+        break;
+      case '-t': case '--tag':
+        opts.tag = args[++i] || 'latest';
+        break;
+      case '-d': case '--dry-run':
+        opts.dryRun = true;
+        break;
+      case '-s': case '--stdout-only':
+        opts.stdoutOnly = true;
+        opts.dryRun = true;
+        break;
+      case '--no-git-tag':
+        opts.noGitTag = true;
+        break;
+      case '--cwd':
+        opts.cwd = path.resolve(args[++i] || '.');
+        break;
+      case '-h': case '--help':
+        opts.help = true;
+        break;
+      case '-v': case '--version':
+        opts.showVersion = true;
+        break;
+      default:
+        // Positional: treat as preid shorthand
+        if (!a.startsWith('-')) {
+          opts.preid = a;
+        }
+        break;
+    }
+  }
+  return opts;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Help text
+// ────────────────────────────────────────────────────────────────────────────
+
+const HELP = `
+dev-dump — Flexible semver-compliant snapshot version generator
+
+Usage:
+  npx dev-dump [options] [preid]
+
+Options:
+  -p, --preid <id>        Prerelease identifier              (default: "dev")
+  -f, --format <tpl>      Prerelease template                (default: "{preid}.{timestamp}.{hash}")
+  -b, --base <ver>        Override base MAJOR.MINOR.PATCH
+  -r, --from-registry     Resolve base / inc from npm registry
+  -t, --tag <tag>         dist-tag for --from-registry       (default: "latest")
+  -d, --dry-run           Print version without modifying files
+  -s, --stdout-only       Only output the version string     (implies --dry-run)
+      --no-git-tag        Do not create a git tag            (default)
+      --cwd <path>        Working directory                  (default: ".")
+  -h, --help              Show this help message
+  -v, --version           Show tool version
+
+Template variables:
+  {preid}      Prerelease id              dev, alpha, beta, rc, canary
+  {timestamp}  YYYYMMDDHHmm              202603171950
+  {ts}         YYMMDDHHmm                2603171950
+  {date}       YYYYMMDD                  20260317
+  {time}       HHmm                      1950
+  {hash}       Git short hash (7)        abc1234
+  {hash-long}  Git full hash (40)        abc1234567890...
+  {inc}        Auto-increment counter    0, 1, 2, ...  (needs --from-registry)
+  {branch}     Git branch (sanitised)    feat-login
+  {base}       MAJOR.MINOR.PATCH         1.2.3
+
+Examples:
+  npx dev-dump                          # 1.2.3-dev.202603171950.abc1234
+  npx dev-dump -p alpha                 # 1.2.3-alpha.202603171950.abc1234
+  npx dev-dump -f "{preid}.{inc}" -r    # 1.2.3-dev.0  (auto-increment from registry)
+  npx dev-dump -f "{branch}.{ts}.{hash}" # 1.2.3-feat-login.2603171950.abc1234
+  npx dev-dump -f "canary.{hash}"       # 1.2.3-canary.abc1234
+  npx dev-dump -b 2.0.0 -p beta         # 2.0.0-beta.202603171950.abc1234
+  npx dev-dump --dry-run                # prints version without writing
+  npx dev-dump --stdout-only            # only outputs version string
+`.trim();
+
+// ────────────────────────────────────────────────────────────────────────────
+// Main
+// ────────────────────────────────────────────────────────────────────────────
+
+function main() {
+  const opts = parseArgs(process.argv);
+
+  // --help
+  if (opts.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  // --version
+  if (opts.showVersion) {
+    const self = path.join(__dirname, 'package.json');
+    if (fs.existsSync(self)) {
+      console.log(JSON.parse(fs.readFileSync(self, 'utf8')).version);
+    } else {
+      console.log('0.0.0');
+    }
+    process.exit(0);
+  }
+
+  // 1. Locate package.json
+  const pkgPath = path.resolve(opts.cwd, 'package.json');
+  let pkg = {};
+  let hasPkg = false;
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      hasPkg = true;
+    } catch (e) {
+      error(`Failed to parse ${pkgPath}: ${e.message}`);
+    }
+  }
+
+  // 2. Determine base version
+  let base;
+  if (opts.base) {
+    // User-supplied
+    const p = parseSemver(opts.base);
+    if (!p) error(`Invalid --base version: ${opts.base}`);
+    base = p.base;
+  } else if (opts.fromRegistry && pkg.name) {
+    const regBase = resolveBaseFromRegistry(pkg.name, opts.tag, opts.cwd);
+    if (regBase) {
+      base = regBase;
+      if (!opts.stdoutOnly) {
+        console.error(`ℹ  Base from registry (${opts.tag}): ${base}`);
+      }
+    }
+  }
+  if (!base && hasPkg && pkg.version) {
+    const p = parseSemver(pkg.version);
+    if (p) base = p.base;
+  }
+  if (!base) {
+    error(
+      'Could not determine base version. Provide --base, ensure package.json has a version, or use --from-registry.',
+    );
+  }
+  opts._resolvedBase = base;
+
+  // 3. Resolve {inc} if the template uses it
+  if (opts.format.includes('{inc}')) {
+    if (!pkg.name) {
+      error('{inc} requires a package name in package.json (or --from-registry).');
+    }
+    opts._resolvedInc = resolveInc(pkg.name, base, sanitise(opts.preid), opts.cwd);
+    if (!opts.stdoutOnly) {
+      console.error(`ℹ  Resolved {inc} = ${opts._resolvedInc}`);
+    }
+  }
+
+  // 4. Build variable map & interpolate
+  const vars = buildVariables(opts);
+  const prerelease = interpolate(opts.format, vars);
+
+  if (!prerelease) {
+    error('Template produced an empty prerelease string.');
+  }
+
+  const newVersion = `${base}-${prerelease}`;
+
+  // 5. Validate
+  if (!isValidSemver(newVersion)) {
+    error(`Generated version is not valid semver: ${newVersion}`);
+  }
+
+  // 6. Verify ordering: new version should be >= base-prerelease level
+  //    (this is a sanity check, not a hard gate)
+  if (hasPkg && pkg.version && isValidSemver(pkg.version)) {
+    if (semverCompare(newVersion, pkg.version) < 0) {
+      if (!opts.stdoutOnly) {
+        console.error(
+          `⚠  Warning: generated version ${newVersion} is lower than current ${pkg.version}`,
+        );
+      }
+    }
+  }
+
+  // 7. Output
+  if (opts.stdoutOnly) {
+    process.stdout.write(newVersion);
+    process.exit(0);
+  }
+
+  if (opts.dryRun) {
+    console.log(newVersion);
+    process.exit(0);
+  }
+
+  // Write to package.json
+  if (!hasPkg) {
+    error('No package.json found. Use --dry-run or --stdout-only.');
+  }
+
+  pkg.version = newVersion;
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  console.log(`✔  ${newVersion}`);
+}
+
+function error(msg) {
+  console.error(`✖  ${msg}`);
+  process.exit(1);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Export for programmatic use
+// ────────────────────────────────────────────────────────────────────────────
+
+module.exports = {
+  parseSemver,
+  isValidSemver,
+  semverCompare,
+  sanitise,
+  stripLeadingZero,
+  interpolate,
+  buildVariables,
+  resolveInc,
+  resolveBaseFromRegistry,
+};
+
+// Run when executed directly
+if (require.main === module) {
+  main();
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "dev-dump",
+  "version": "0.0.1",
+  "description": "Zero-dependency CLI tool to generate timestamp and git-hash based development versions",
+  "main": "index.js",
+  "bin": {
+    "dev-dump": "./index.js"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "semver",
+    "version",
+    "snapshot",
+    "prerelease",
+    "dev",
+    "alpha",
+    "beta",
+    "canary",
+    "ci",
+    "npm-version",
+    "git",
+    "hash",
+    "timestamp",
+    "bump"
+  ],
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gitaiQAQ/dev-dump.git"
+  },
+  "author": "gitaiQAQ",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}