backlogsync 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to backlogsync. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/). Items reference their `BS-n` backlog id.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-10-01
+
+The first version on npm: 0.0.1's tool, unchanged in behaviour, published once one
+repository had been migrated and its sync observed on GitHub.
+
+### Added
+- The 0.1.0 gate is met: skilltrigger migrated with the action pinned by commit, and its
+  first sync on GitHub created the one issue the dry run had planned and touched nothing
+  else (BS-10, BS-15).
+
+### Changed
+- The README documents running a pinned commit locally through the GitHub tarball, since
+  `npx github:…` fails inside npm (BS-19).
+- The README installs from npm and pins the action by its release tag,
+  `@backlogsync--v0.1.0`, or by commit; the tarball route stays for a commit that is not
+  released. CONTRIBUTING gives the first release's order: publish by hand, configure the
+  trusted publisher, push the tag (BS-9).
+
+## [0.0.1] — 2026-10-01 — not released
+
+The first version, in the repository only: the tool that replaces the `scripts/backlog.mjs`
+seven repositories each carried, its tests against a fake GitHub API, and this
+repository. The first version on npm is 0.1.0, after one repository has been migrated
+and its sync observed on GitHub (BS-10).
+
+### Added
+- `backlogsync check`: the backlog validated — ids well-formed and unique, metadata that
+  parses and holds known values, items under versioned milestones — and the roadmap
+  compared with what the backlog generates; exit 1 on either (BS-1, BS-2).
+- `backlogsync roadmap`: `ROADMAP.md` in the layout the replaced copies produced, byte
+  for byte given the same name and regenerate command (BS-2).
+- `backlogsync sync`: the one-way sync to issues and milestones over the GitHub REST
+  API, from `GITHUB_TOKEN` and `GITHUB_REPOSITORY`; `--dry-run` and `--milestones`; no
+  delete call; a pagination link to another origin refused (BS-3).
+- Configuration in `package.json#backlogsync` or `.backlogsync.json`: `prefix`, `meta`,
+  `name`, `labels`, `backlog`, `roadmap`, `branch`, `regenerate` (BS-4).
+- A composite action, `uses: Allan-Nava/backlogsync@<ref>`, and `release-drift.yml` as a
+  reusable workflow (BS-5).
+- `scripts/compat.mjs`: the roadmap and the sync plan compared with a repository's own
+  script, on its real backlog and issues (BS-7).
+
+### Changed
+- Against the replaced copies: the sync applies by default and `--dry-run` plans;
+  `lint` and `check` are one command; labels are ensured only when an issue is created;
+  the lint also refuses an item under another prefix, an item ticked `[X]`, a repeated
+  milestone title and a `prio-` label listed by hand (BS-1, BS-3).
+
+### Fixed
+- The "Source of trutm" and "Source of trugl" artefacts two copies wrote into issue
+  footers and milestone descriptions (BS-3).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allan Nava
+
+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,159 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/Allan-Nava/backlogsync/main/assets/logo.svg" width="72" height="72" alt=""></p>
 
-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.
+# backlogsync — one backlog file, a generated roadmap, issues that follow
+
+**backlogsync keeps `BACKLOG.md` the single source of truth for planned work**: it checks the file, generates `ROADMAP.md` from it, and syncs GitHub issues and milestones one way — from the file to GitHub, never back. A Node CLI with zero runtime dependencies, and a composite GitHub Action that runs the same code.
+
+**Status:** 0.1.0, the first version on npm. It replaces the `scripts/backlog.mjs` that seven repositories each carried, and on 2026-10-01 it reproduced every one of their committed roadmaps byte for byte and planned the same sync, decision for decision, on their real issues (see [Compatibility](#compatibility)). The gate on 0.1.0 — one of those repositories migrated and its sync observed on GitHub — was met the same day by skilltrigger.
+
+## What it does
+
+- **`backlogsync check`** — validates the backlog (ids well-formed and unique, metadata that parses and holds known values, every item under a milestone) and fails when `ROADMAP.md` is not what the backlog would generate. The CI gate.
+- **`backlogsync roadmap`** — writes `ROADMAP.md`: a summary line, a table of milestones with progress bars, then every item by milestone.
+- **`backlogsync sync`** — plans the issue sync, prints the whole plan, then applies it over the GitHub REST API: create the issue for an open item, close it when the item is ticked, reopen it when the item is unticked, retitle it when the title drifts, move it when the item moves to another milestone. `--dry-run` prints the plan and changes nothing.
+
+The sync **never deletes**. There is no delete call in the code. An issue whose item has left the backlog is left alone; so is an issue filed by hand, a pull request, and an issue with another prefix.
+
+## Install
+
+Node 18 or later. No runtime dependencies, no build step, no install script.
+
+**From npm**: `npx backlogsync check`, or `npm install --save-dev backlogsync` and `npx backlogsync check` from then on.
+
+**As a GitHub Action**, pinned by release tag or by commit — `.github/workflows/backlog-issues.yml`:
+
+```yaml
+name: Backlog issues
+on:
+  push:
+    branches: [main]
+    paths: [BACKLOG.md, .github/workflows/backlog-issues.yml]
+  workflow_dispatch:
+permissions:
+  contents: read
+  issues: write
+concurrency:
+  group: backlog-issues
+  cancel-in-progress: false
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: Allan-Nava/backlogsync@backlogsync--v0.1.0   # or @<sha>
+        with:
+          command: sync        # or check, roadmap
+          # dry-run: "true"
+          # milestones: v0.1.0,v0.2.0
+```
+
+The `concurrency` group matters: two runs racing would both see no issue for an item and open it twice. The action's inputs are `command`, `dry-run`, `milestones`, `config`, `working-directory` and `token` (default: the job's `GITHUB_TOKEN`). It runs `node "$GITHUB_ACTION_PATH/bin/backlogsync.mjs"` with the runner's Node.
+
+**From a commit**, the pre-release route: for a repository that pins the action to a commit not yet released on npm and wants the same version locally — the GitHub tarball, because `npx github:Allan-Nava/backlogsync#<sha>` fails inside npm ("GitFetcher requires an Arborist constructor"):
+
+```bash
+npx --yes https://codeload.github.com/Allan-Nava/backlogsync/tar.gz/<sha> check
+```
+
+skilltrigger's `npm run backlog` and `npm run roadmap`, from the 0.1.0 pilot, do exactly this.
+
+**From a checkout**: `node <checkout>/bin/backlogsync.mjs check`, run in the repository that holds the backlog.
+
+## The backlog
+
+````markdown
+## v0.2.0 — Title of the milestone <!-- ms: phase=next -->
+
+- [ ] **ST-12 — Short name**: what it is, why it earns its place, what it
+  needs to touch. <!-- st: prio=high size=M labels=runner,docs -->
+- [x] **ST-11 — Shipped item**: … <!-- st: prio=med size=S labels=docs ver=0.1.0 -->
+````
+
+- A **milestone** is a `## ` heading that starts with `vX.Y.Z` and carries `<!-- ms: phase=… -->`, phase one of `now`, `next`, `later`, `shipped`. Any other `## ` heading ends the milestone above it.
+- An **item** is `- [ ] **<PREFIX>-n — Title**: body` and its indented continuation lines, ending with the metadata comment, whose key is the configured `meta` (here `st`). `prio` is `high`, `med` or `low`; `size` is `S`, `M`, `L` or `XL`; `labels` is a comma-separated list, at least one.
+- `- [x]` marks it shipped, and a shipped item carries `ver=x.y.z` (or `ver=main` while merged and unreleased); an open item carries no `ver`.
+- The **id never changes**. A new item takes the next free number.
+- Fenced blocks are skipped whole, so the file can document its own format, as above.
+
+The issue for an item is titled `<id> — <title>`; that prefix is the only link between the two, so the title is the one thing the sync rewrites. The body is the item's text with every HTML comment stripped, followed by a footer naming the backlog. It is written once, at creation.
+
+## Configuration
+
+In `package.json` under `"backlogsync"`, or in `.backlogsync.json` — which is all a repository without a `package.json`, a Go module say, needs. Both at once is an error rather than a precedence rule: a repository that carries two has already drifted. `--config <file>` names any other file.
+
+```json
+{
+  "prefix": "ST",
+  "meta": "st",
+  "name": "skilltrigger",
+  "labels": {
+    "runner": { "color": "0e8a16", "description": "The serial runner" },
+    "docs": ["0075ca", "README, CONTRIBUTING, site"]
+  }
+}
+```
+
+| Key | Default | What it is |
+|---|---|---|
+| `prefix` | — (required) | The id prefix: `ST` for `ST-1`. Upper-case letters and digits. |
+| `meta` | the prefix, lower-cased | The metadata comment's key: `<!-- st: … -->`. |
+| `name` | `package.json#name`, else the directory | The roadmap's title: `# Roadmap — <name>`. |
+| `labels` | none: any label passes | Name → `{color, description}` (or `[color, description]`, the shape the replaced scripts used). When set, an item may only use these; the sync creates any that are missing. |
+| `backlog`, `roadmap` | `BACKLOG.md`, `ROADMAP.md` | Paths, relative to the config's directory. |
+| `branch` | `main` | The branch the issue footer links to. |
+| `regenerate` | `npx backlogsync roadmap` | The command the roadmap and the stale-roadmap error tell a reader to run. The generated-by comment prints it without its leading `node` or `npx`. |
+
+The sync takes `GITHUB_TOKEN` (or `GH_TOKEN`) and `GITHUB_REPOSITORY` from the environment, plus `GITHUB_API_URL` and `GITHUB_SERVER_URL` when set — Actions sets all four. A dry run on a public repository works without a token. Labels `prio-high`, `prio-med` and `prio-low` are added to every new issue from its `prio=`; a `labels` entry of the same name overrides one's colour.
+
+Exit codes: `0` ok, `1` a problem in the backlog, a stale roadmap or a failed API call, `2` a usage or configuration error.
+
+## Release drift
+
+`.github/workflows/release-drift.yml` is also a reusable workflow: it fails when the version in the manifest has had no matching tag for two hours, because a merged release PR publishes nothing until someone pushes the tag. It runs on push and daily.
+
+```yaml
+jobs:
+  drift:
+    uses: Allan-Nava/backlogsync/.github/workflows/release-drift.yml@backlogsync--v0.1.0   # or @<sha>
+    with:
+      version-file: VERSION   # default package.json
+      tag-prefix: v           # default <package name>--v, or v for a plain file
+```
+
+`grace-hours` (default 2) and `changelog` (default `CHANGELOG.md`) are the other inputs. A version whose CHANGELOG heading says `not released`, or whose section opens with `Not released`, passes with a notice.
+
+## Decisions
+
+The seven copies agreed on the format, the lint rules, the roadmap layout and the planner; they differed in what each hard-coded. Each difference is either a key above or one choice, recorded here.
+
+- **Prefix, meta key, roadmap name, label set** — different in every copy; `prefix`, `meta`, `name` and `labels`. The owner and repository came from a hard-coded URL; they now come from `GITHUB_REPOSITORY`.
+- **The `prio-med` colour** — `fbca04` in six copies, `e4b429` in one. The default is the majority's; a `labels` entry overrides it. Existing labels are never recoloured.
+- **"Source of trutm" and "Source of trugl"** — two copies carried a find-and-replace artefact in the issue footer and the milestone description. Fixed, not reproduced. Bodies and descriptions are written only on creation, so issues that already exist are not touched by it.
+- **The release-drift marker** — one copy read `not released` on the CHANGELOG heading, one read a section opening with `Not released`, five read neither. The reusable workflow accepts both. One of the five has a section that opens with `Not released` and would fail daily once its grace window passed; the reusable workflow passes it.
+- **Version file and tag shape** — `package.json` with `<name>--v<version>` in five, a `VERSION` file with `v<version>` in two: the `version-file` and `tag-prefix` inputs. The remediation hint is a plain `git tag … && git push …` for all.
+- **Fixed, not configurable:** the `prio`, `size` and `phase` vocabularies and the `vX.Y.Z` milestone headings — identical in all seven, so a key would only invite drift.
+
+Changed on purpose, and the same in every repository from now on:
+
+- The sync calls the REST API itself rather than the `gh` CLI, and applies by default; `--dry-run` replaces the old `issues` / `issues --apply` pair. `lint` and `check` are one command, `check`; the old `stats` line is the roadmap's summary line.
+- Labels are ensured only when an issue is about to be created, not on every run.
+- The close and reopen comments and the issue footer name backlogsync rather than a script path.
+- The lint is stricter in four ways the copies let pass silently: an item under another prefix, an item ticked `[X]`, two milestone headings with one title (the sync finds a milestone by title), and a `prio-` label listed by hand. None of the seven real backlogs trips them.
+
+## Compatibility
+
+`node scripts/compat.mjs <repo> … [--issues]` runs over checkouts of repositories that still carry their own `scripts/backlog.mjs`. It derives the config from that script, runs `backlogsync roadmap` over the repository's `BACKLOG.md` into a temporary directory and compares the result with its committed `ROADMAP.md` byte for byte; runs `backlogsync check`; and, with `--issues`, reads the issues with `gh issue list` and compares the new planner's decisions with the old script's on that same list. It writes nothing outside the temporary directory, and nothing it reads belongs in this repository.
+
+On 2026-10-01, over the seven repositories: seven roadmaps byte-identical (1,905 to 4,448 bytes), seven checks passing, seven plans identical (17 to 40 decisions each, 118 issues read, none with anything left to change).
+
+## What it never does
+
+- Delete an issue, a milestone or a label.
+- Write to the repository. `roadmap` writes one file locally; committing it is yours.
+- Read anything back from GitHub into the backlog. The sync is one way.
+- Send the token anywhere but the configured API origin: a pagination link to another origin is refused.
+- Run on install. There is no install script, and no dependency.
+
+## License
+
+MIT

package/action.yml

@@ -0,0 +1,65 @@
+name: backlogsync
+description: BACKLOG.md as the single source of truth — check it, generate ROADMAP.md, sync GitHub issues and milestones one way.
+author: Allan Nava
+branding:
+  icon: list
+  color: orange
+
+# A composite action, so a repository can adopt backlogsync by ref before any npm
+# release exists: it runs the CLI from this checkout of the action, with the
+# runner's own Node (18 or later — every GitHub-hosted image has one; add
+# actions/setup-node before this step on a runner that does not).
+#
+# Inputs reach the shell as environment variables, never interpolated into the
+# script, so a milestone list cannot become a command.
+
+inputs:
+  command:
+    description: "check, roadmap or sync"
+    required: false
+    default: sync
+  dry-run:
+    description: "sync only: print the plan, change nothing"
+    required: false
+    default: "false"
+  milestones:
+    description: "sync only: limit to these milestones by version, comma-separated (e.g. v0.1.0). Empty means all."
+    required: false
+    default: ""
+  config:
+    description: "A config file instead of .backlogsync.json / package.json#backlogsync"
+    required: false
+    default: ""
+  working-directory:
+    description: "The repository directory, relative to the workspace"
+    required: false
+    default: "."
+  token:
+    description: "The token the sync uses; it needs issues: write. The default is the job's GITHUB_TOKEN."
+    required: false
+    default: ${{ github.token }}
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        BS_COMMAND: ${{ inputs.command }}
+        BS_DRY_RUN: ${{ inputs.dry-run }}
+        BS_MILESTONES: ${{ inputs.milestones }}
+        BS_CONFIG: ${{ inputs.config }}
+        GITHUB_TOKEN: ${{ inputs.token }}
+      run: |
+        set -euo pipefail
+        case "$BS_COMMAND" in
+          check|roadmap|sync) ;;
+          *) echo "::error::command must be check, roadmap or sync, got: $BS_COMMAND"; exit 2 ;;
+        esac
+        args=("$BS_COMMAND")
+        if [ -n "$BS_CONFIG" ]; then args+=(--config "$BS_CONFIG"); fi
+        if [ "$BS_COMMAND" = sync ]; then
+          if [ "$BS_DRY_RUN" = true ]; then args+=(--dry-run); fi
+          if [ -n "$BS_MILESTONES" ]; then args+=(--milestones "$BS_MILESTONES"); fi
+        fi
+        node "$GITHUB_ACTION_PATH/bin/backlogsync.mjs" "${args[@]}"

package/bin/backlogsync.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// backlogsync — BACKLOG.md as the single source of truth: a generated ROADMAP.md and a
+// one-way sync to GitHub issues and milestones.
+//
+//   backlogsync roadmap      write ROADMAP.md from BACKLOG.md
+//   backlogsync check        validate BACKLOG.md and fail if ROADMAP.md is stale
+//   backlogsync sync         sync the issues and milestones (GITHUB_TOKEN, GITHUB_REPOSITORY)
+//     --dry-run              print the plan, change nothing
+//     --milestones v0.1.0,…  limit to these milestones, by version
+//
+// Options for every command:
+//   --config <file>          a config file instead of .backlogsync.json / package.json
+//   --backlog <file>         read this backlog instead of the configured one
+//   --roadmap <file>         write or compare this roadmap instead of the configured one
+//
+// Exit codes: 0 ok, 1 a problem found (or a failed API call), 2 usage or configuration.
+import { appendFileSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from './lib/args.mjs'
+import { lint, parse, roadmap } from './lib/backlog.mjs'
+import { ConfigError, loadConfig } from './lib/config.mjs'
+import { client, GitHubError } from './lib/github.mjs'
+import { sync } from './lib/sync.mjs'
+
+const SELF = fileURLToPath(import.meta.url)
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+const usage = () =>
+  readFileSync(SELF, 'utf8')
+    .split('\n')
+    .slice(1, 16)
+    .map((l) => l.replace(/^\/\/ ?/, ''))
+    .join('\n')
+
+class UsageError extends Error {}
+
+export async function main(argv = process.argv.slice(2), env = process.env, out = console.log, errOut = console.error) {
+  const [cmd, ...rest] = argv
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    out(usage())
+    return 0
+  }
+  if (cmd === '--version' || cmd === '-v') {
+    out(VERSION)
+    return 0
+  }
+  try {
+    if (!['roadmap', 'check', 'sync'].includes(cmd)) throw new UsageError(`unknown command "${cmd}" — try roadmap, check or sync`)
+    const spec = { config: 'string', backlog: 'string', roadmap: 'string' }
+    if (cmd === 'sync') Object.assign(spec, { 'dry-run': 'boolean', milestones: 'string' })
+    let args
+    try {
+      args = parseArgs(rest, spec)
+    } catch (e) {
+      throw new UsageError(e.message)
+    }
+    if (args.positionals.length) throw new UsageError(`unexpected argument "${args.positionals[0]}"`)
+    const cfg = loadConfig({ configPath: args.values.config })
+    if (args.values.backlog) cfg.backlog = resolve(args.values.backlog)
+    if (args.values.roadmap) cfg.roadmap = resolve(args.values.roadmap)
+
+    let text
+    try {
+      text = readFileSync(cfg.backlog, 'utf8')
+    } catch {
+      throw new ConfigError(`cannot read the backlog at ${args.values.backlog ?? cfg.backlogRel}`)
+    }
+    const model = parse(text, cfg)
+    const errors = lint(model, cfg)
+    if (errors.length) {
+      for (const e of errors) errOut(e)
+      errOut(`${errors.length} problem${errors.length === 1 ? '' : 's'} in ${cfg.backlogRel}`)
+      return 1
+    }
+
+    if (cmd === 'roadmap') {
+      writeFileSync(cfg.roadmap, roadmap(model, cfg))
+      out(`wrote ${args.values.roadmap ?? cfg.roadmapRel} — ${model.items.length} items, ${model.milestones.length} milestones`)
+      return 0
+    }
+
+    if (cmd === 'check') {
+      let current = null
+      try {
+        current = readFileSync(cfg.roadmap, 'utf8')
+      } catch {}
+      if (current !== roadmap(model, cfg)) {
+        errOut(`${cfg.roadmapRel} is ${current === null ? 'missing' : 'stale'} — run \`${cfg.regenerate}\` and commit the result`)
+        return 1
+      }
+      out(`ok — ${model.items.length} items, ${model.milestones.length} milestones; ${cfg.roadmapRel} is in step with ${cfg.backlogRel}`)
+      return 0
+    }
+
+    // sync
+    const dryRun = Boolean(args.values['dry-run'])
+    const token = env.GITHUB_TOKEN || env.GH_TOKEN || ''
+    if (!token && !dryRun) throw new ConfigError('GITHUB_TOKEN is not set — a sync that changes issues needs one (--dry-run can do without on a public repository)')
+    let gh
+    try {
+      gh = client({ token, repo: env.GITHUB_REPOSITORY, apiUrl: env.GITHUB_API_URL || undefined, userAgent: `backlogsync/${VERSION}` })
+    } catch (e) {
+      throw new ConfigError(e.message)
+    }
+    const only = (args.values.milestones ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+    const res = await sync(model, cfg, gh, { dryRun, only, server: env.GITHUB_SERVER_URL || undefined, log: out })
+    if (env.GITHUB_STEP_SUMMARY) {
+      try {
+        appendFileSync(env.GITHUB_STEP_SUMMARY, `### Backlog issue sync${dryRun ? ' — dry run' : ''}\n\n\`\`\`\n${res.summary}\n\`\`\`\n`)
+      } catch {}
+    }
+    return 0
+  } catch (e) {
+    if (e instanceof UsageError || e instanceof ConfigError) {
+      errOut(`backlogsync: ${e.message}`)
+      if (e instanceof UsageError) errOut('run `backlogsync help` for usage')
+      return 2
+    }
+    if (e instanceof GitHubError) {
+      errOut(`backlogsync: ${e.message}`)
+      return 1
+    }
+    throw e
+  }
+}
+
+// Through npm's bin symlink argv[1] is the link, not this file.
+const invoked = (() => {
+  try {
+    return process.argv[1] && realpathSync(process.argv[1]) === realpathSync(SELF)
+  } catch {
+    return false
+  }
+})()
+if (invoked) {
+  main().then((code) => {
+    process.exitCode = code
+  })
+}

package/bin/lib/args.mjs

@@ -0,0 +1,30 @@
+// A small argument parser: util.parseArgs arrived in Node 18.3 and the floor is 18.0.
+// `spec` maps a long option to 'boolean' or 'string'; anything else is an error.
+export function parseArgs(argv, spec) {
+  const values = {}
+  const positionals = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--') {
+      positionals.push(...argv.slice(i + 1))
+      break
+    }
+    if (!a.startsWith('--')) {
+      positionals.push(a)
+      continue
+    }
+    const eq = a.indexOf('=')
+    const name = a.slice(2, eq < 0 ? undefined : eq)
+    const type = spec[name]
+    if (!type) throw new Error(`unknown option --${name}`)
+    if (type === 'boolean') {
+      if (eq >= 0) throw new Error(`--${name} takes no value`)
+      values[name] = true
+    } else {
+      const v = eq >= 0 ? a.slice(eq + 1) : argv[++i]
+      if (v === undefined || (eq < 0 && v.startsWith('--'))) throw new Error(`--${name} needs a value`)
+      values[name] = v
+    }
+  }
+  return { values, positionals }
+}

package/bin/lib/backlog.mjs

@@ -0,0 +1,183 @@
+// BACKLOG.md, read and checked. Pure functions: text and config in, a model or a list
+// of errors out. No filesystem, no network — the CLI and the sync pass the text in.
+import { PHASES, PRIOS, SIZES } from './config.mjs'
+
+export const DASH = ' — '
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+// `<!-- tag: k=v k=v -->` → { k: v }; null when the comment is absent. A value may
+// itself carry `=`; only the first one splits.
+export function meta(s, tag) {
+  const m = s.match(new RegExp(`<!--\\s*${esc(tag)}:([\\s\\S]*?)-->`))
+  if (!m) return null
+  const out = {}
+  for (const kv of m[1].trim().split(/\s+/).filter(Boolean)) {
+    const [k, ...v] = kv.split('=')
+    out[k] = v.join('=')
+  }
+  return out
+}
+
+// Strip every HTML comment, including an unterminated one, so nothing that reads as
+// markup survives into an issue body. Loop: one pass can leave a `<!--` behind.
+export function stripComments(s) {
+  let body = s
+  for (let prev = null; prev !== body; ) {
+    prev = body
+    body = body.replace(/<!--[\s\S]*?(?:-->|$)/g, '')
+  }
+  return body.trim()
+}
+
+// → { milestones: [{ line, title, version, phase, items }], items: [...], errors }
+//
+// A milestone is a `## ` heading carrying `<!-- ms: phase=… -->`; any other `## `
+// heading ends the current milestone. An item is `- [ ] **XX-n — Title**: body` and
+// its indented continuation lines; fenced blocks are skipped whole.
+export function parse(text, cfg) {
+  const { prefix, meta: tag } = cfg
+  const file = cfg.backlogRel ?? 'BACKLOG.md'
+  const errors = []
+  const err = (line, msg) => errors.push(`${file}:${line}: ${msg}`)
+  const milestones = []
+  const items = []
+  const itemRe = new RegExp(`^- \\[( |x)\\] \\*\\*(${esc(prefix)}-(\\d+))\\s+—\\s+(.+?)\\*\\*:?\\s*([\\s\\S]*)$`)
+  const startRe = new RegExp(`^- \\[[ x]\\] \\*\\*${esc(prefix)}-`)
+  // An item line under another prefix is a typo that would otherwise vanish silently.
+  const foreignRe = /^- \[[ xX]\] \*\*([A-Z][A-Z0-9]*)-\d+/
+  let ms = null
+  let fenced = false
+  let cur = null
+
+  const flush = () => {
+    if (!cur) return
+    const raw = cur.lines.join(' ').replace(/\s+/g, ' ').trim()
+    const m = raw.match(itemRe)
+    if (!m) err(cur.line, `item does not match \`- [ ] **${prefix}-n — Title**: body <!-- ${tag}: ... -->\``)
+    else {
+      items.push({
+        line: cur.line,
+        status: m[1] === 'x' ? 'shipped' : 'open',
+        id: m[2],
+        num: Number(m[3]),
+        title: m[4].trim(),
+        body: stripComments(m[5]),
+        meta: meta(raw, tag),
+        ms,
+      })
+    }
+    cur = null
+  }
+
+  text.split('\n').forEach((line, i) => {
+    const n = i + 1
+    if (line.startsWith('```')) {
+      fenced = !fenced
+      flush()
+      return
+    }
+    if (fenced) return
+    const h = line.match(/^## (.+?)\s*(<!--[\s\S]*-->)?\s*$/)
+    if (h) {
+      flush()
+      const mm = meta(line, 'ms')
+      if (mm) {
+        const title = h[1].trim()
+        const version = title.match(/^(v\d+\.\d+\.\d+)\b/)?.[1] ?? null
+        ms = { line: n, title, version, phase: mm.phase ?? null, items: [] }
+        milestones.push(ms)
+      } else ms = null
+      return
+    }
+    if (startRe.test(line)) {
+      flush()
+      cur = { line: n, lines: [line] }
+      return
+    }
+    const f = line.match(foreignRe)
+    if (f && f[1] !== prefix) err(n, `item id prefix "${f[1]}" is not the configured "${prefix}"`)
+    else if (/^- \[X\] \*\*/.test(line)) err(n, 'use a lower-case [x] to tick an item')
+    if (cur && /^\s+\S/.test(line)) {
+      cur.lines.push(line.trim())
+      return
+    }
+    flush()
+  })
+  flush()
+
+  for (const it of items) if (it.ms) it.ms.items.push(it)
+  return { milestones, items, errors }
+}
+
+// → ["BACKLOG.md:<line>: <problem>"]; empty when the backlog is sound.
+export function lint(model, cfg) {
+  const file = cfg.backlogRel ?? 'BACKLOG.md'
+  const errors = [...model.errors]
+  const err = (line, msg) => errors.push(`${file}:${line}: ${msg}`)
+  const seen = new Map()
+  const titles = new Map()
+  for (const m of model.milestones) {
+    if (!m.version) err(m.line, `milestone heading must start with a version, vX.Y.Z — Theme: "${m.title}"`)
+    if (!PHASES.includes(m.phase)) err(m.line, `milestone phase must be one of ${PHASES.join('|')}, got "${m.phase}"`)
+    // The sync finds a milestone by its title; two headings with one title are one milestone.
+    if (titles.has(m.title)) err(m.line, `milestone "${m.title}" is already a heading on line ${titles.get(m.title)}`)
+    titles.set(m.title, m.line)
+  }
+  for (const it of model.items) {
+    if (seen.has(it.id)) err(it.line, `${it.id} is already used on line ${seen.get(it.id)}`)
+    seen.set(it.id, it.line)
+    if (!it.ms) err(it.line, `${it.id} is not under a milestone heading`)
+    if (!it.meta) {
+      err(it.line, `${it.id} has no <!-- ${cfg.meta}: ... --> metadata`)
+      continue
+    }
+    if (!PRIOS.includes(it.meta.prio)) err(it.line, `${it.id}: prio must be ${PRIOS.join('|')}`)
+    if (!SIZES.includes(it.meta.size)) err(it.line, `${it.id}: size must be ${SIZES.join('|')}`)
+    const labels = (it.meta.labels ?? '').split(',').filter(Boolean)
+    if (!labels.length) err(it.line, `${it.id}: at least one label`)
+    for (const l of labels) {
+      if (l.startsWith('prio-')) err(it.line, `${it.id}: "${l}" is added from prio=, do not list it`)
+      else if (cfg.labels && !cfg.labels[l]) err(it.line, `${it.id}: unknown label "${l}"`)
+    }
+    if (it.status === 'shipped' && !it.meta.ver) err(it.line, `${it.id} is shipped but has no ver=`)
+    if (it.status === 'open' && it.meta.ver) err(it.line, `${it.id} is open but carries ver=${it.meta.ver}`)
+    if (!it.body) err(it.line, `${it.id} has no body`)
+  }
+  return errors
+}
+
+// The comment line names the generator without its runner: `node x.mjs roadmap` and
+// `npx backlogsync roadmap` print as `x.mjs roadmap` and `backlogsync roadmap`.
+const generatedBy = (cmd) => cmd.replace(/^(?:node|npx)\s+/, '')
+
+// The layout every replaced copy produced, byte for byte, given the same name and
+// regenerate command (README, "Compatibility").
+export function roadmap(model, cfg) {
+  const all = model.items
+  const shipped = all.filter((i) => i.status === 'shipped').length
+  const bar = (done, total) => {
+    const n = total ? Math.round((10 * done) / total) : 0
+    return `\`${'#'.repeat(n)}${'.'.repeat(10 - n)}\` ${total ? Math.round((100 * done) / total) : 0}%`
+  }
+  const backlog = cfg.backlogRel ?? 'BACKLOG.md'
+  const out = []
+  out.push(`# Roadmap — ${cfg.name}`, '', `<!-- GENERATED by ${generatedBy(cfg.regenerate)} — do not edit by hand. -->`, '')
+  out.push(`> This page is **generated** from [${backlog}](${backlog}), the single source of truth for planned work. Regenerate it with \`${cfg.regenerate}\` after editing the backlog — CI fails when the two disagree.`, '')
+  out.push(`**${all.length} items · ${shipped} shipped · ${all.length - shipped} open · ${model.milestones.length} milestones.**`, '')
+  out.push('## At a glance', '', '| Milestone | Phase | Progress | Open | Shipped |', '|---|---|---|---|---|')
+  for (const m of model.milestones) {
+    const s = m.items.filter((i) => i.status === 'shipped').length
+    out.push(`| **${m.title}** | ${m.phase} | ${bar(s, m.items.length)} | ${m.items.length - s} | ${s} |`)
+  }
+  out.push('')
+  for (const m of model.milestones) {
+    out.push(`## ${m.title}`, '')
+    for (const it of m.items) {
+      const tick = it.status === 'shipped' ? 'x' : ' '
+      const ver = it.meta?.ver ? ` · \`${it.meta.ver}\`` : ''
+      out.push(`- [${tick}] **${it.id}** — ${it.title} · ${it.meta?.prio ?? '?'} · ${it.meta?.size ?? '?'} · ${(it.meta?.labels ?? '').split(',').join(', ')}${ver}`)
+    }
+    out.push('')
+  }
+  return out.join('\n')
+}

package/bin/lib/config.mjs

@@ -0,0 +1,114 @@
+// Configuration: `.backlogsync.json`, or the `backlogsync` key of package.json, or the
+// file named by --config. One source only — two that could disagree is an error, not a
+// precedence rule, because a repository that carries both has already drifted.
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+export class ConfigError extends Error {}
+
+// The three vocabularies are the same in every copy this tool replaces, so they are
+// fixed rather than configurable (README, "Decisions").
+export const PRIOS = ['high', 'med', 'low']
+export const SIZES = ['S', 'M', 'L', 'XL']
+export const PHASES = ['now', 'next', 'later', 'shipped']
+
+// The priority labels every copy adds on creation. The colours are the majority's;
+// a `labels` entry of the same name overrides one.
+export const PRIO_LABELS = {
+  'prio-high': { color: 'b60205', description: 'High priority in BACKLOG.md' },
+  'prio-med': { color: 'fbca04', description: 'Medium priority in BACKLOG.md' },
+  'prio-low': { color: 'c2e0c6', description: 'Low priority in BACKLOG.md' },
+}
+
+export const DEFAULT_REGENERATE = 'npx backlogsync roadmap'
+const KEYS = new Set(['prefix', 'meta', 'name', 'backlog', 'roadmap', 'labels', 'branch', 'regenerate'])
+
+// → { root, source, prefix, meta, name, backlog, roadmap, labels, branch, regenerate }
+// `backlog` and `roadmap` are absolute; `backlogRel` is the path the documents print.
+export function loadConfig({ cwd = process.cwd(), configPath } = {}) {
+  let raw
+  let root
+  let source
+  const pkgPath = join(cwd, 'package.json')
+  const pkg = existsSync(pkgPath) ? readJson(pkgPath) : null
+  if (configPath) {
+    source = resolve(cwd, configPath)
+    raw = readJson(source)
+    root = dirname(source)
+  } else {
+    const file = join(cwd, '.backlogsync.json')
+    const inPkg = pkg && Object.hasOwn(pkg, 'backlogsync')
+    if (existsSync(file) && inPkg) throw new ConfigError('both .backlogsync.json and package.json#backlogsync exist — keep one')
+    if (existsSync(file)) {
+      source = file
+      raw = readJson(file)
+    } else if (inPkg) {
+      source = `${pkgPath}#backlogsync`
+      raw = pkg.backlogsync
+    } else throw new ConfigError('no configuration: add .backlogsync.json or a "backlogsync" key to package.json (at least {"prefix": "XX"})')
+    root = cwd
+  }
+  return normalise(raw, { root, source, pkgName: pkg?.name })
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch (e) {
+    throw new ConfigError(`${path}: ${e.code === 'ENOENT' ? 'not found' : e.message}`)
+  }
+}
+
+export function normalise(raw, { root = process.cwd(), source = '(inline)', pkgName } = {}) {
+  const bad = (msg) => {
+    throw new ConfigError(`${source}: ${msg}`)
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) bad('must be a JSON object')
+  for (const k of Object.keys(raw)) if (!KEYS.has(k)) bad(`unknown key "${k}" (known: ${[...KEYS].join(', ')})`)
+  const str = (k, re, what) => {
+    if (raw[k] === undefined) return undefined
+    if (typeof raw[k] !== 'string' || !re.test(raw[k])) bad(`${k} must be ${what}, got ${JSON.stringify(raw[k])}`)
+    return raw[k]
+  }
+  const prefix = str('prefix', /^[A-Z][A-Z0-9]*$/, 'upper-case letters and digits, starting with a letter (e.g. "ST")')
+  if (!prefix) bad('prefix is required (e.g. "ST" for ST-1, ST-2 …)')
+  const meta = str('meta', /^[a-z][a-z0-9-]*$/, 'lower-case letters, digits and dashes') ?? prefix.toLowerCase()
+  const name = str('name', /\S/, 'a non-empty string') ?? pkgName ?? basename(resolve(root))
+  const backlogRel = str('backlog', /\S/, 'a path') ?? 'BACKLOG.md'
+  const roadmapRel = str('roadmap', /\S/, 'a path') ?? 'ROADMAP.md'
+  const branch = str('branch', /^[\w./-]+$/, 'a branch name') ?? 'main'
+  const regenerate = str('regenerate', /\S/, 'the command a reader runs to regenerate the roadmap') ?? DEFAULT_REGENERATE
+
+  let labels = null
+  if (raw.labels !== undefined) {
+    if (!raw.labels || typeof raw.labels !== 'object' || Array.isArray(raw.labels)) bad('labels must be an object of name → {color, description}')
+    labels = {}
+    for (const [lname, v] of Object.entries(raw.labels)) {
+      // [color, description] is the shape the replaced scripts used; both are accepted.
+      const [color, description = ''] = Array.isArray(v) ? v : [v?.color, v?.description ?? '']
+      if (typeof color !== 'string' || !/^[0-9a-fA-F]{6}$/.test(color)) bad(`labels.${lname}.color must be six hex digits, no #`)
+      if (typeof description !== 'string') bad(`labels.${lname}.description must be a string`)
+      labels[lname] = { color: color.toLowerCase(), description }
+    }
+  }
+  return {
+    root,
+    source,
+    prefix,
+    meta,
+    name,
+    backlogRel,
+    roadmapRel,
+    backlog: resolve(root, backlogRel),
+    roadmap: resolve(root, roadmapRel),
+    labels,
+    branch,
+    regenerate,
+  }
+}
+
+// Every label the sync may need to create: the configured ones plus the priority
+// labels, a configured entry winning over the default of the same name.
+export function allLabels(cfg) {
+  return { ...(cfg.labels ?? {}), ...Object.fromEntries(Object.entries(PRIO_LABELS).filter(([k]) => !cfg.labels?.[k])) }
+}

package/bin/lib/github.mjs

@@ -0,0 +1,85 @@
+// A minimal GitHub REST client on node:http(s) — no fetch, which Node 18 still marks
+// experimental and warns about on every run. Only the calls the sync makes, and no
+// DELETE among them.
+import http from 'node:http'
+import https from 'node:https'
+
+export class GitHubError extends Error {
+  constructor(message, status) {
+    super(message)
+    this.status = status
+  }
+}
+
+export function client({ token, repo, apiUrl = 'https://api.github.com', userAgent = 'backlogsync' }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo ?? '')) throw new GitHubError(`GITHUB_REPOSITORY must be owner/name, got ${JSON.stringify(repo ?? '')}`)
+  const base = new URL(apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`)
+
+  function request(method, pathOrUrl, body) {
+    const url = new URL(pathOrUrl, base)
+    // A pagination link that points elsewhere must not receive the token.
+    if (url.origin !== base.origin) return Promise.reject(new GitHubError(`refusing to follow ${url.origin}: not ${base.origin}`))
+    const payload = body === undefined ? null : JSON.stringify(body)
+    const headers = {
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      'user-agent': userAgent,
+    }
+    if (token) headers.authorization = `Bearer ${token}`
+    if (payload) {
+      headers['content-type'] = 'application/json'
+      headers['content-length'] = Buffer.byteLength(payload)
+    }
+    const lib = url.protocol === 'http:' ? http : https
+    return new Promise((resolve, reject) => {
+      const req = lib.request(url, { method, headers }, (res) => {
+        const chunks = []
+        res.on('data', (c) => chunks.push(c))
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8')
+          let data = null
+          try {
+            data = text ? JSON.parse(text) : null
+          } catch {
+            data = text
+          }
+          if (res.statusCode >= 200 && res.statusCode < 300) resolve({ data, headers: res.headers })
+          else {
+            const msg = (data && typeof data === 'object' && data.message) || `HTTP ${res.statusCode}`
+            reject(new GitHubError(`${method} ${url.pathname}: ${res.statusCode} ${msg}`, res.statusCode))
+          }
+        })
+      })
+      req.on('error', (e) => reject(new GitHubError(`${method} ${url.pathname}: ${e.message}`)))
+      if (payload) req.write(payload)
+      req.end()
+    })
+  }
+
+  // Follows rel="next" until there is none.
+  async function all(path) {
+    const out = []
+    let next = path
+    while (next) {
+      const { data, headers } = await request('GET', next)
+      if (!Array.isArray(data)) throw new GitHubError(`GET ${path}: expected a list`)
+      out.push(...data)
+      next = String(headers.link ?? '').match(/<([^>]+)>;\s*rel="next"/)?.[1] ?? null
+    }
+    return out
+  }
+
+  const r = `repos/${repo}`
+  return {
+    repo,
+    request,
+    issues: () => all(`${r}/issues?state=all&per_page=100`),
+    labels: () => all(`${r}/labels?per_page=100`),
+    milestones: () => all(`${r}/milestones?state=all&per_page=100`),
+    createLabel: (name, color, description) => request('POST', `${r}/labels`, { name, color, description }).then((x) => x.data),
+    createMilestone: (title, description) => request('POST', `${r}/milestones`, { title, description }).then((x) => x.data),
+    createIssue: (fields) => request('POST', `${r}/issues`, fields).then((x) => x.data),
+    updateIssue: (num, fields) => request('PATCH', `${r}/issues/${num}`, fields).then((x) => x.data),
+    comment: (num, body) => request('POST', `${r}/issues/${num}/comments`, { body }).then((x) => x.data),
+  }
+}

package/bin/lib/plan.mjs

@@ -0,0 +1,53 @@
+// The planner: the backlog and the issues that exist → what to do. Pure, so every
+// decision is tested without a network — each failure mode of a sync is a wrong
+// decision here: a duplicate opened on every push, an issue closed for open work.
+import { DASH } from './backlog.mjs'
+
+// GitHub issues (REST shape) → Map(id → { num, state, title, milestone }). The id is
+// the title's prefix, the only durable link back to the backlog. Pull requests are
+// issues to the REST API and are left out. When two issues carry one id the oldest
+// wins, so a stray duplicate never takes over the item's history.
+export function existingFromIssues(list, cfg) {
+  const idRe = new RegExp(`^${cfg.prefix}-\\d+$`)
+  const map = new Map()
+  for (const i of [...list].sort((a, b) => a.number - b.number)) {
+    if (i.pull_request) continue
+    const id = String(i.title).split(DASH)[0]
+    if (!idRe.test(id) || map.has(id)) continue
+    map.set(id, { num: String(i.number), state: String(i.state).toLowerCase(), title: i.title, milestone: i.milestone?.title ?? '' })
+  }
+  return map
+}
+
+// One or more actions per item, in backlog order:
+//   CREATE     open item with no issue          REOPEN   open item whose issue is closed
+//   CLOSE      shipped item whose issue is open  RETITLE  title drifted (any state)
+//   MILESTONE  the issue sits under another milestone than the item's heading
+//   OK         already right                    SKIP     shipped and never had an issue
+// Nothing is ever deleted: there is no action for it. An issue whose item left the
+// backlog is not touched at all.
+export function plan(model, existing, only = []) {
+  const actions = []
+  for (const it of model.items) {
+    if (only.length && !only.includes(it.ms?.version)) continue
+    const ex = existing.get(it.id)
+    const want = `${it.id}${DASH}${it.title}`
+    if (ex && ex.title !== want) actions.push(['RETITLE', it.id, ex.num])
+    if (ex && ex.milestone !== undefined && it.ms && ex.milestone !== it.ms.title) actions.push(['MILESTONE', it.id, ex.num])
+    if (it.status === 'open') {
+      if (!ex) actions.push(['CREATE', it.id, '-'])
+      else if (ex.state === 'closed') actions.push(['REOPEN', it.id, ex.num])
+      else actions.push(['OK', it.id, ex.num])
+    } else {
+      if (!ex) actions.push(['SKIP', it.id, '-'])
+      else if (ex.state === 'open') actions.push(['CLOSE', it.id, ex.num])
+      else actions.push(['OK', it.id, ex.num])
+    }
+  }
+  return actions
+}
+
+export function summarise(actions) {
+  const count = (k) => actions.filter((a) => a[0] === k).length
+  return `${count('CREATE')} to create · ${count('RETITLE')} to retitle · ${count('MILESTONE')} to move · ${count('CLOSE')} to close · ${count('REOPEN')} to reopen · ${count('OK')} ok · ${count('SKIP')} skipped`
+}

package/bin/lib/sync.mjs

@@ -0,0 +1,100 @@
+// The one-way sync: BACKLOG.md → GitHub issues and milestones. The plan is computed
+// first and printed in full before anything is applied, so a run's log says what it
+// was about to do even when a later call fails.
+import { DASH } from './backlog.mjs'
+import { allLabels } from './config.mjs'
+import { existingFromIssues, plan, summarise } from './plan.mjs'
+
+export function issueBody(it, cfg, { server = 'https://github.com', repo }) {
+  const blob = `${server}/${repo}/blob/${cfg.branch}`
+  return `${it.body}
+
+---
+
+Planned work, tracked in [${cfg.backlogRel}](${blob}/${cfg.backlogRel}) as \`${it.id}\` under **${it.ms.title}** (priority ${it.meta.prio}, size ${it.meta.size}).
+
+\`${cfg.backlogRel}\` is the single source of truth: it carries the stable \`${cfg.prefix}-n\` id that commits and the CHANGELOG reference, and [${cfg.roadmapRel}](${blob}/${cfg.roadmapRel}) is generated from it. This issue is a view of that item, kept in step one way by backlogsync, so closing it means ticking the item in the backlog and regenerating the roadmap in the same commit.
+`
+}
+
+export const CLOSE_COMMENT = 'Shipped: the backlog item is ticked in the backlog. Closed by backlogsync.'
+export const REOPEN_COMMENT = 'Reopened: the backlog item is open again in the backlog. Reopened by backlogsync.'
+export const MILESTONE_DESCRIPTION = 'Backlog milestone. Source of truth: BACKLOG.md'
+
+// → { actions, summary, applied: [lines] }. `log` receives every line as it happens.
+export async function sync(model, cfg, gh, { dryRun = false, only = [], server, log = console.log } = {}) {
+  const existing = existingFromIssues(await gh.issues(), cfg)
+  const actions = plan(model, existing, only)
+  for (const a of actions) log(a.join('\t'))
+  const summary = summarise(actions)
+  log('')
+  log(summary)
+  const todo = actions.filter((a) => !['OK', 'SKIP'].includes(a[0]))
+  if (dryRun) {
+    log('(dry run — nothing changed)')
+    return { actions, summary, applied: [] }
+  }
+  const applied = []
+  const note = (s) => {
+    applied.push(s)
+    log(s)
+  }
+  const byId = new Map(model.items.map((i) => [i.id, i]))
+
+  // Labels only matter to a CREATE: an existing issue's labels are left as they are.
+  if (todo.some((a) => a[0] === 'CREATE')) {
+    const have = new Set((await gh.labels()).map((l) => l.name))
+    for (const [name, { color, description }] of Object.entries(allLabels(cfg))) {
+      if (have.has(name)) continue
+      await gh.createLabel(name, color, description)
+      have.add(name)
+      note(`  created label ${name}`)
+    }
+    // With no `labels` configured any label is allowed; one that does not exist yet is
+    // created grey rather than failing the issue.
+    const used = new Set(todo.filter((a) => a[0] === 'CREATE').flatMap((a) => byId.get(a[1]).meta.labels.split(',').filter(Boolean)))
+    for (const name of used) {
+      if (have.has(name)) continue
+      await gh.createLabel(name, 'ededed', '')
+      have.add(name)
+      note(`  created label ${name}`)
+    }
+  }
+
+  let milestones = null
+  const milestoneNumber = async (title) => {
+    milestones ??= new Map((await gh.milestones()).map((m) => [m.title, m.number]))
+    if (!milestones.has(title)) {
+      const m = await gh.createMilestone(title, MILESTONE_DESCRIPTION.replace('BACKLOG.md', cfg.backlogRel))
+      milestones.set(title, m.number)
+      note(`  created milestone ${title}`)
+    }
+    return milestones.get(title)
+  }
+
+  const repo = gh.repo
+  for (const [action, id, num] of todo) {
+    const it = byId.get(id)
+    const title = `${id}${DASH}${it.title}`
+    if (action === 'CREATE') {
+      const labels = [...it.meta.labels.split(',').filter(Boolean), `prio-${it.meta.prio}`]
+      const issue = await gh.createIssue({ title, body: issueBody(it, cfg, { server, repo }), milestone: await milestoneNumber(it.ms.title), labels })
+      note(`  created ${id}  #${issue.number}`)
+    } else if (action === 'RETITLE') {
+      await gh.updateIssue(num, { title })
+      note(`  retitled ${id}  #${num}  -> ${title}`)
+    } else if (action === 'MILESTONE') {
+      await gh.updateIssue(num, { milestone: await milestoneNumber(it.ms.title) })
+      note(`  moved ${id}  #${num}  -> ${it.ms.title}`)
+    } else if (action === 'CLOSE') {
+      await gh.comment(num, CLOSE_COMMENT)
+      await gh.updateIssue(num, { state: 'closed', state_reason: 'completed' })
+      note(`  closed ${id}  #${num}`)
+    } else if (action === 'REOPEN') {
+      await gh.updateIssue(num, { state: 'open' })
+      await gh.comment(num, REOPEN_COMMENT)
+      note(`  reopened ${id}  #${num}`)
+    }
+  }
+  return { actions, summary, applied }
+}

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "backlogsync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "BACKLOG.md as the single source of truth: a generated ROADMAP.md, a check for CI, and a one-way sync to GitHub issues and milestones. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "backlogsync": "bin/backlogsync.mjs"
+  },
+  "files": [
+    "bin",
+    "action.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node bin/backlogsync.mjs check && node scripts/repo-check.mjs && node --test",
+    "build:site": "node site/build.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Allan-Nava/backlogsync"
+  },
+  "homepage": "https://allan-nava.github.io/backlogsync/",
+  "bugs": "https://github.com/Allan-Nava/backlogsync/issues",
+  "keywords": [
+    "backlog",
+    "roadmap",
+    "github-issues",
+    "milestones",
+    "github-action",
+    "zero-dependency"
+  ],
+  "author": "Allan Nava (https://github.com/Allan-Nava)",
+  "license": "MIT",
+  "backlogsync": {
+    "prefix": "BS",
+    "meta": "bs",
+    "regenerate": "node bin/backlogsync.mjs roadmap",
+    "labels": {
+      "cli": {
+        "color": "b7552f",
+        "description": "The commands: roadmap, check, sync"
+      },
+      "sync": {
+        "color": "0e8a16",
+        "description": "The issue sync and the REST client"
+      },
+      "action": {
+        "color": "1d76db",
+        "description": "The composite action and the reusable workflows"
+      },
+      "migration": {
+        "color": "5319e7",
+        "description": "Replacing a repository's own backlog script"
+      },
+      "release": {
+        "color": "6f42c1",
+        "description": "Publishing and versioning"
+      },
+      "docs": {
+        "color": "0075ca",
+        "description": "README, CONTRIBUTING, site"
+      },
+      "project": {
+        "color": "6a737d",
+        "description": "Backlog, roadmap, repo hygiene"
+      },
+      "tests": {
+        "color": "d4c5f9",
+        "description": "Test coverage and the fake GitHub API"
+      },
+      "enhancement": {
+        "color": "a2eeef",
+        "description": "New capability"
+      }
+    }
+  },
+  "devDependencies": {
+    "marked": "^17.0.0"
+  }
+}