fix(docs): document the install source that actually resolves by unbraind · Pull Request #16 · unbraind/pm-github

unbraind · 2026-07-25T23:49:45Z

The bug

The install command this README has always advertised does not work:

$ pm install github.com/unbraind/pm-github --project
Error: Command failed
  Extension entry file is missing at "/tmp/pm-extension-source-XXXXXX/dist/index.js"

dist/ is in .gitignore and no build output is committed, and pm does not build when installing from a GitHub source — it copies the repository as-is. So the entry file named by manifest.json has never been present for anyone installing this package the documented way.

Verified on pm 2026.7.25 in a clean pm init --workspace tracker.

The fix

Document pm install npm:pm-github, verified end to end (ok: true, failed_count: 0, the command group resolves afterwards). npm is this package's real distribution channel — the Daily Release workflow publishes it and prepack builds dist into the tarball — so the npm source needs no build output in git.

The npm: prefix is required. A bare pm install pm-github fails with Local extension source does not exist, because a bare target resolves only a local directory or a bundled alias, never the registry. (That distinction is easy to miss: pm install todos and pm install beads do succeed, because pm-cli bundles @unbrained/pm-todos and @unbrained/pm-beads under those aliases — different packages from these repos.)

Considered and rejected: committing `dist/`

It would also fix the GitHub source, and 9 sibling repos do exactly that. Rejected here because it puts build artifacts under version control, invites drift — pm-web already tracks 72 dist files against the 30 a clean build produces — and adds a conflict surface to the multi-agent merge workflow this fleet is built around.

Scope

This is one of 6 identical PRs. pm-beads, pm-brief, pm-csv, pm-github, pm-linear and pm-todos all shipped the same broken install line.

pm items

pm-github-q6ql — Issue: reproduction, root cause, and the rejected alternative

Summary by Sourcery

Clarify the documented installation method to use the npm registry source that actually resolves, and record the associated pm issue in project history.

Bug Fixes:

Note in the changelog that the previously documented GitHub-based install command fails because pm does not build when installing from a GitHub source.

Documentation:

Update README installation instructions to use pm install npm:pm-github --global instead of the non-functional GitHub source command.

Chores:

Add pm issue and history artifacts for pm-github-q6ql to track the install-command bug and its resolution.

Summary by cubic

Fix README install instructions to use the npm source pm install npm:pm-github --global, replacing the broken GitHub-based command that failed due to missing build output. Add a note explaining that the npm: prefix is required (bare pm install pm-github only resolves local/bundled aliases) and why the GitHub source cannot work (pm doesn’t build from GitHub and this repo doesn’t commit dist/).

^{Written for commit e4d1309. Summary will update on new commits.}

`pm install github.com/unbraind/pm-github` — the command this README has always advertised — fails: Extension entry file is missing at "/tmp/pm-extension-source-XXXXXX/dist/index.js" `dist/` is in .gitignore and no build output is committed, and pm does not build when installing from a GitHub source; it copies the repository as-is. So the entry file named by manifest.json has never been present for anyone installing this package the documented way. Fixed by documenting `pm install npm:pm-github`, verified end to end. npm is this package's real distribution channel — the Daily Release workflow publishes it and `prepack` builds `dist` into the tarball — so the npm source needs no build output in git. Note the `npm:` prefix is required. A bare `pm install pm-github` fails with `Local extension source does not exist`, because a bare target resolves only a local directory or a bundled alias, never the registry. Considered and rejected: committing `dist/`. It puts build artifacts under version control, invites drift (pm-web already tracks 72 dist files against the 30 a clean build produces), and adds a conflict surface to the multi-agent merge workflow this fleet is built around. Tracked in pm-github-q6ql. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

gemini-code-assist · 2026-07-25T23:49:48Z

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

sourcery-ai · 2026-07-25T23:49:51Z

🧙 Sourcery has finished reviewing your pull request!

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

coderabbitai · 2026-07-25T23:49:53Z

Warning

Review limit reached

@unbraind, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 9 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 02c14e2b-38bf-48df-8aa8-94c99397653b

📥 Commits

Reviewing files that changed from the base of the PR and between a90629c and e4d1309.

📒 Files selected for processing (4)

.agents/pm/history/pm-github-q6ql.jsonl
.agents/pm/issues/pm-github-q6ql.toon
CHANGELOG.md
README.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/document-working-npm-install-source

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

sourcery-ai

Hey - I've reviewed your changes and they look great!

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

Sourcery asked for this on the pm-beads and pm-csv PRs: the README showed the working command without saying why the two obvious alternatives do not work. A bare `pm install <pkg>` resolves only a local directory or a bundled alias and never reaches the registry, and a `github.com/unbraind/<pkg>` source cannot work because pm copies a GitHub source as-is without building it while this repository does not commit `dist/`. Someone hitting either failure now has the answer in the README instead of an entry-file-missing error. Applied to all 6 repos in this batch for consistency, not just the two Sourcery happened to review. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

unbraind · 2026-07-25T23:56:55Z

Updated: the README now explains why the npm: prefix is required.

This came from @sourcery-ai on the sibling pm-beads and pm-csv PRs — it asked for a note on why the prefix is needed and that GitHub sources are not built on install. Applying it across all 6 repos in this batch so the docs stay identical.

Recording the two failure modes, since neither error explains itself:

bare name → Local extension source does not exist. It never consults the registry. pm install todos and pm install beads do succeed though, because pm-cli bundles @unbrained/pm-todos and @unbrained/pm-beads under those aliases — different packages from these repos.
GitHub source → Extension entry file is missing at ".../dist/index.js", which reads like a broken repo rather than an unbuildable install path. That is the bug this PR fixes.

sourcery-ai Bot reviewed Jul 25, 2026

View reviewed changes

unbraind merged commit 637e1f0 into main Jul 25, 2026
5 checks passed

unbraind deleted the fix/document-working-npm-install-source branch July 25, 2026 23:58

Navigation Menu

Repository navigation

fix(docs): document the install source that actually resolves - #16

fix(docs): document the install source that actually resolves#16
unbraind merged 2 commits into
mainfrom
fix/document-working-npm-install-source

unbraind commented Jul 25, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

gemini-code-assist Bot commented Jul 25, 2026

Uh oh!

sourcery-ai Bot commented Jul 25, 2026 •

edited

Loading

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

coderabbitai Bot commented Jul 25, 2026 •

edited

Loading

Review limit reached

Uh oh!

sourcery-ai Bot left a comment

Uh oh!

unbraind commented Jul 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

unbraind commented Jul 25, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The bug

The fix

Considered and rejected: committing dist/

Scope

pm items

Summary by Sourcery

Summary by cubic

Uh oh!

gemini-code-assist Bot commented Jul 25, 2026

Uh oh!

sourcery-ai Bot commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

coderabbitai Bot commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

sourcery-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

unbraind commented Jul 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

unbraind commented Jul 25, 2026 •

edited by cubic-dev-ai Bot

Loading

Considered and rejected: committing `dist/`

sourcery-ai Bot commented Jul 25, 2026 •

edited

Loading

coderabbitai Bot commented Jul 25, 2026 •

edited

Loading