npm package: @stratware/updlog
Description: Monitor installed npm packages and report new versions with changelog embeds to Discord webhooks.
Author: Team Stratware
Latest version: 0.1.7

# 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:

```js
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:

```js
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:

```json
{
  "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