updlog

Author: Team Stratware

What is updlog?

updlog is a lightweight utility and library for detecting package version changes, reading per-package update manifests, and reporting update entries (for example, as Discord embeds via a webhook).

It expects packages to include an updates/ directory containing JSON files named by version (e.g. 1.2.0.json). When a package's version advances, updlog reads all new entries between the recorded version and the current version and dispatches them in order.

Common flags:

• --packages – comma-separated package names to check.
• --packagesFile – path to a file listing packages (one per line; # lines are ignored).
• --packagesDir – comma-separated directories to scan for package.json files (e.g. --packagesDir packages,src/stratware); packages that are only present in your workspace are referenced via relative paths so Node can still resolve them.
• --webhook – Discord webhook URL to post embeds. If omitted, updlog runs in dry-run mode and prints payloads.
• --stateFile – path to the JSON state file (defaults to .updlog-state.json).
• --generate – when no updates/<version>.json exists for a detected version, create a scaffold file.
• --markdown – path to a Markdown file that should receive every dispatched update as a human-friendly snapshot.
• --quiet – reduce logging output.

Using updlog programmatically

@stratware/updlog exports both a ready-to-use singleton UpdLog and the UpdLogRuntime class. Most scripts can import the singleton, hook into events, and call init/run once:

const { UpdLog, Blueprint } = require('@stratware/updlog')

UpdLog.on('setup', ({ packages, dryRun }) => console.log('watching', packages, '(dry run?', dryRun, ')'))

UpdLog.init({
  packages: '@stratware/pathify',
  generate: true,
  webhook: process.env.UPDLOG_WEBHOOK,
  blueprint: (info, entry, BP = Blueprint) =>
    new BP()
      .Title(`${info.name} v${entry.version}`)
      .Description(entry.summary)
      .Color(0xff3366)
      .section('Highlights', entry.features)
      .section('Fixes', entry.fixes)
})

;(async () => {
  try {
    await UpdLog.run()
  } catch (error) {
    console.error(error)
    process.exitCode = 1
  }
})()

If you need multiple isolated runners (e.g., different option sets in the same process), instantiate UpdLogRuntime directly instead of using the singleton:

const { UpdLogRuntime } = require('@stratware/updlog')
const runner = new UpdLogRuntime()
runner.init({ root: process.cwd(), packages: 'pkg-a,pkg-b' })
await runner.run(['pkg-a'])

Important init options:

• root – base path for package resolution.
• stateFile – custom path for the .updlog-state.json file.
• packageList / packages / packagesFile – ways to specify target packages.
• packagesDir – auto-discover packages by scanning directories that contain package.json files (workspace-only packages are referenced via relative paths so they don't need to exist in node_modules).
• webhook – webhook URL (or null for dry-run).
• dryRun – force dry-run behavior.
• quiet – suppress normal logging.
• blueprint – optional function (info, entry, BlueprintClass) => customEmbedOrBlueprint to customize embed building.
• generate – boolean to create missing update templates automatically.
• markdown – optional path to append Markdown snapshots for every dispatched update (helpful for release notes or email digests).

Events emitted by UpdLogRuntime (useful for monitoring):

• setup – emitted after init completes.
• package:detected, package:unchanged, package:missing, package:recorded.
• dispatch, dispatch:success, dispatch:error.
• updates:generated – when a scaffold was written by the --generate flow.
• markdown:written – emitted when a Markdown snapshot is appended via the markdown option.

Update file schema

Place versioned JSON files under updates/. Minimal example:

{
  "version": "1.2.0",
  "summary": "Short summary line",
  "link": "https://github.com/owner/repo/releases/tag/v1.2.0",
  "features": ["New API foo", "Performance improvements"],
  "fixes": ["Fix crash on startup"],
  "breaking": ["Changed behavior of X"],
  "notes": ["Additional notes or migration steps"]
}

Fields are optional; Blueprint maps features, fixes, breaking, and notes into embed sections.

Recommended workflow

• Commit updates/<version>.json files alongside release commits so updlog has authoritative changelogs to report.
• Use --generate in release CI to scaffold missing entries; maintainers can fill them during review.
• Persist .updlog-state.json between runs (CI artifact or commit) so updlog only reports new versions.

Markdown snapshots

Pass --markdown releases.md (or set markdown in code) to mirror every dispatched update into a Markdown changelog. This is handy for email digests, release PRs, or docs sites that want the same content that went to Discord. updlog appends sections in the order they were reported, so you can pipe the resulting file into newsletters or include it in CI artifacts.

npm/registry fallback

By default, updlog only dispatches entries present in updates/. If packages do not provide these files, you can implement an optional fallback to query the npm registry or fetch CHANGELOGs from the repository. This approach is best-effort and may be inconsistent.

License

MIT