Production install experience: npm readme, agent install guide, next-step hints#5
Merged
Merged
Conversation
ElbertePlinio
added a commit
that referenced
this pull request
Jul 4, 2026
…l bin dir picklab's bins are Node scripts, so a bun-only machine could install successfully and then fail to run them — Node >= 20 is now checked before any install mutation. Verification asks bun pm bin -g for the global bin dir instead of assuming ~/.bun/bin, honoring BUN_INSTALL_BIN and install.globalBinDir. Addresses both installer findings from landing-page PR #5 review.
ElbertePlinio
added a commit
that referenced
this pull request
Jul 4, 2026
* fix(cli): never plan privileged lab-user steps without --create-lab-user init --yes alone used to plan and execute sudo useradd for desktop profiles, contradicting the CLI's own non-interactive refusal message that demands both --yes and --create-lab-user. The lab user is also no longer a required check for any profile while run-as-lab-user isolation is deferred: doctor reports a missing lab user as an optional warn, and init failures after the project config step now print a recovery hint. * fix(sessions): report dead sessions truthfully and reap stale records on create Session records whose processes died uncleanly were listed as running (with xvfb=dead) forever and kept claiming their display. CLI and MCP status now derive dead from process liveness, and session creation reaps running records whose processes are gone before allocating resources. Run artifacts are never touched. * fix(android): start automatic emulator port allocation at 5556 The default console port 5554 is where users' own emulators live; PickLab's dedicated AVD now auto-allocates from 5556 upward so it never contends for it. An explicit --port 5554 remains valid. * feat(cli): exact-command doctor hints for cmdline-tools and SDK root Missing sdkmanager/avdmanager now hint the exact command (sdkmanager "cmdline-tools;latest") and a missing SDK root hints the exact ANDROID_HOME/ANDROID_SDK_ROOT exports, matching the install guide's promise that doctor prints runnable commands. * docs: align INSTALL.md with actual CLI behavior Smoke test now destroys with --all (bare destroy errors), init documents the --yes non-interactive mode and the explicit --create-lab-user consent, the lab user is described as optional until run-as-lab-user isolation ships, screenshot tool options and doctor hint behavior match the code, and the emulator port note explains why a user's own emulator on 5554 is never touched. * docs: align READMEs and INSTALL.md with current init and destroy semantics README no longer claims init provisions the lab user by default and shows session destroy --all; INSTALL.md describes bare init accurately (defaults to generic, prompts only for privileged steps); the installer notes when a PATH-resolved picklab shadows the copy it just installed. * fix(agents): make claude-code install idempotent like the other agents Re-running picklab agents install claude-code failed with 'MCP server picklab already exists' because the claude mcp add path skipped the already-registered pre-check the codex and cursor installers have. It now reports 'already registered (no changes made)' and exits 0; an already-exists failure from claude mcp add is also treated as a no-op while other failures still surface. * chore(release): v0.1.3 * fix(agents,sessions): validate registration content and stop helpers before reaping Registration checks now verify the entry matches the canonical picklab mcp serve snippet for all three agents, and a stale claude-code entry is repaired via claude mcp remove + add instead of being reported as registered. The session reaper stops still-alive recorded pids (xvfb, x11vnc, emulator) before deleting a dead record so no orphan helpers keep ports open. Addresses both PR #6 review findings. * fix(installer): require Node 20+ for both lanes and resolve bun's real bin dir picklab's bins are Node scripts, so a bun-only machine could install successfully and then fail to run them — Node >= 20 is now checked before any install mutation. Verification asks bun pm bin -g for the global bin dir instead of assuming ~/.bun/bin, honoring BUN_INSTALL_BIN and install.globalBinDir. Addresses both installer findings from landing-page PR #5 review.
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
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
The published npm package renders "ERROR: No README data found!" and the install flow leaves agents guessing about MCP registration, system packages, and lab provisioning (observed in a real Codex install session). This PR fixes both.
prepack/postpackcopy the root README + LICENSE intopackages/cliat publish time (npm always includes them despitefiles: ["dist"]); addedrepository,homepage,bugs,keywords. Root README images switched to absolute raw.githubusercontent URLs so they render on npmjs.com.picklab agents install), system packages per distro (incl. optional x11vnc),init --profile, lab user + AVD provisioning, and verification — with explicit sudo-consent rules. Linked from the README Install section.install.shand a successfulpicklab initnow print the follow-up commands (agents install → init --profile → doctor), so MCP registration and provisioning are discoverable from the flow itself.Validation
bun run typecheckcleannpm packtarball verified to containpackage/README.mdandpackage/LICENSE; postpack cleans the working treesh -n scripts/install.shNotes
v0.1.1tag after merge.