Add optional setup wizard for first-run onboarding#1475
Draft
NatalieNobile wants to merge 1 commit into
Draft
Conversation
Adds an opt-in `./scripts/setup` wizard and `./scripts/doctor` audit under a new `dev_setup/` Python package. The wizard streamlines first-time onboarding without modifying SDK source files. What the wizard does (3-step picker): 1. Python + dependencies preflight — verifies Python 3.8+, pip, and that `box_sdk_gen` is importable. Optionally runs `pip install -e .[test,dev]` (with a progress watchdog so the subprocess doesn't look hung). 2. Auth credentials — inner picker for Developer Token / JWT / CCG / OAuth, then captures the right credentials and writes them to `.env` at the repo root. 3. Smoke test snippet — prints a copy-pasteable Python program that authenticates and calls `client.users.get_user_me()`, keyed to the chosen auth mode. Doctor is read-only and re-runs each step's check function. What this adds: - dev_setup/ — Python package (5 modules, ~900 lines) - scripts/setup, scripts/doctor — bash launchers - .env.example — annotated template - WIZARD_FLOWS.md — decision tree + step reference What this touches in existing code: - setup.py: one-line change to `find_packages(exclude=...)` so the developer-only `dev_setup/` package isn't shipped via pip. The wizard package is named `dev_setup/` (rather than `setup/`) specifically to avoid colliding with `setup.py`. - .gitignore: adds `box-jwt-config.json` and an `!.env.example` un-ignore so the example file ships. What this does NOT touch: - box_sdk_gen/ — no SDK source changes - existing docs — README, CONTRIBUTING, docs/* unchanged The wizard is fully opt-in. Existing flows continue to work; users who prefer the README's manual setup steps are unaffected. Patterns used (paced output, picker-first, env injection, doctor-symmetry, idempotence, progress watchdog, self-containment) are distilled in setup-wizard-squared: https://github.com/NatalieNobile/setup-wizard-squared Tested locally: doctor reports 6 OK / 0 WARN / 0 FAIL after a complete developer-token round-trip. Picker grammar (1,3 / 1-3 / all / recommended / none / blank) all parse correctly. Wizard is idempotent — re-running prompts to keep or change existing values. Co-authored-by: Cursor <cursoragent@cursor.com>
NatalieNobile
added a commit
to NatalieNobile/setup-wizard-squared
that referenced
this pull request
Jun 10, 2026
The Python sibling to the box-java-sdk example. Same scaffold, same picker grammar, same 4-mode auth picker (Developer Token / JWT / CCG / OAuth) — different ecosystem (Python/pip/.env instead of Java/Gradle/.properties). Together the two examples demonstrate the scaffold is genuinely portable across language families: only step bodies and check functions change between them. What this commit adds: - examples/box-python-sdk/ — full mirror of the customized wizard copied from the upstream draft PR fork. Includes dev_setup/ (Python package), scripts/setup + scripts/doctor (bash launchers), WIZARD_FLOWS.md (Mermaid decision tree + step table), .env.example (annotated template), and a README.md explaining what was customized vs. lifted from the scaffold. - README.md — adds the box-python-sdk row to the worked-examples table with a link to the upstream draft PR (box/box-python-sdk#1475) and a one-line note that the Java/Python pair shows portability. - SKILL.md — same example registration in the Worked Examples section, plus a callout about the one ecosystem-specific concession (rename setup/ to dev_setup/ in Python repos to avoid setup.py / find_packages() collision). Co-authored-by: Cursor <cursoragent@cursor.com>
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
Adds an opt-in setup wizard (
./scripts/setup) and audit(
./scripts/doctor) that streamline first-time onboarding forcontributors and SDK consumers. The wizard verifies Python + pip,
optionally installs the SDK in editable mode, captures auth
credentials for any of the four supported modes, and prints a
copy-pasteable smoke-test snippet.
The wizard is fully opt-in. Existing manual-setup flows in the README
continue to work unchanged; users who prefer those are unaffected.
What's in the diff
dev_setup/scripts/setup,scripts/doctorpython3 -m dev_setup.wizard/.doctor.env.example.env(gitignored)WIZARD_FLOWS.md.gitignorebox-jwt-config.json, un-ignores.env.examplesetup.pyfind_packages(exclude=['docs', '*test*', 'dev_setup', 'dev_setup.*'])The package is intentionally named
dev_setup/rather thansetup/to avoid colliding with the existing
setup.pyand to makefind_packages()'s discovery rules unambiguous. The one-line excludein
setup.pykeeps the developer-only wizard out of the pipdistribution.
box_sdk_gen/is not modified. README, CONTRIBUTING, anddocs/*are untouched.
Wizard flow
3-step picker (
recommendedruns all):python >= 3.8,pip --version,import box_sdk_gen. Offerspip install -e .[test,dev]with a progress watchdog if the SDK isn't importable.getpass(no echo, no shell history); writes.envat the repo root withchmod 0600.BoxDeveloperTokenAuth,BoxJWTAuth,BoxCCGAuth, orBoxOAuthas appropriate).Picker grammar:
1,3/1-3/all/recommended/none/ blank-for-default.Pacing is tunable via
WIZARD_PACE_MS(0for CI, default80for interactive). Auto-disables when stdout isn't a TTY.Test plan
python3 -m dev_setup.wizardandpython3 -m dev_setup.doctorimport cleanly./scripts/doctoron a fresh clone reports 5 OK / 1 WARN (no.envyet) / 0 FAILrecommended,1,2,3,1-3,all,none, blank, and rejects junk gracefully.envis written, doctor flips to 6 OK / 0 WARN / 0 FAIL./scripts/setupis idempotent — prompts to keep or change existingBOX_AUTH_MODEfind_packages()exclude verified:python3 -c "from setuptools import find_packages; print(find_packages(exclude=['docs', '*test*', 'dev_setup', 'dev_setup.*']))"does not listdev_setupPatterns / provenance
The wizard's design (paced output, picker-first, env injection,
doctor-symmetry, idempotence, progress watchdog, self-contained
credential capture) is captured as a reusable scaffold at
NatalieNobile/setup-wizard-squared,with this PR's wizard mirrored as a worked example. The
box-java-sdk equivalent
is the sister PR using the same scaffold against a Java/Gradle repo.
Happy to iterate on naming, auth-mode coverage, or trim scope if
useful.