Summary
Extract pure, self-contained functions from bin/lib/onboard.js (~3,850 lines) into typed TypeScript modules under src/lib/. Each extraction converts CJS → ESM TS in one step, exercising the tsconfig.cli.json foundation from #913.
These extractions are independent of the #924 blockers (#781, #782, #819, #672, #634, #890) — none of the blocking PRs touch the functions listed below.
Motivation
onboard.js mixes pure logic (string parsing, state classification, URL validation) with side-effectful orchestration (gateway lifecycle, sandbox creation, user prompts). The pure functions can move to typed modules today without waiting for the blocker queue to clear, giving us:
Extraction groups
Each group becomes one PR. Groups are independent and can land in any order.
Group 1: Gateway state classification (~50 lines → src/lib/gateway-state.ts)
Pure parsers of openshell status / openshell gateway list output. No I/O — they take strings in and return booleans or enums.
getReportedGatewayNameisGatewayConnectedhasActiveGatewayInfohasStaleGatewayisSelectedGatewayisGatewayHealthygetGatewayReuseStateisSandboxReadygetSandboxStateFromOutputs
Group 2: Validation & classification (~60 lines → src/lib/validation.ts)
Pure string matching — classify error types, validate key formats, check model IDs.
classifyValidationFailureclassifyApplyFailureclassifySandboxCreateFailurevalidateNvidiaApiKeyValueisSafeModelId
Group 3: URL / string utilities (~40 lines → src/lib/url-utils.ts)
Pure string transformations for endpoint URLs, env var formatting, and policy preset parsing.
stripEndpointSuffixnormalizeProviderBaseUrlisLoopbackHostnamecompactTextformatEnvAssignmentparsePolicyPresetEnv
Group 4: Sandbox build context helpers (~30 lines → src/lib/build-context.ts)
Path filtering for Docker build context staging and failure classification for sandbox creation.
shouldIncludeBuildContextPathcopyBuildContextDirprintSandboxCreateRecoveryHints
Group 5: Dashboard URL logic (~30 lines → src/lib/dashboard.ts)
Resolve dashboard forwarding targets and build control UI URLs from auth tokens.
resolveDashboardForwardTargetbuildControlUiUrls
Approach for each PR
- Create new
.ts file in src/lib/ with typed exports
onboard.js imports from the compiled JS output- Co-located
.test.ts for the new module (tests that existed as inline assertions in runner.test.js or onboard.test.js migrate; new tests added where coverage is missing)
- Verify
npm test and make check pass
What this does NOT do
Relation to #924
This is incremental pre-work for #924's TypeScript migration. It reduces the size of onboard.js by ~210 lines and converts them to typed TS, making the eventual PR 1 rewrite smaller and less risky.
Supersedes nothing. Blocked by nothing. Can proceed immediately.
Summary
Extract pure, self-contained functions from
bin/lib/onboard.js(~3,850 lines) into typed TypeScript modules undersrc/lib/. Each extraction converts CJS → ESM TS in one step, exercising thetsconfig.cli.jsonfoundation from #913.These extractions are independent of the #924 blockers (#781, #782, #819, #672, #634, #890) — none of the blocking PRs touch the functions listed below.
Motivation
onboard.jsmixes pure logic (string parsing, state classification, URL validation) with side-effectful orchestration (gateway lifecycle, sandbox creation, user prompts). The pure functions can move to typed modules today without waiting for the blocker queue to clear, giving us:onboard.js(easier to review the remaining refactor(cli): shell consolidation, TypeScript migration & oclif #924 PRs)tsconfig.cli.jsonbeyond the coverage ratchet scriptExtraction groups
Each group becomes one PR. Groups are independent and can land in any order.
Group 1: Gateway state classification (~50 lines →
src/lib/gateway-state.ts)Pure parsers of
openshell status/openshell gateway listoutput. No I/O — they take strings in and return booleans or enums.getReportedGatewayNameisGatewayConnectedhasActiveGatewayInfohasStaleGatewayisSelectedGatewayisGatewayHealthygetGatewayReuseStateisSandboxReadygetSandboxStateFromOutputsGroup 2: Validation & classification (~60 lines →
src/lib/validation.ts)Pure string matching — classify error types, validate key formats, check model IDs.
classifyValidationFailureclassifyApplyFailureclassifySandboxCreateFailurevalidateNvidiaApiKeyValueisSafeModelIdGroup 3: URL / string utilities (~40 lines →
src/lib/url-utils.ts)Pure string transformations for endpoint URLs, env var formatting, and policy preset parsing.
stripEndpointSuffixnormalizeProviderBaseUrlisLoopbackHostnamecompactTextformatEnvAssignmentparsePolicyPresetEnvGroup 4: Sandbox build context helpers (~30 lines →
src/lib/build-context.ts)Path filtering for Docker build context staging and failure classification for sandbox creation.
shouldIncludeBuildContextPathcopyBuildContextDirprintSandboxCreateRecoveryHintsGroup 5: Dashboard URL logic (~30 lines →
src/lib/dashboard.ts)Resolve dashboard forwarding targets and build control UI URLs from auth tokens.
resolveDashboardForwardTargetbuildControlUiUrlsApproach for each PR
.tsfile insrc/lib/with typed exportsonboard.jsimports from the compiled JS output.test.tsfor the new module (tests that existed as inline assertions inrunner.test.jsoronboard.test.jsmigrate; new tests added where coverage is missing)npm testandmake checkpassWhat this does NOT do
shared/types.ts(that comes with PR 1 when the blockers clear)Relation to #924
This is incremental pre-work for #924's TypeScript migration. It reduces the size of
onboard.jsby ~210 lines and converts them to typed TS, making the eventual PR 1 rewrite smaller and less risky.Supersedes nothing. Blocked by nothing. Can proceed immediately.