chore: finalize 0.1.1 release surfaces#39
Merged
Conversation
Reviewer's GuideTightens the release workflow to gate GitHub Releases on npm readiness, refreshes multi-language landing/docs hubs and release checklist for the 0.1.1 public npm path, introduces a tracked CHANGELOG, adjusts docs-contract tests accordingly, and retags Dependabot updates as enhancements. Sequence diagram for npm-gated GitHub release workflowsequenceDiagram
actor Maintainer
participant GitHubRepo
participant Actions as GitHubActions_ReleaseWorkflow
participant npm as npmRegistry
participant GHRel as GitHubReleases
Maintainer->>GitHubRepo: Push vX.Y.Z tag
GitHubRepo-->>Actions: Trigger release workflow
Actions->>Actions: verify_release_version
Actions->>Actions: pnpm_verify_release
Actions->>Actions: pnpm_pack_release
Actions->>Actions: set tarball_path
Actions->>npm: npm_preflight (NODE_AUTH_TOKEN present?)
alt Missing NPM_TOKEN
Actions->>Actions: write npm_not_configured summary
Actions-->>Maintainer: Job fails before any public release action
else NPM_TOKEN present
Actions->>npm: npm_whoami
alt Target_version_already_published
Actions->>npm: npm_view package_version
Actions->>Actions: set publish_mode=already-published
Actions->>Actions: write npm_already_published summary
Actions->>GHRel: Create GitHub Release and upload tarball
Actions-->>Maintainer: Workflow completes without npm_publish
else Target_version_not_published
Actions->>npm: npm_view package_name
alt Package_exists_and_token_has_access
Actions->>npm: npm_access_list_packages
Actions->>Actions: set publish_mode=publish
Actions->>Actions: write npm_can_publish_new_version summary
Actions->>GHRel: Create GitHub Release and upload tarball
Actions->>npm: npm_publish tarball_path
Actions-->>Maintainer: GitHub Release and npm package published from same tarball
else Package_absent_or_unexpected_error
alt Package_absent_404
Actions->>Actions: set publish_mode=publish
Actions->>Actions: write first_publish summary
Actions->>GHRel: Create GitHub Release and upload tarball
Actions->>npm: npm_publish tarball_path
Actions-->>Maintainer: First npm publish and GitHub Release from same tarball
else Unexpected_npm_error
Actions->>Actions: log_error_and_fail
Actions-->>Maintainer: Job fails before any public release action
end
end
end
end
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughThis PR updates release automation with enhanced preflight npm version checks, introduces a CHANGELOG.md file, restructures documentation across multiple language versions to emphasize Markdown-first local memory and npm global installation, and updates related tests to validate the new workflow and documentation expectations. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- The new
Preflight npm releasestep does a lot of inline shell/Node work with duplicated constants (e.g., registry URL, temp paths); consider moving this logic into a small script or composite action so it’s easier to maintain and test in isolation. npm whoamifailures in the preflight step will currently just hard-fail the job; you might want to catch that case explicitly and add a more actionableGITHUB_STEP_SUMMARYmessage so maintainers understand what went wrong with the token or registry auth.- The
docs-contracttests are tightly coupled to exact wording in READMEs and the release checklist (e.g., checking for specific phrases like 'Preflight npm release'); consider relaxing these to assert on structure or key concepts instead so routine copy edits don’t cause unnecessary test churn.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new `Preflight npm release` step does a lot of inline shell/Node work with duplicated constants (e.g., registry URL, temp paths); consider moving this logic into a small script or composite action so it’s easier to maintain and test in isolation.
- `npm whoami` failures in the preflight step will currently just hard-fail the job; you might want to catch that case explicitly and add a more actionable `GITHUB_STEP_SUMMARY` message so maintainers understand what went wrong with the token or registry auth.
- The `docs-contract` tests are tightly coupled to exact wording in READMEs and the release checklist (e.g., checking for specific phrases like 'Preflight npm release'); consider relaxing these to assert on structure or key concepts instead so routine copy edits don’t cause unnecessary test churn.
## Individual Comments
### Comment 1
<location path=".github/workflows/release.yml" line_range="115" />
<code_context>
+ exit 1
fi
+ npm whoami
+
+ if npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version --registry https://registry.npmjs.org >/tmp/npm-version.txt 2>/tmp/npm-version.err; then
</code_context>
<issue_to_address>
**suggestion (bug_risk):** `npm whoami` failure will abort the step without providing a structured summary for token/permission issues.
If `npm whoami` fails (invalid token, missing permissions, registry outage), the step exits non‑zero and the workflow stops before writing any `GITHUB_STEP_SUMMARY` guidance. Consider wrapping this in a check that captures stderr and prints a clearer message (e.g., distinguishing auth vs. registry errors), similar to the later `npm view` handling.
```suggestion
if ! npm whoami >/tmp/npm-whoami.txt 2>/tmp/npm-whoami.err; then
WHOAMI_ERR="$(cat /tmp/npm-whoami.err || true)"
{
echo "## npm authentication / registry check failed"
echo
echo "\`\`\`text"
printf '%s\n' "$WHOAMI_ERR"
echo "\`\`\`"
echo
if printf '%s' "$WHOAMI_ERR" | grep -Ei 'ENEEDAUTH|EACCES|E401|E403|token' >/dev/null 2>&1; then
echo "- npm reported an authentication or permission error when running \`npm whoami\`."
echo "- Verify that the \`NPM_TOKEN\` secret is set correctly and that it has permission to access the registry."
elif printf '%s' "$WHOAMI_ERR" | grep -Ei 'ENOTFOUND|EAI_AGAIN|ECONNREFUSED|network|ETIMEDOUT' >/dev/null 2>&1; then
echo "- npm reported a network or registry connectivity error when running \`npm whoami\`."
echo "- Check npm registry availability and network connectivity from the GitHub Actions runner."
else
echo "- \`npm whoami\` failed for an unexpected reason."
echo "- Inspect the error above and \`npm\` output logs for more details."
fi
echo
echo "The workflow will stop before attempting \`npm publish\`. Fix the issue and re-run the release workflow."
} >> "$GITHUB_STEP_SUMMARY"
printf 'npm whoami failed:\n%s\n' "$WHOAMI_ERR" >&2
exit 1
fi
```
</issue_to_address>
### Comment 2
<location path="CHANGELOG.md" line_range="28" />
<code_context>
+
+### Product
+
+- expanded reviewer, dream, and session continuity surfaces across the CLI and public docs
</code_context>
<issue_to_address>
**issue (typo):** “dream” here likely a typo or wrong term in the list of surfaces.
"Dream" seems inconsistent with the surrounding terms and may be a typo or incorrect surface name. Please update it to the intended term (e.g., "team", "stream", or another existing product surface) for clarity and accuracy.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| exit 1 | ||
| fi | ||
|
|
||
| npm whoami |
There was a problem hiding this comment.
suggestion (bug_risk): npm whoami failure will abort the step without providing a structured summary for token/permission issues.
If npm whoami fails (invalid token, missing permissions, registry outage), the step exits non‑zero and the workflow stops before writing any GITHUB_STEP_SUMMARY guidance. Consider wrapping this in a check that captures stderr and prints a clearer message (e.g., distinguishing auth vs. registry errors), similar to the later npm view handling.
Suggested change
| npm whoami | |
| if ! npm whoami >/tmp/npm-whoami.txt 2>/tmp/npm-whoami.err; then | |
| WHOAMI_ERR="$(cat /tmp/npm-whoami.err || true)" | |
| { | |
| echo "## npm authentication / registry check failed" | |
| echo | |
| echo "\`\`\`text" | |
| printf '%s\n' "$WHOAMI_ERR" | |
| echo "\`\`\`" | |
| echo | |
| if printf '%s' "$WHOAMI_ERR" | grep -Ei 'ENEEDAUTH|EACCES|E401|E403|token' >/dev/null 2>&1; then | |
| echo "- npm reported an authentication or permission error when running \`npm whoami\`." | |
| echo "- Verify that the \`NPM_TOKEN\` secret is set correctly and that it has permission to access the registry." | |
| elif printf '%s' "$WHOAMI_ERR" | grep -Ei 'ENOTFOUND|EAI_AGAIN|ECONNREFUSED|network|ETIMEDOUT' >/dev/null 2>&1; then | |
| echo "- npm reported a network or registry connectivity error when running \`npm whoami\`." | |
| echo "- Check npm registry availability and network connectivity from the GitHub Actions runner." | |
| else | |
| echo "- \`npm whoami\` failed for an unexpected reason." | |
| echo "- Inspect the error above and \`npm\` output logs for more details." | |
| fi | |
| echo | |
| echo "The workflow will stop before attempting \`npm publish\`. Fix the issue and re-run the release workflow." | |
| } >> "$GITHUB_STEP_SUMMARY" | |
| printf 'npm whoami failed:\n%s\n' "$WHOAMI_ERR" >&2 | |
| exit 1 | |
| fi |
|
|
||
| ### Product | ||
|
|
||
| - expanded reviewer, dream, and session continuity surfaces across the CLI and public docs |
There was a problem hiding this comment.
issue (typo): “dream” here likely a typo or wrong term in the list of surfaces.
"Dream" seems inconsistent with the surrounding terms and may be a typo or incorrect surface name. Please update it to the intended term (e.g., "team", "stream", or another existing product surface) for clarity and accuracy.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/release.yml:
- Around line 133-152: The preflight Node check currently only tests for the
presence of PACKAGE_NAME in the parsed /tmp/npm-access.json map but not whether
the token has write rights; update the inline node -e script (the block that
reads /tmp/npm-access.json and uses packageName from process.env) to safely
parse the file inside a try/catch, validate the file is non-empty, and then
verify that access[packageName] === "read-write" (fail with console.error and
process.exit(1) if missing or not "read-write"). Ensure JSON.parse errors and
empty/malformed /tmp/npm-access.json are caught and produce a clear error
message and non-zero exit.
In `@docs/README.zh-TW.md`:
- Line 13: The README link label "技術概覽（English / 简体中文）" mismatches its target
(currently only ./architecture.en.md); update the Markdown link for the
architecture entry so the label matches the destination—either add a second link
to the Simplified Chinese file (e.g., include ./architecture.zh-CN.md alongside
./architecture.en.md) or change the label to only "English" to match
./architecture.en.md; locate the architecture link text in README.zh-TW.md and
adjust the link target(s) and/or label accordingly.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 229553da-c333-4810-bb2d-7f548c6f9141
📒 Files selected for processing (16)
.github/dependabot.yml.github/workflows/release.yml.gitignoreCHANGELOG.mdCONTRIBUTING.mdREADME.en.mdREADME.ja.mdREADME.mdREADME.zh-TW.mddocs/README.en.mddocs/README.ja.mddocs/README.mddocs/README.zh-TW.mddocs/release-checklist.mdpackage.jsontest/docs-contract.test.ts
💤 Files with no reviewable changes (1)
- .gitignore
Comment on lines
+133
to
+152
| if npm view "${PACKAGE_NAME}" name --registry https://registry.npmjs.org >/tmp/npm-package.txt 2>/tmp/npm-package.err; then | ||
| npm access list packages --json >/tmp/npm-access.json | ||
| PACKAGE_NAME="${PACKAGE_NAME}" node -e ' | ||
| const fs = require("node:fs"); | ||
| const packageName = process.env.PACKAGE_NAME; | ||
| const access = JSON.parse(fs.readFileSync("/tmp/npm-access.json", "utf8")); | ||
| if (!(packageName in access)) { | ||
| console.error(`Package ${packageName} already exists on npm and is not publishable with the current token.`); | ||
| process.exit(1); | ||
| } | ||
| ' | ||
| echo "publish_mode=publish" >> "$GITHUB_OUTPUT" | ||
| { | ||
| echo "## npm release status" | ||
| echo | ||
| echo "- \`${PACKAGE_NAME}\` already exists on npm." | ||
| echo "- The current token can publish the new version \`${PACKAGE_VERSION}\`." | ||
| } >> "$GITHUB_STEP_SUMMARY" | ||
| exit 0 | ||
| fi |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What JSON shape does npm access list packages --json return in npm 10 and npm 11, and does it require a user/scope argument?
💡 Result:
The command npm access list packages --json returns an object where keys are package names and values are their associated access permissions (e.g., "read-only" or "read-write") for the specified user, scope, or scope:team. This format is consistent across npm 10 and npm 11, as the npm-access documentation and underlying libnpmaccess library (which powers the CLI) describe the output as a mapping of packages to permissions. It requires a user/scope argument: the syntax is npm access list packages [||scope:team] []. The argument identifies whose packages to list (user, organization/scope, or team). Without it, the command operates on the current working directory's package if present, but typically requires the specifier for listing multiple packages. Example inferred from libnpmaccess.lsPackages: {"@zkat/scope/pkg1": "read-write", "@zkat/scope/pkg2": "read-only"}. No significant changes between npm 10 (v10 docs) and npm 11 (v11 docs); both support --json flag and same synopsis.
Citations:
- 1: https://docs.npmjs.com/cli/v10/commands/npm-access
- 2: https://docs.npmjs.com/cli/v11/commands/npm-access
- 3: https://github.com/npm/cli
- 4: https://github.com/npm/libnpmaccess
🏁 Script executed:
#!/bin/bash
# Check npm documentation and test command behavior
npm --version
echo "---"
npm help access 2>&1 | grep -A 20 "list packages"Repository: Boulea7/Codex-Auto-Memory
Length of output: 79
🏁 Script executed:
#!/bin/bash
# Test npm access list packages command behavior
echo "=== Testing: npm access list packages --json (no args) ==="
npm access list packages --json 2>&1 || echo "Exit code: $?"
echo ""
echo "=== Testing: npm access list packages --json with --no-description ==="
npm access list packages --json --no-description 2>&1 || echo "Exit code: $?"Repository: Boulea7/Codex-Auto-Memory
Length of output: 1141
🏁 Script executed:
#!/bin/bash
# Check the release workflow file to understand full context
cd .github/workflows 2>/dev/null || cd .
if [ -f "release.yml" ]; then
echo "=== Lines 105-160 of release.yml ==="
sed -n '105,160p' release.yml
else
echo "File not found, searching for release.yml"
find . -name "release.yml" -type f
fiRepository: Boulea7/Codex-Auto-Memory
Length of output: 2763
Permission check only validates presence, not publish-write access.
npm access list packages --json returns a map like { "pkg": "read-only" | "read-write" }. The current check !(packageName in access) only verifies the package exists in the token's accessible set, not that the token has write permission. A token with read-only grant on an existing package (e.g., inherited org membership access, or misconfigured automation token) passes preflight but fails later at npm publish. Check should verify grant === "read-write":
🛡️ Suggested fix
PACKAGE_NAME="${PACKAGE_NAME}" node -e '
const fs = require("node:fs");
const packageName = process.env.PACKAGE_NAME;
const access = JSON.parse(fs.readFileSync("/tmp/npm-access.json", "utf8"));
- if (!(packageName in access)) {
- console.error(`Package ${packageName} already exists on npm and is not publishable with the current token.`);
+ const grant = access[packageName];
+ if (grant !== "read-write") {
+ console.error(`Package ${packageName} already exists on npm and is not publishable with the current token (grant: ${grant ?? "none"}).`);
process.exit(1);
}
'Also add error handling for JSON.parse() — if /tmp/npm-access.json is empty or malformed, it throws an uncaught exception instead of a clear error message. Wrap with try/catch or validate the file is non-empty first.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.github/workflows/release.yml around lines 133 - 152, The preflight Node
check currently only tests for the presence of PACKAGE_NAME in the parsed
/tmp/npm-access.json map but not whether the token has write rights; update the
inline node -e script (the block that reads /tmp/npm-access.json and uses
packageName from process.env) to safely parse the file inside a try/catch,
validate the file is non-empty, and then verify that access[packageName] ===
"read-write" (fail with console.error and process.exit(1) if missing or not
"read-write"). Ensure JSON.parse errors and empty/malformed /tmp/npm-access.json
are caught and produce a clear error message and non-zero exit.
| - [繁體中文 landing page](../README.zh-TW.md) | ||
| - [繁體中文 docs hub](./README.zh-TW.md) | ||
| - [架構設計（简体中文）](./architecture.md) | ||
| - [技術概覽（English / 简体中文）](./architecture.en.md) |
There was a problem hiding this comment.
Link label and destination mismatch at architecture entry.
Line 13 claims “English / 简体中文” but links only to ./architecture.en.md. This can mislead first-time readers looking for Chinese content.
Suggested doc fix
-- [技術概覽（English / 简体中文）](./architecture.en.md)
+- [技術概覽（English）](./architecture.en.md)
+- [技術概覽（简体中文）](./architecture.md)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - [技術概覽（English / 简体中文）](./architecture.en.md) | |
| - [技術概覽（English）](./architecture.en.md) | |
| - [技術概覽（简体中文）](./architecture.md) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/README.zh-TW.md` at line 13, The README link label "技術概覽（English /
简体中文）" mismatches its target (currently only ./architecture.en.md); update the
Markdown link for the architecture entry so the label matches the
destination—either add a second link to the Simplified Chinese file (e.g.,
include ./architecture.zh-CN.md alongside ./architecture.en.md) or change the
label to only "English" to match ./architecture.en.md; locate the architecture
link text in README.zh-TW.md and adjust the link target(s) and/or label
accordingly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary\n- tighten npm-first release gating so GitHub Release does not publish before npm is ready\n- refresh landing pages, docs hubs, contributing guide, and release checklist for the 0.1.1 public release path\n- add a tracked CHANGELOG and fix dependabot label noise\n\n## Verification\n- pnpm verify:release\n- pnpm test:docs-contract\n- pnpm pack:check\n- pnpm test:tarball-install-smoke\n\n## Notes\n- no remaining low-risk changes need to be absorbed from origin/fix/release-windows-and-ci-hardening\n- final npm release still needs a valid credential path: repo NPM_TOKEN or local npm login
Summary by Sourcery
Tighten the release workflow around npm publication readiness and update public-facing docs and tests for the 0.1.1 release path.
Enhancements:
Documentation:
Tests:
Summary by cubic
Enforces npm-first publication for the 0.1.1 release by gating GitHub Releases on an npm preflight and publishing to npm before attaching the release asset. Refreshes install/docs, adds a tracked
CHANGELOG.md, and reduces Dependabot label noise.New Features
.github/workflows/release.yml(requireNPM_TOKEN, runnpm whoami, check version/ownership; setpublish_modeand fail fast if not ready).npm publish.Refactors
docs/release-checklist.md: require the token, run registry preflight, treat missing token as a stop, and document a manual maintainer fallback.CHANGELOG.md, include it inpackage.json, and stop ignoring it.enhancement.Written for commit 2aba3c9. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation