Document v0.1.0 installation packages - #453
Conversation
Describe the crates.io release and the Linux, macOS, and Windows installer matrix as published user-facing options. Include platform installation commands, payload details, prerequisites, and checksum guidance. Keep the README and user's guide aligned through the executable documentation contract.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Summary
WalkthroughDocument v0.1.0 installation packages across platforms, add complete Windows PATH and PowerShell help setup instructions, and extend documentation tests to enforce release details and Windows examples. ChangesInstallation documentation
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 20✅ Passed checks (20 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Reviewer's GuideDocuments Netsuke v0.1.0 installation options (crates.io and new pre-built installers) in README and user guide, and adds tests to keep these docs synchronized with the release packaging contract. Flow diagram for Netsuke v0.1.0 installation optionsflowchart TD
Start([User wants to install Netsuke v0.1.0])
Start --> A[Install from crates.io]
Start --> B[Install pre-built installer]
A --> A1[cargo install netsuke]
B --> C[Download from v0.1.0 GitHub release]
C --> D{Platform}
D --> L[Linux .deb or .rpm]
D --> M[macOS .pkg]
D --> W[Windows .msi]
L --> L1[Use apt or dnf to install]
M --> M1[Use installer tool]
W --> W1[Use msiexec.exe]
L1 --> End([Netsuke installed])
M1 --> End
W1 --> End
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fd99a0b9af
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| licence. Ninja must be installed separately when using the macOS or Windows | ||
| installer. | ||
|
|
||
| SHA-256 checksum files accompany the downloadable release files. Windows |
There was a problem hiding this comment.
For users downloading the listed .deb, .rpm, .pkg, or .msi packages, this wording promises corresponding SHA-256 sidecars, but the checked release pipeline runs the checksum-producing staging step before any of those packages are created (.github/workflows/build-and-package.yml lines 109–192); the later release job only uploads the resulting dist files. Consequently the generated checksums cover staged binaries, licences, and help files, not the installer packages users are being directed to download. Generate package checksums after packaging or narrow this claim to the files that actually have sidecars.
AGENTS.md reference: AGENTS.md:L44-L47
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
@coderabbitai Has this now been resolved in the latest commit?
Use codegraph analysis to determine your answer.
If this comment is now resolved, please mark it as such using the API. Otherwise, please provide an AI agent prompt for the remaining work to be done to address this comment.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '== Current checkout =='
git rev-parse HEAD
git status --short
printf '%s\n' '== Documentation and workflow candidates =='
fd -a -t f '^(users-guide\.md|build-and-package\.yml)$' . \
| sed 's#^\./##'
printf '%s\n' '== Structural outlines =='
ast-grep outline docs/users-guide.md --items all --type function,class 2>/dev/null || true
ast-grep outline .github/workflows/build-and-package.yml --items all 2>/dev/null || true
printf '%s\n' '== Checksum, package, staging, and release data-flow references =='
rg -n -i -C 5 \
'(sha[- ]?256|checksum|checksums|stage|staging|\.deb|\.rpm|\.pkg|\.msi|upload.*artifact|release)' \
docs/users-guide.md .github/workflows/build-and-package.yml
printf '%s\n' '== Review thread =='
gh api graphql -F owner='leynos' -F name='netsuke' -F number=453 -f query='
query($owner: String!, $name: String!, $number: Int!) {
repository(owner: $owner, name: $name) {
pullRequest(number: $number) {
reviewThreads(first: 100) {
nodes {
id
isResolved
comments(first: 20) {
nodes { author { login } body url }
}
}
}
}
}
}' --jq '
.data.repository.pullRequest.reviewThreads.nodes[]
| select(any(.comments.nodes[]; .url == "https://github.com/leynos/netsuke/pull/453#discussion_r3665379936"))
'Length of output: 24298
@leynos, treat this finding as resolved.
The latest commit narrows the checksum claim at docs/users-guide.md Lines
49–50: it limits SHA-256 sidecars to standalone binaries and staged help and
licence files, then explicitly states that installer packages have no checksum
sidecars in v0.1.0. The workflow still stages checksum-covered artefacts before
creating .deb, .rpm, .msi, and .pkg packages, so the documentation now
matches the release artefact flow.
I cannot resolve this thread through the API because its root comment belongs
to chatgpt-codex-connector, rather than this review identity.
| Release archives contain platform-specific packages and help artefacts. Unix | ||
| archives include a `netsuke.1` manual page. Windows archives include PowerShell | ||
| external help: | ||
| After installing the Windows PowerShell help sidecars, inspect the external |
There was a problem hiding this comment.
For Windows users who install only the MSI as instructed above, this prerequisite cannot be completed from the guide: installer/Package.wxs embeds only the executable, while the separately staged .psd1, MAML, and about-help files must be placed in a discoverable PowerShell module layout before Get-Help Netsuke -Full can consume them. Add the download, destination, and module-import steps rather than referring to an undefined sidecar installation.
AGENTS.md reference: AGENTS.md:L52-L53
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
@coderabbitai Has this now been resolved in the latest commit?
Use codegraph analysis to determine your answer.
If this comment is now resolved, please mark it as such using the API. Otherwise, please provide an AI agent prompt for the remaining work to be done to address this comment.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '== Relevant repository files =='
fd -t f . | rg '(^|/)(Package\.wxs|users-guide\.md|.*(release|package|powershell|help).*\.(ya?ml|toml|json|wxs|ps1|rs|md))$' || true
printf '%s\n' '== Guide installation and help flow =='
rg -n -C 4 \
'PowerShell help|guide-windows-help|Netsuke\.ps(m1|d1)|Get-Help Netsuke|windows-\$architecture|browser_download_url' \
docs/users-guide.md
printf '%s\n' '== Packaging / release asset graph =='
rg -n -i -C 4 \
'Netsuke\.ps(m1|d1)|about_Netsuke|Netsuke-help|windows-(amd64|arm64)|\.msi|Package\.wxs|PowerShell' \
. \
-g '!docs/users-guide.md' \
-g '!target/**' \
-g '!node_modules/**' || trueLength of output: 53455
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '== Release staging configuration and contract tests =='
sed -n '1,260p' .github/release-staging.toml
printf '%s\n' '-- staging test relationship --'
sed -n '1,150p' tests/release_staging_tests.rs
printf '%s\n' '-- documentation test relationship --'
sed -n '150,235p' tests/documentation_examples_tests.rs
printf '%s\n' '== MSI file relationship =='
sed -n '1,260p' installer/Package.wxs
printf '%s\n' '== Review thread metadata =='
gh api graphql \
-F owner='leynos' \
-F name='netsuke' \
-F number=453 \
-f query='
query($owner: String!, $name: String!, $number: Int!) {
repository(owner: $owner, name: $name) {
pullRequest(number: $number) {
reviewThreads(first: 100) {
nodes {
id
isResolved
comments(first: 20) {
nodes { databaseId body author { login } url }
}
}
}
}
}
}' \
--jq '.data.repository.pullRequest.reviewThreads.nodes[]
| select(any(.comments.nodes[]?; .url == "https://github.com/leynos/netsuke/pull/453#discussion_r3665379938"))
| {id, isResolved, comments}'Length of output: 14306
🏁 Script executed:
#!/bin/bash
set -euo pipefail
assets="$(gh api repos/leynos/netsuke/releases/tags/v0.1.0 --jq '.assets[].name')"
printf '%s\n' '== Published Windows v0.1.0 asset names =='
printf '%s\n' "$assets" | rg -i 'windows|Netsuke\.(psm1|psd1)|Netsuke-help\.xml|about_Netsuke\.help\.txt|\.msi$' || true
for architecture in amd64 arm64; do
printf '%s\n' "== $architecture guide-pattern coverage =="
for suffix in 'Netsuke.psm1' 'Netsuke.psd1' 'en-US-Netsuke-help.xml' 'en-US-about_Netsuke.help.txt'; do
matches="$(printf '%s\n' "$assets" | awk -v architecture="$architecture" -v suffix="$suffix" \
'BEGIN { IGNORECASE=1 } index($0, "windows-" architecture) && $0 ~ (suffix "$") { print }')"
if [ -z "$matches" ]; then
printf 'MISSING: windows-%s *%s\n' "$architecture" "$suffix"
exit 1
fi
printf '%s\n' "$matches"
done
doneLength of output: 1187
@leynos, leave this thread unresolved. Codegraph analysis confirms that the
latest commit adds the missing workflow:
- Download the module script, manifest, MAML help, and about-help sidecars.
- Restore them under
Documents/<PowerShell edition>/Modules/Netsuke/0.1.0/en-US. - Import
Netsuke.psd1. - Run
Get-Help Netsuke -Full.
It also aligns with the release-staging paths and confirms that the MSI embeds
only the executable.
However, verification of the published asset names failed: GitHub returned HTTP
404 for releases/tags/v0.1.0. Retry once that release is available, or update
the guide to the published tag. The guide’s windows-amd64 and
windows-arm64 matching patterns cannot be confirmed until then.
Use this agent prompt for the remaining work:
Verify the Windows PowerShell-help installation instructions in
`docs/users-guide.md` against the published Netsuke v0.1.0 GitHub release.
1. Fetch the release asset list for the tag referenced by the guide.
2. For both `amd64` and `arm64`, confirm that the guide’s PowerShell script
matches exactly one published asset for each required file:
- `Netsuke.psm1`
- `Netsuke.psd1`
- `en-US-Netsuke-help.xml`
- `en-US-about_Netsuke.help.txt`
3. If the documented tag does not exist, replace it with the correct published
release tag, and update any versioned module-directory path consistently.
4. Preserve the module layout:
`<PowerShell modules root>/Netsuke/<version>/en-US/`.
5. Add or strengthen a documentation contract test that validates the release
tag and asset-name patterns without relying solely on substring checks.
6. Run the documentation formatting and validation quality gates required by
the repository.
Document the MSI installation directory and persistent PATH setup so the installed command resolves in new and current PowerShell sessions. Add an architecture-aware download and module-install flow for the staged PowerShell help files. Narrow the checksum claim to the staged files that actually receive sidecars and state that v0.1.0 installers are not covered.
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/users-guide.md`:
- Around line 118-133: Verify the downloaded module files before importing them
in the documented installation flow. After the download loop and before
Import-Module, validate the integrity or authenticity of Netsuke.psm1 and
Netsuke.psd1 using a digest or signature mechanism that covers those files, and
abort if verification fails.
In `@README.md`:
- Around line 40-46: Pin both release-specific installation examples to version
0.1.0 by updating the cargo install command in README.md lines 40-46 and
docs/users-guide.md lines 16-22 to include the version flag, preserving the
surrounding documentation.
In `@tests/documentation_examples_tests.rs`:
- Around line 204-213: Strengthen the assertions in the documentation test
around documented_example for guide-windows-path and guide-windows-help-install:
verify the Windows PATH script targets the Path variable at User scope and uses
$netsukeDirectory, and verify the help script imports the versioned Netsuke.psd1
path while selecting architecture-aware assets. Keep the existing method-name
checks, but add assertions for these critical fragments.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 7f125e97-1e0d-45cb-833f-b5c6281b9896
📒 Files selected for processing (3)
README.mddocs/users-guide.mdtests/documentation_examples_tests.rs
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
leynos/rstest-bdd(auto-detected)leynos/ortho-config(auto-detected)leynos/shared-actions(auto-detected)
| foreach ($fileName in $patterns.Keys) { | ||
| $pattern = "*windows-$architecture*$($patterns[$fileName])" | ||
| $asset = $release.assets | Where-Object { $_.name -like $pattern } | Select-Object -First 1 | ||
| if ($null -eq $asset) { | ||
| throw "Release asset not found: $pattern" | ||
| } | ||
| $destinationDirectory = if ($localizedFiles -contains $fileName) { | ||
| $helpDirectory | ||
| } else { | ||
| $moduleDirectory | ||
| } | ||
| $destination = Join-Path $destinationDirectory $fileName | ||
| Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $destination -UseBasicParsing | ||
| } | ||
|
|
||
| Import-Module (Join-Path $moduleDirectory 'Netsuke.psd1') -Force |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant section with line numbers.
sed -n '100,150p' docs/users-guide.md
# Find any mention of the downloaded module files, hashes, signatures, or import flow.
rg -n "Netsuke\.psm1|Netsuke\.psd1|SHA-256|sha256|signature|Import-Module|Invoke-WebRequest|browser_download_url|release assets" docs users-guide.md . -g '!**/.git/**' || trueRepository: leynos/netsuke
Length of output: 34726
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the documentation claim about checksum files and the packaging logic
# for release artefacts and staged help.
sed -n '40,70p' README.md
sed -n '1,120p' scripts/package-artefact.sh
sed -n '1,140p' tests/release_staging_tests.rs
sed -n '1,220p' tests/release_help_script_tests.rsRepository: leynos/netsuke
Length of output: 14010
Verify the downloaded PowerShell module before import. Invoke-WebRequest fetches Netsuke.psm1 and Netsuke.psd1 directly from the release asset URL, and Import-Module executes them immediately afterwards. Add a digest or signature check first; the documented SHA-256 sidecars do not cover these files.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/users-guide.md` around lines 118 - 133, Verify the downloaded module
files before importing them in the documented installation flow. After the
download loop and before Import-Module, validate the integrity or authenticity
of Netsuke.psm1 and Netsuke.psd1 using a digest or signature mechanism that
covers those files, and abort if verification fails.
| Netsuke v0.1.0 is available from crates.io: | ||
|
|
||
| <!-- tested-example: readme-crates-io-install --> | ||
|
|
||
| ```sh | ||
| cargo install netsuke | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'README.md matches:\n'
rg -n "cargo install netsuke|v0\.1\.0" README.md docs/users-guide.md
printf '\nRelease metadata:\n'
rg -n "0\.1\.0|crates\.io" Cargo.toml .github docs README.mdRepository: leynos/netsuke
Length of output: 144
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Cargo.toml =="
sed -n '1,120p' Cargo.toml
echo
echo "== README.md relevant lines =="
sed -n '30,55p' README.md
echo
echo "== docs/users-guide.md relevant lines =="
sed -n '1,35p' docs/users-guide.mdRepository: leynos/netsuke
Length of output: 6322
Pin both crates.io examples to v0.1.0.
cargo install netsuke pulls the latest published release, so these release-specific examples will drift as soon as a newer crate lands.
README.md#L40-L46: usecargo install netsuke --version 0.1.0.docs/users-guide.md#L16-L22: apply the same pin.
📍 Affects 2 files
README.md#L40-L46(this comment)docs/users-guide.md#L16-L22
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 40 - 46, Pin both release-specific installation
examples to version 0.1.0 by updating the cargo install command in README.md
lines 40-46 and docs/users-guide.md lines 16-22 to include the version flag,
preserving the surrounding documentation.
| let windows_path = documented_example("guide-windows-path")?; | ||
| ensure!( | ||
| windows_path.body.contains("SetEnvironmentVariable"), | ||
| "Windows PATH setup should persist the MSI installation directory" | ||
| ); | ||
| let windows_help_install = documented_example("guide-windows-help-install")?; | ||
| ensure!( | ||
| windows_help_install.body.contains("Import-Module"), | ||
| "Windows help setup should import the downloaded sidecars" | ||
| ); |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Assert the Windows setup contract, not only method names.
contains("SetEnvironmentVariable") passes even if the script updates the wrong variable or scope, and contains("Import-Module") passes even if it imports the wrong path. Assert critical fragments such as 'Path', 'User', $netsukeDirectory, the versioned Netsuke.psd1 path, and architecture-aware asset selection.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@tests/documentation_examples_tests.rs` around lines 204 - 213, Strengthen the
assertions in the documentation test around documented_example for
guide-windows-path and guide-windows-help-install: verify the Windows PATH
script targets the Path variable at User scope and uses $netsukeDirectory, and
verify the help script imports the versioned Netsuke.psd1 path while selecting
architecture-aware assets. Keep the existing method-name checks, but add
assertions for these critical fragments.
2 participants
Summary
Stack: 2/2 — depends on #448.
This branch documents Netsuke v0.1.0 as available through crates.io and as
pre-built installers for Linux, macOS, and Windows. It gives users the
architecture matrix, platform installation commands, Ninja dependency rules,
installed help details, and accurate checksum scope.
The Windows guidance records the MSI installation directory, provides a
persistent per-user PATH setup, and supplies an architecture-aware script that
downloads, lays out, and imports the separately published PowerShell help
module. The parent PR makes Netsuke publishable as a single crate; this child
keeps the README and user's guide aligned with the resulting release and
packaging surfaces.
Review walkthrough
The documented matrix and caveats follow .github/workflows/release.yml, .github/workflows/build-and-package.yml, .github/release-staging.toml, and installer/Package.wxs.
Validation
cargo test --test documentation_examples_tests installation_examples_match_source_and_release_contracts: passedmake check-fmt: passedmake lint: passedmake test: passedmake markdownlint: passedmake nixie: passedmbake validate Makefile: passedcargo package --allow-dirty --no-verify --list: passedgit diff --check remove-ambient-fs..HEAD: passedSummary by Sourcery
Document Netsuke v0.1.0 distribution channels and release details across README and the user’s guide, and keep them in sync via tests.
Documentation:
Tests: