Develop

README.md

@@ -26,6 +26,10 @@ See [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) for installation and usag
 
 The `no-docker` profile excludes tests under `**/nostr/api/integration/**` and sets `noDocker=true` for conditional test disabling.
 
+## Roadmap project automation
+
+Maintainers can create or refresh the GitHub Project that tracks all 1.0.0 release blockers by running `./scripts/create-roadmap-project.sh`. The helper script uses the GitHub CLI to set up draft items that mirror the tasks described in [docs/explanation/roadmap-1.0.md](docs/explanation/roadmap-1.0.md); see the [how-to guide](docs/howto/manage-roadmap-project.md) for prerequisites and usage tips.
+
 ### Troubleshooting failed relay sends
 
 When broadcasting to multiple relays, failures on individual relays are tolerated and sending continues to other relays. To inspect which relays failed during the last send on the current thread:

docs/README.md

@@ -14,6 +14,7 @@ Quick links to the most relevant guides and references.
 - [howto/api-examples.md](howto/api-examples.md) — Comprehensive examples with 13+ use cases
 - [howto/streaming-subscriptions.md](howto/streaming-subscriptions.md) — Long-lived subscriptions
 - [howto/custom-events.md](howto/custom-events.md) — Creating custom event types
+- [howto/manage-roadmap-project.md](howto/manage-roadmap-project.md) — Sync the GitHub Project with the 1.0 backlog
 
 ## Operations
 
@@ -27,6 +28,7 @@ Quick links to the most relevant guides and references.
 ## Explanation
 
 - [explanation/extending-events.md](explanation/extending-events.md) — Extending the event model
+- [explanation/roadmap-1.0.md](explanation/roadmap-1.0.md) — Outstanding work before the 1.0 release
 
 ## Project
 

docs/explanation/roadmap-1.0.md

@@ -0,0 +1,36 @@
+# 1.0 Roadmap
+
+This explanation outlines the outstanding work required to promote `nostr-java` from the current 0.6.x snapshots to a stable 1.0.0 release. Items are grouped by theme so maintainers can prioritize stabilization, hardening, and release-readiness tasks.
+
+## Release-readiness snapshot
+
+| Theme | Why it matters for 1.0 | Key tasks |
+| --- | --- | --- |
+| API stabilization | Cleanly removing deprecated entry points avoids breaking changes post-1.0. | Remove `Constants.Kind`, `Encoder.ENCODER_MAPPER_BLACKBIRD`, and other for-removal APIs. |
+| Protocol coverage | Missing tests leave command handling and relay workflows unverified. | Complete message decoding/command mapping tests; resolve brittle relay integration tests. |
+| Developer experience | Documentation gaps make migrations risky and hide release steps. | Populate the 1.0 migration guide and document dependency alignment/release chores. |
+
+## API stabilization and breaking-change prep
+
+- **Remove the deprecated constants facade.** `nostr.config.Constants.Kind` is still published even though every field is flagged `@Deprecated(forRemoval = true)`; delete the nested class (and migrate callers to `nostr.base.Kind`) before cutting 1.0.0.【F:nostr-java-api/src/main/java/nostr/config/Constants.java†L1-L194】
+- **Retire the legacy encoder singleton.** The `Encoder.ENCODER_MAPPER_BLACKBIRD` field remains available despite a for-removal notice; the mapper should be removed after migrating callers to `EventJsonMapper` so the 1.0 interface stays minimal.【F:nostr-java-base/src/main/java/nostr/base/Encoder.java†L1-L34】
+- **Drop redundant NIP facades.** The older overloads in `NIP01` and `NIP61` that still accept an explicit `Identity`/builder arguments contradict the new fluent API and are marked for removal; purge them together with any downstream usage when finalizing 1.0.【F:nostr-java-api/src/main/java/nostr/api/NIP01.java†L152-L195】【F:nostr-java-api/src/main/java/nostr/api/NIP61.java†L103-L156】
+- **Remove deprecated tag constructors.** The ad-hoc `GenericTag` constructor (and similar helpers in `EntityFactory`) persist only for backward compatibility; deleting them tightens the surface area and enforces explicit sender metadata in example factories.【F:nostr-java-event/src/main/java/nostr/event/tag/GenericTag.java†L1-L44】【F:nostr-java-id/src/test/java/nostr/id/EntityFactory.java†L25-L133】
+
+## Protocol coverage and quality gaps
+
+- **Extend message decoding coverage.** Both `BaseMessageDecoderTest` and `BaseMessageCommandMapperTest` only cover the `REQ` flow and carry TODOs for the remaining relay commands (EVENT, NOTICE, EOSE, etc.); expand the fixtures so every command path is exercised before freezing APIs.【F:nostr-java-event/src/test/java/nostr/event/unit/BaseMessageDecoderTest.java†L16-L117】【F:nostr-java-event/src/test/java/nostr/event/unit/BaseMessageCommandMapperTest.java†L16-L74】
+- **Stabilize calendar and classifieds integration tests.** The NIP-52 and NIP-99 integration suites currently comment out flaky assertions and note inconsistent relay responses (`EVENT` vs `EOSE`); diagnose the relay behavior, update expectations, and re-enable the assertions to guarantee end-to-end compatibility.【F:nostr-java-api/src/test/java/nostr/api/integration/ApiNIP52RequestIT.java†L82-L160】【F:nostr-java-api/src/test/java/nostr/api/integration/ApiNIP99RequestIT.java†L71-L165】
+
+## Documentation and release engineering
+
+- **Finish the migration checklist.** The `MIGRATION.md` entry for “Deprecated APIs Removed” still lacks the concrete removal list that integrators need; populate it with the APIs scheduled above so adopters can plan upgrades safely.【F:MIGRATION.md†L19-L169】
+- **Record the dependency alignment plan.** The parent `pom.xml` pins 0.6.5-SNAPSHOT and includes temporary module overrides until the BOM catches up; document (and eventually remove) those overrides as part of the 1.0 cut so published coordinates stay consistent.【F:pom.xml†L71-L119】
+- **Plan the version uplift.** The aggregator POM still advertises `0.6.5-SNAPSHOT`; outline the steps for bumping modules, tagging, and publishing to Central once the blockers above are cleared.【F:pom.xml†L71-L119】
+
+## Suggested next steps
+
+1. Resolve the API deprecations and land refactors behind feature flags where necessary.
+2. Stabilize the relay-facing integration tests (consider mocking relays for deterministic assertions if public relays differ).
+3. Update `MIGRATION.md` alongside each removal so downstream consumers have a single source of truth.
+4. When the backlog is green, coordinate the version bump, remove BOM overrides, and publish the 1.0.0 release notes.

docs/howto/manage-roadmap-project.md

@@ -0,0 +1,34 @@
+# Maintain the 1.0 roadmap project
+
+This how-to guide explains how to create and refresh the GitHub Projects board that tracks every task blocking the nostr-java 1.0 release. Use it when spinning up a fresh board or when the backlog has drifted from `docs/explanation/roadmap-1.0.md`.
+
+## Prerequisites
+
+- GitHub CLI (`gh`) 2.32 or newer with the “projects” feature enabled.
+- Authenticated session with permissions to create Projects for the repository owner.
+- Local clone of `nostr-java` so the script can infer the repository owner.
+- `jq` installed (used by the helper script for JSON parsing).
+
+## Steps
+
+1. Authenticate the GitHub CLI if you have not already:
+   ```bash
+   gh auth login
+   ```
+2. Enable the projects feature flag if it is not yet active:
+   ```bash
+   gh config set prompt disabled
+   gh config set projects_enabled true
+   ```
+3. From the repository root, run the helper script to create or update the board:
+   ```bash
+   ./scripts/create-roadmap-project.sh
+   ```
+4. Review the board in the GitHub UI. If duplicate draft items appear (for example because the script was re-run), consolidate them manually.
+5. When tasks are completed, update both the project item and the canonical checklist in [`docs/explanation/roadmap-1.0.md`](../explanation/roadmap-1.0.md).
+
+## Troubleshooting
+
+- **`gh` reports that the command is unknown** — Upgrade to GitHub CLI 2.32 or later so that `gh project` commands are available.
+- **Project already exists but tasks did not change** — The script always adds draft items; to avoid duplicates, delete or convert the older drafts first.
+- **Permission denied errors** — Ensure your personal access token has the `project` scope and that you are an owner or maintainer of the repository.

scripts/create-roadmap-project.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Create or update a GitHub Projects (beta) board that tracks the nostr-java 1.0 roadmap.
+# Requires: GitHub CLI 2.32+ with project commands enabled and an authenticated session.
+
+project_title="nostr-java 1.0 Roadmap"
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "GitHub CLI (gh) is required to run this script." >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required to parse GitHub CLI responses." >&2
+  exit 1
+fi
+
+repo_json=$(gh repo view --json nameWithOwner,owner --jq '{nameWithOwner, owner_login: .owner.login}' 2>/dev/null || true)
+if [[ -z "${repo_json}" ]]; then
+  echo "Unable to determine repository owner via 'gh repo view'. Ensure you are within a cloned repo or pass --repo." >&2
+  exit 1
+fi
+
+repo_name_with_owner=$(jq -r '.nameWithOwner' <<<"${repo_json}")
+repo_owner=$(jq -r '.owner_login' <<<"${repo_json}")
+
+# Look up an existing project with the desired title.
+project_number=$(gh project list --owner "${repo_owner}" --format json |
+  jq -r --arg title "${project_title}" 'map(select(.title == $title)) | first | .number // empty')
+
+if [[ -z "${project_number}" ]]; then
+  echo "Creating project '${project_title}' for owner ${repo_owner}"
+  gh project create --owner "${repo_owner}" --title "${project_title}" --format json >/tmp/project-create.json
+  project_number=$(jq -r '.number' /tmp/project-create.json)
+  echo "Created project #${project_number}"
+else
+  echo "Project '${project_title}' already exists as #${project_number}."
+fi
+
+add_task() {
+  local title="$1"
+  local body="$2"
+  echo "Ensuring draft item: ${title}"
+  gh project item-add --owner "${repo_owner}" --project "${project_number}" --title "${title}" --body "${body}" --format json >/dev/null
+}
+
+add_task "Remove deprecated constants facade" "Delete nostr.config.Constants.Kind before 1.0. See docs/explanation/roadmap-1.0.md."
+add_task "Retire legacy encoder singleton" "Drop Encoder.ENCODER_MAPPER_BLACKBIRD after migrating callers to EventJsonMapper."
+add_task "Drop deprecated NIP overloads" "Purge for-removal overloads in NIP01 and NIP61 to stabilize fluent APIs."
+add_task "Remove deprecated tag constructors" "Clean up GenericTag and EntityFactory compatibility constructors."
+add_task "Cover all relay command decoding" "Extend BaseMessageDecoderTest and BaseMessageCommandMapperTest fixtures beyond REQ."
+add_task "Stabilize NIP-52 calendar integration" "Re-enable flaky assertions in ApiNIP52RequestIT with deterministic relay handling."
+add_task "Stabilize NIP-99 classifieds integration" "Repair ApiNIP99RequestIT expectations for NOTICE/EOSE relay responses."
+add_task "Complete migration checklist" "Fill MIGRATION.md deprecated API removals section before cutting 1.0."
+add_task "Document dependency alignment plan" "Record and streamline parent POM overrides tied to 0.6.5-SNAPSHOT."
+add_task "Plan version uplift workflow" "Outline tagging and publishing steps for the 1.0.0 release in docs."
+
+cat <<INFO
+Project setup complete.
+If tasks already existed as draft items, duplicates may appear; manually consolidate as needed.
+INFO