diff --git a/.claude/skills/veilid-upgrade/SKILL.md b/.claude/skills/veilid-upgrade/SKILL.md new file mode 100644 index 0000000..b67aa57 --- /dev/null +++ b/.claude/skills/veilid-upgrade/SKILL.md @@ -0,0 +1,142 @@ +--- +name: veilid-upgrade +description: Upgrade Veilid across the OpenArchive Rust dependency chain. Use when asked to upgrade Veilid, bump Veilid, move to a new Veilid version, refresh veilid-core or veilid-tools tags, or run the cross-repo Veilid release cascade for veilid-iroh-blobs, save-dweb-backend, and save-rust. +--- + +# Veilid Upgrade + +Upgrade Veilid one repository at a time, in dependency order: + +1. `../veilid-iroh-blobs` +2. `../save-dweb-backend` +3. current `save-rust` + +Read `references/dependency-map.md` before editing. It contains the repo-specific pins, git URLs, and verification commands. Treat it as a map, not as a substitute for inspecting the current files. + +## Ground Rules + +- Locate dependency entries by package key or `rg`, never by hardcoded line number. +- Keep fork-origin migration separate from a Veilid version bump unless the user explicitly asks to combine them. +- Pause after each PR is opened and ask the human to review and merge before tagging and continuing downstream. +- Verify each repo's default branch, origin, and push/tag permissions before creating PRs or tags. +- Default to a patch version bump for routine dependency-only upgrades; use a minor bump only when the changelog or API impact warrants it. + +## One-Time Fork Migration + +The chain historically depended on personal upstream forks: + +- `RangerMauve/veilid-iroh-blobs` +- `tripledoublev/iroh` + +OpenArchive forks now exist and should be the long-term dependency sources: + +- `OpenArchive/veilid-iroh-blobs` +- `OpenArchive/iroh` + +Repoint references in standalone PRs before or after a Veilid upgrade. Do not mix that origin migration into the Veilid bump unless the user asks. + +Until a repo's migration PR is merged, operate against the current upstreams listed in that repo's manifest. + +## Step 0: Verify The Target Veilid Tag + +Discover the target tag live. Prefer machine-readable sources over GitLab HTML pages: + +```bash +git ls-remote --tags https://gitlab.com/veilid/veilid.git +curl -fsS 'https://gitlab.com/api/v4/projects/veilid%2Fveilid/repository/tags?per_page=10' +curl -fsS https://gitlab.com/veilid/veilid/-/raw/main/CHANGELOG.md +``` + +Record the target tag, the target commit hash, and the changelog entry. + +Run the hickory/iroh gate before editing: + +1. Inspect the target tag's `veilid-tools/Cargo.toml` hickory dependency or scan the changelog for hickory changes. +2. If Veilid still forces the resolver constraint that required `hickory-resolver = "=0.25.2"`, keep the hickory pins and iroh patches unchanged. +3. If Veilid relaxed the constraint, drop the hickory pins and iroh patches only as a separate, well-tested change unless the user explicitly asks to combine it. +4. For routine bumps, default to keeping the existing hickory pins and iroh patches. + +## Steps 1-3: Upgrade Each Repo + +For each repo in order: + +1. Inspect the current manifest: + +```bash +rg 'veilid-core|veilid-tools|veilid-iroh-blobs|save-dweb-backend|hickory-resolver|patch.crates-io|tripledoublev|RangerMauve|OpenArchive' Cargo.toml +``` + +2. Edit `Cargo.toml`: + +- Update every `veilid-core` and `veilid-tools` git tag to the target Veilid tag. +- Update downstream git tags only after the upstream repo's PR has merged and its release tag has been pushed. +- Update all occurrences found by search, including target-specific dependency stanzas. +- Bump the package version. +- Leave hickory and iroh patch entries untouched unless Step 0 explicitly calls for a separate compatibility cleanup. + +3. Refresh the lockfile with package-aware commands from `references/dependency-map.md`. + +- Run `cargo update -p ` only for packages present in that repo. +- If Cargo refuses a package target because of source ambiguity or graph absence, run a full lockfile refresh with `cargo update` or let `cargo build` resolve it. +- Inspect `Cargo.lock` to confirm the new Veilid commit hash and any downstream git tag/hash landed. + +4. Build and test. + +- Use a normal fresh build in the current tree. Do not run `cargo clean` unless stale artifacts or dependency resolution make it necessary. +- Discover smoke test names before invoking exact filters: + +```bash +cargo nextest list +cargo test -- --list +``` + +5. Open a PR and pause. + +- Verify default branch and permissions with `gh repo view --json defaultBranchRef` and git remote checks. +- Create a branch named like `chore/veilid-0.5.x`. +- Commit the repo-local upgrade. +- Open a PR to the repo's default branch. +- Stop and ask the human to review and merge. + +6. After merge, switch to the repo's default branch and fast-forward before tagging — the feature branch does not contain the squash/merge commit, so tagging without checking out the default branch tags the wrong commit. Do NOT assume `origin` is the release repo: the local `origin` may not point at it (e.g. veilid-iroh-blobs often has `origin` = RangerMauve and a separate `openarchive` remote = OpenArchive). Confirm with `git remote -v` and push the tag to the remote the PR actually merged into: + +```bash +git remote -v # identify the release remote (the merged-into repo) +RELEASE_REMOTE=origin # set to the verified release remote, e.g. openarchive +git checkout # usually 'main'; veilid-iroh-blobs uses 'default' +git pull --ff-only "$RELEASE_REMOTE" +git tag v +git push "$RELEASE_REMOTE" v +``` + +7. Publish the GitHub Release from that tag. These repos keep a Release per tag, and a pushed git tag does NOT appear on the Releases page on its own. Only create a Release for a tag that is already on the merged default branch (never for an open PR). Match the repo's existing release-title convention: + +```bash +gh release list --repo OpenArchive/ # confirm the title convention, e.g. " vX.Y.Z" +gh release create v --repo OpenArchive/ --title " v" --notes "..." +``` + +The next repo must not point at an upstream tag until that tag exists remotely. + +## Final save-rust Release + +Run the same loop for `save-rust`. Use the repo convention for the release commit, for example: + +```text +chore: release v0.2.x +``` + +After its PR merges, tag and push the final `save-rust` release, then publish the GitHub Release (step 7). Create the Release only once every PR for this upgrade has merged, so it reflects the final merged state. + +## Verification + +- Each repo builds and tests before its PR. +- `Cargo.lock` in each repo records the expected Veilid commit hash for the target tag. +- Downstream repos point at the freshly pushed upstream release tags. +- In `save-rust`, verify the new `save-dweb-backend` tag/hash and Veilid hash in `Cargo.lock`. +- Search all three manifests for the PREVIOUS Veilid version (the one you upgraded FROM), escaped for regex — it should return nothing. Set `OLD_VEILID` to that concrete version; e.g. for a 0.5.5 → 0.5.6 bump use `0\.5\.5` (the unanchored match also covers the `v0.5.5` tag form): + +```bash +OLD_VEILID='0\.5\.5' +rg "${OLD_VEILID}" ../veilid-iroh-blobs/Cargo.toml ../save-dweb-backend/Cargo.toml Cargo.toml +``` diff --git a/.claude/skills/veilid-upgrade/references/dependency-map.md b/.claude/skills/veilid-upgrade/references/dependency-map.md new file mode 100644 index 0000000..6c21505 --- /dev/null +++ b/.claude/skills/veilid-upgrade/references/dependency-map.md @@ -0,0 +1,228 @@ +# Veilid Upgrade Dependency Map + +Use this file after reading `SKILL.md`. Verify every fact against the live manifests before editing. Do not rely on line numbers. + +## Repo Layout + +The expected sibling checkout layout from `save-rust` is: + +```text +../veilid-iroh-blobs +../save-dweb-backend +. +``` + +If a repo is missing, stop and ask the user whether to clone it, locate it, or skip that stage. + +## Current Dependency Chain + +```text +veilid tag + -> veilid-iroh-blobs release tag + -> save-dweb-backend release tag + -> save-rust release tag +``` + +The downstream repo must not be updated until the upstream repo has a merged PR and a pushed release tag. + +## Shared Compatibility Patch + +The current compatibility workaround is: + +- `hickory-resolver = "=0.25.2"` +- iroh patch entries under `[patch.crates-io]` + +Keep this workaround during routine Veilid bumps unless the target Veilid changelog or `veilid-tools/Cargo.toml` proves the resolver constraint has been relaxed. If it has been relaxed, remove the workaround as a separate PR unless the user explicitly asks to combine it. + +## Target Discovery + +Use one or both machine-readable checks: + +```bash +git ls-remote --tags https://gitlab.com/veilid/veilid.git +curl -fsS 'https://gitlab.com/api/v4/projects/veilid%2Fveilid/repository/tags?per_page=10' +``` + +Read the raw changelog: + +```bash +curl -fsS https://gitlab.com/veilid/veilid/-/raw/main/CHANGELOG.md +``` + +If fetching from the network fails because of sandboxing, request approval for the same command rather than guessing the target. + +## veilid-iroh-blobs + +Path: + +```bash +cd ../veilid-iroh-blobs +``` + +Important manifest entries to find with `rg`: + +```bash +rg 'version =|veilid-core|hickory-resolver|patch.crates-io|iroh-net|tripledoublev' Cargo.toml +``` + +Expected dependency surfaces: + +- package version, currently in the `0.3.x` line +- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` +- `hickory-resolver = "=0.25.2"` +- `[patch.crates-io] iroh-net` from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet + +Routine edit: + +- Update all `veilid-core` tag occurrences to the target Veilid tag. +- Bump the package version, usually patch. +- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise. + +Lockfile refresh candidates: + +```bash +cargo update -p veilid-core +cargo build +cargo test +``` + +If `cargo update -p veilid-core` is ambiguous or insufficient, use `cargo update`, then inspect `Cargo.lock`. + +Release handoff: + +- Open PR against the repo's default branch. +- After merge, tag `v` and push it. +- `save-dweb-backend` cannot start until this tag exists remotely. + +## save-dweb-backend + +Path: + +```bash +cd ../save-dweb-backend +``` + +Important manifest entries to find with `rg`: + +```bash +rg 'version =|veilid-core|veilid-tools|veilid-iroh-blobs|hickory-resolver|patch.crates-io|tripledoublev|RangerMauve|OpenArchive' Cargo.toml +``` + +Expected dependency surfaces: + +- package version, currently in the `0.3.x` line +- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` +- `veilid-tools` git tag from `https://gitlab.com/veilid/veilid.git` +- `veilid-iroh-blobs` git tag from `https://github.com/OpenArchive/veilid-iroh-blobs` after fork-origin migration, or the current manifest URL if migration has not landed yet +- `hickory-resolver = "=0.25.2"` +- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet + +Routine edit: + +- Update all `veilid-core` and `veilid-tools` tag occurrences to the target Veilid tag. +- Update `veilid-iroh-blobs` to the tag pushed from the previous repo. +- Bump the package version, usually patch. +- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise. + +Lockfile refresh candidates: + +```bash +cargo update -p veilid-core -p veilid-tools -p veilid-iroh-blobs +cargo build +cargo nextest run +``` + +If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`. + +Test workflow — save-dweb-backend's CI runs the full suite, so run it all. `.config/nextest.toml` already serializes and retries the flaky Veilid P2P/DHT tests: + +```bash +cargo nextest run +``` + +To narrow to specific tests, discover names first and pass them as a filter EXPRESSION with `-E`. A bare quoted string WITHOUT `-E` is a substring match and silently runs 0 tests: + +```bash +cargo nextest list +cargo nextest run -E 'test(parse_url_rejects_malformed_url)' +``` + +Release handoff: + +- Open PR against the repo's default branch. +- After merge, tag `v` and push it. +- `save-rust` cannot start until this tag exists remotely. + +## save-rust + +Path: + +```bash +cd +``` + +Important manifest entries to find with `rg`: + +```bash +rg 'version =|save-dweb-backend|veilid-core|hickory-resolver|patch.crates-io|tripledoublev' Cargo.toml +``` + +Expected dependency surfaces: + +- package name `save` +- package version, currently in the `0.2.x` line +- `save-dweb-backend` git tag from `https://github.com/OpenArchive/save-dweb-backend` +- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` +- an additional Android-target `veilid-core` dependency +- `hickory-resolver = "=0.25.2"` +- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet + +Routine edit: + +- Update all `veilid-core` tag occurrences to the target Veilid tag. +- Update `save-dweb-backend` to the tag pushed from the previous repo. +- Bump the package version, usually patch. +- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise. + +Lockfile refresh candidates: + +```bash +cargo update -p veilid-core -p save-dweb-backend +cargo build +cargo nextest run +``` + +If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`. + +Smoke-test workflow — match CI's smoke set. Pass the filter as an EXPRESSION with `-E`; without `-E` the quoted string is a substring match and silently runs 0 tests: + +```bash +cargo nextest list +cargo nextest run -E 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)' +``` + +Only use exact test filters after confirming the names still exist. + +Release: + +- Use a release commit message like `chore: release v0.2.x`. +- Open PR against the repo's default branch. +- After merge, tag `v` and push it. + +## Fork-Origin Migration + +Do this only as a standalone change unless the user explicitly asks otherwise. + +OpenArchive fork URLs: + +- `https://github.com/OpenArchive/veilid-iroh-blobs` +- `https://github.com/OpenArchive/iroh.git` + +Migration checklist: + +1. Update the `veilid-iroh-blobs` git URL in `save-dweb-backend` (and any other direct consumer) to the OpenArchive fork. +2. Update every `[patch.crates-io]` iroh entry in all three repos to `OpenArchive/iroh`. +3. Refresh lockfiles so the source hashes repoint to the OpenArchive forks. Do NOT change the **Veilid version tags** — `veilid-core`/`veilid-tools` stay on their current `vX.Y.Z`. +4. Build and test all affected repos. +5. Keep each repo's diff focused on fork origins + lockfile source hashes — no Veilid version change. +6. Separate from the Veilid tags above, you will likely need to cut **new wrapper-crate release tags** so downstream repos can consume the merged fork-origin commits. Never move an existing pushed tag — instead bump the wrapper package `version` and tag the new version: e.g. release `veilid-iroh-blobs` (bump `version`, tag `v0.3.x`) after its migration merges, then `save-dweb-backend` (bump `version`, tag `v0.3.y`), repointing each downstream git tag the same way the Veilid cascade does. This is a wrapper-crate release bump, distinct from a Veilid version change. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..14ee8b8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# Agent Guidance + +## Veilid Cross-Repo Upgrades + +For Veilid upgrades, read `.claude/skills/veilid-upgrade/SKILL.md` and `.claude/skills/veilid-upgrade/references/dependency-map.md`, then follow that runbook. + +The `.claude/skills/...` directory is a Claude Code skill location, not a native Codex skill trigger. For Codex, this `AGENTS.md` file is the discoverability pointer. + +Assume the sibling repo layout: + +```text +../veilid-iroh-blobs +../save-dweb-backend +. +``` + +Upgrade in dependency order: `veilid-iroh-blobs`, then `save-dweb-backend`, then `save-rust`. Locate dependency pins with `rg` or package keys, not line numbers. Keep fork-origin migration separate from Veilid version bumps unless the user explicitly asks to combine them. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d0fc277 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,15 @@ +# Claude Guidance + +## Veilid Cross-Repo Upgrades + +For Veilid upgrades, use the repo-local skill at `.claude/skills/veilid-upgrade/SKILL.md` and read `.claude/skills/veilid-upgrade/references/dependency-map.md` before editing. + +The expected dependency chain is: + +```text +veilid -> veilid-iroh-blobs -> save-dweb-backend -> save-rust +``` + +This checkout is expected to sit beside `../veilid-iroh-blobs` and `../save-dweb-backend`. Upgrade one repo at a time, wait for review/merge, tag the upstream release, then move to the next downstream repo. + +Do not combine the OpenArchive fork-origin migration with a Veilid version bump unless the user explicitly asks.