feat(cli): add unified setup wizard consolidating init/install/docker flows#132
Merged
feat(cli): add unified setup wizard consolidating init/install/docker flows#132
Conversation
… flows (#129) Create `gitlab-mcp setup` command that unifies the three separate wizards (init, install, docker init) into a single entry point with discovery, mode selection, tool configuration, and multiple execution flows. - Add src/cli/setup/ module with types, presets, discovery, wizard, and flows - Add local-setup, server-setup, configure-existing, and tool-selection flows - Define 18 tool categories and 6 preset definitions (developer, senior-dev, devops, code-reviewer, full-access, readonly) - Add missing preset YAML files: code-reviewer.yaml, full-access.yaml - Route `init` as alias to `setup --mode=local` - Route `docker init` as alias to `setup --mode=server` - Update cli-utils.ts with setup command and --mode flag parsing - Add 43 unit tests for presets, discovery, and wizard modules
📊 Test Coverage ReportOverall Coverage: 91.69% Coverage Details
Coverage Report: View detailed coverage report
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
Adds a new unified gitlab-mcp setup wizard intended to consolidate the existing init / install / docker init interactive flows into a single entry point with discovery, mode selection, and configuration flows.
Changes:
- Introduces
src/cli/setup/*(wizard orchestration, discovery, presets, and flows for local/server/configure-existing). - Routes
init→setup --mode=localanddocker init→setup --mode=serverinsrc/main.ts. - Adds unit test coverage for the new setup modules and updates existing entry/arg-parsing tests.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/main.entry.test.ts | Updates main-entry test to expect init to call runSetupWizard({ mode: "local" }). |
| tests/unit/cli/setup/wizard.test.ts | Adds unit tests for setup wizard orchestration + mode branching. |
| tests/unit/cli/setup/presets.test.ts | Adds unit tests for tool categories/presets helpers. |
| tests/unit/cli/setup/discovery.test.ts | Adds unit tests for discovery and summary formatting. |
| tests/unit/cli-utils.test.ts | Updates CLI arg parsing test shape to include setup flags. |
| src/main.ts | Adds setup handling + docker init alias routing to server setup flow. |
| src/cli-utils.ts | Adds setup args and --mode=... parsing for setup. |
| src/cli/setup/index.ts | Exposes setup module exports. |
| src/cli/setup/types.ts | Defines setup types (modes, discovery result, tool config, etc.). |
| src/cli/setup/wizard.ts | Orchestrates discovery → mode selection → flow execution → outro summary. |
| src/cli/setup/discovery.ts | Adds environment discovery (clients + docker container detection). |
| src/cli/setup/presets.ts | Defines tool categories and presets plus helper functions. |
| src/cli/setup/flows/tool-selection.ts | Adds preset/manual/advanced tool configuration prompt flow. |
| src/cli/setup/flows/local-setup.ts | Implements local (stdio) setup flow (PAT, connection test, client install). |
| src/cli/setup/flows/server-setup.ts | Implements server (Docker) setup flow. |
| src/cli/setup/flows/configure-existing.ts | Implements “configure existing” flow for detected clients/docker. |
| src/profiles/builtin/full-access.yaml | Adds missing full-access preset YAML. |
| src/profiles/builtin/code-reviewer.yaml | Adds missing code-reviewer preset YAML. |
- Rename USE_ISSUES/USE_WIKI/etc to USE_WORKITEMS/USE_GITLAB_WIKI/etc - Rename GITLAB_SCOPE_* to GITLAB_PROJECT_ID/GITLAB_ALLOWED_PROJECT_IDS - Rename GITLAB_MCP_PRESET to GITLAB_PROFILE - Rename GITLAB_URL to GITLAB_API_URL in local-setup - Apply toolConfig env to Docker config in server-setup - Add applyManualCategories() for manual mode category disabling - Add failure reporting in configure-existing updateClients - Replace process.exit(0) with null return in wizard cancel path - Remove unused skipGitlab option from wizard - Use manage_repository:fork in code-reviewer profile - Add unit tests for setup flow modules
… env to Docker - Remove "commits" from CATEGORY_ENV_MAP (browse_commits is always-on core) - Rename "namespace" scope option to "allowlist" with clearer prompt - Add environment field to DockerConfig type - Persist tool config env vars into docker-compose via generateDockerCompose - Make SetupResult.mode optional for cancel-before-selection path - Add generateDockerCompose environment tests
detectDocker now checks both `docker compose version` (v2) and `docker-compose --version` (v1) for consistency with docker-utils.
Add container-runtime module that detects Docker or Podman automatically. When Docker is unavailable, falls back to podman/podman-compose for all container operations. Centralizes runtime detection with process-level caching, eliminating duplicated logic in discovery.ts.
- Pass DEPLOYMENT_TYPE to Docker environment config - Replace hardcoded "Docker" error messages with runtime label - Add error field to configure-existing container operation failure
…compose - Use config.oauthSessionSecret and config.databaseUrl in compose env - Throw controlled error in tailLogs when no compose tool detected
…d categories - Exit non-zero from main when setup wizard fails - Add compose-bundle deployment with bundled postgres service - Store OAuth secret in .env file (0600) instead of plaintext in compose - Filter always-on categories from manual tool selection UI - Add deploymentType field to DockerConfig interface
…t code - docker init now exits non-zero on wizard failure (like init/setup) - compose-bundle only adds postgres service when oauthEnabled is true - POSTGRES_PASSWORD uses randomBytes(24) instead of weak fixed default - Add unit tests for setup subcommand parsing in cli-utils - Add tests for docker init exit codes in main.entry
…n guard - Rename list_webhooks → browse_webhooks in webhooks category - Rename list_integrations → browse_integrations in integrations category - Add return after process.exit in docker init to prevent fall-through
Test Coverage ReportOverall Coverage: 92.14%
|
|
🎉 This PR is included in version 6.31.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
polaz
added a commit
that referenced
this pull request
Jan 23, 2026
… flows (#132) * feat(cli): add unified setup wizard consolidating init/install/docker flows (#129) Create `gitlab-mcp setup` command that unifies the three separate wizards (init, install, docker init) into a single entry point with discovery, mode selection, tool configuration, and multiple execution flows. - Add src/cli/setup/ module with types, presets, discovery, wizard, and flows - Add local-setup, server-setup, configure-existing, and tool-selection flows - Define 18 tool categories and 6 preset definitions (developer, senior-dev, devops, code-reviewer, full-access, readonly) - Add missing preset YAML files: code-reviewer.yaml, full-access.yaml - Route `init` as alias to `setup --mode=local` - Route `docker init` as alias to `setup --mode=server` - Update cli-utils.ts with setup command and --mode flag parsing - Add 43 unit tests for presets, discovery, and wizard modules * refactor(setup): align env vars with config and add category application - Rename USE_ISSUES/USE_WIKI/etc to USE_WORKITEMS/USE_GITLAB_WIKI/etc - Rename GITLAB_SCOPE_* to GITLAB_PROJECT_ID/GITLAB_ALLOWED_PROJECT_IDS - Rename GITLAB_MCP_PRESET to GITLAB_PROFILE - Rename GITLAB_URL to GITLAB_API_URL in local-setup - Apply toolConfig env to Docker config in server-setup - Add applyManualCategories() for manual mode category disabling - Add failure reporting in configure-existing updateClients - Replace process.exit(0) with null return in wizard cancel path - Remove unused skipGitlab option from wizard - Use manage_repository:fork in code-reviewer profile - Add unit tests for setup flow modules * refactor(setup): remove commits mapping, rename scope option, persist env to Docker - Remove "commits" from CATEGORY_ENV_MAP (browse_commits is always-on core) - Rename "namespace" scope option to "allowlist" with clearer prompt - Add environment field to DockerConfig type - Persist tool config env vars into docker-compose via generateDockerCompose - Make SetupResult.mode optional for cancel-before-selection path - Add generateDockerCompose environment tests * fix(discovery): add docker-compose v1 fallback for compose detection detectDocker now checks both `docker compose version` (v2) and `docker-compose --version` (v1) for consistency with docker-utils. * feat(docker): add native Podman support with container runtime detection Add container-runtime module that detects Docker or Podman automatically. When Docker is unavailable, falls back to podman/podman-compose for all container operations. Centralizes runtime detection with process-level caching, eliminating duplicated logic in discovery.ts. * fix(setup): use runtime-aware messages and propagate deployment type - Pass DEPLOYMENT_TYPE to Docker environment config - Replace hardcoded "Docker" error messages with runtime label - Add error field to configure-existing container operation failure * fix(docker): propagate OAuth secrets to compose and throw on missing compose - Use config.oauthSessionSecret and config.databaseUrl in compose env - Throw controlled error in tailLogs when no compose tool detected * fix(setup): implement deployment types, secure secrets, filter ungated categories - Exit non-zero from main when setup wizard fails - Add compose-bundle deployment with bundled postgres service - Store OAuth secret in .env file (0600) instead of plaintext in compose - Filter always-on categories from manual tool selection UI - Add deploymentType field to DockerConfig interface * fix(docker): require OAuth for postgres, use random password, fix exit code - docker init now exits non-zero on wizard failure (like init/setup) - compose-bundle only adds postgres service when oauthEnabled is true - POSTGRES_PASSWORD uses randomBytes(24) instead of weak fixed default - Add unit tests for setup subcommand parsing in cli-utils - Add tests for docker init exit codes in main.entry * fix(presets): correct tool names for webhooks/integrations, add return guard - Rename list_webhooks → browse_webhooks in webhooks category - Rename list_integrations → browse_integrations in integrations category - Add return after process.exit in docker init to prevent fall-through
polaz
added a commit
that referenced
this pull request
Jan 23, 2026
…alidation (#140) * feat(availability): use WidgetAvailability for version-based widget validation Add runtime validation of widget parameters in manage_work_item handler against the detected GitLab instance version and tier before making API calls. - Add VERSION_RESTRICTED structured error type to error-handler - Add parameter-to-widget mapping (PARAMETER_WIDGET_MAP) in WidgetAvailability - Add validateWidgetParams() method that checks version/tier compatibility - Integrate validation in manage_work_item create/update actions - Return structured error with required version, detected version, and upgrade hint Closes #137 * feat(availability): add tier-gated widget params and validation tests - Expand PARAMETER_WIDGET_MAP with premium/ultimate tier entries (weight, iterationId, linkedItemIds, healthStatus, startDate, dueDate, color) - Add tier-restricted validation tests for validateWidgetParams - Add VERSION_RESTRICTED error throw tests in registry create/update handlers * fix(availability): skip validation for empty array params on create Empty assigneeIds/labelIds arrays should not trigger widget version validation on create, since the handler does not send widget input for empty arrays. Update path keeps validation for empty arrays because they semantically clear the widget. * docs(availability): clarify update validation semantics for empty arrays * fix(availability): address version parsing and error message accuracy Fix version comparison to use integer encoding (major*100+minor) instead of float math that breaks for minor versions >= 10 (e.g., 16.11 was incorrectly parsed as 17.1). Make VERSION_RESTRICTED error messages contextual: show tier info only when tier is insufficient, and tailor suggested_fix to the specific constraint violated. Remove duplicate normalizeTierForDisplay from registry in favor of exported normalizeTier from error-handler. * fix(availability): use numeric version comparison in error messages Replace string comparison of version strings with numeric parsing (major*100+minor) to prevent incorrect results for single-digit major versions (e.g., "9.0" > "15.0" in string comparison). Add tests for contextual suggested_fix messaging. * feat(cli): add unified setup wizard consolidating init/install/docker flows (#132) * feat(cli): add unified setup wizard consolidating init/install/docker flows (#129) Create `gitlab-mcp setup` command that unifies the three separate wizards (init, install, docker init) into a single entry point with discovery, mode selection, tool configuration, and multiple execution flows. - Add src/cli/setup/ module with types, presets, discovery, wizard, and flows - Add local-setup, server-setup, configure-existing, and tool-selection flows - Define 18 tool categories and 6 preset definitions (developer, senior-dev, devops, code-reviewer, full-access, readonly) - Add missing preset YAML files: code-reviewer.yaml, full-access.yaml - Route `init` as alias to `setup --mode=local` - Route `docker init` as alias to `setup --mode=server` - Update cli-utils.ts with setup command and --mode flag parsing - Add 43 unit tests for presets, discovery, and wizard modules * refactor(setup): align env vars with config and add category application - Rename USE_ISSUES/USE_WIKI/etc to USE_WORKITEMS/USE_GITLAB_WIKI/etc - Rename GITLAB_SCOPE_* to GITLAB_PROJECT_ID/GITLAB_ALLOWED_PROJECT_IDS - Rename GITLAB_MCP_PRESET to GITLAB_PROFILE - Rename GITLAB_URL to GITLAB_API_URL in local-setup - Apply toolConfig env to Docker config in server-setup - Add applyManualCategories() for manual mode category disabling - Add failure reporting in configure-existing updateClients - Replace process.exit(0) with null return in wizard cancel path - Remove unused skipGitlab option from wizard - Use manage_repository:fork in code-reviewer profile - Add unit tests for setup flow modules * refactor(setup): remove commits mapping, rename scope option, persist env to Docker - Remove "commits" from CATEGORY_ENV_MAP (browse_commits is always-on core) - Rename "namespace" scope option to "allowlist" with clearer prompt - Add environment field to DockerConfig type - Persist tool config env vars into docker-compose via generateDockerCompose - Make SetupResult.mode optional for cancel-before-selection path - Add generateDockerCompose environment tests * fix(discovery): add docker-compose v1 fallback for compose detection detectDocker now checks both `docker compose version` (v2) and `docker-compose --version` (v1) for consistency with docker-utils. * feat(docker): add native Podman support with container runtime detection Add container-runtime module that detects Docker or Podman automatically. When Docker is unavailable, falls back to podman/podman-compose for all container operations. Centralizes runtime detection with process-level caching, eliminating duplicated logic in discovery.ts. * fix(setup): use runtime-aware messages and propagate deployment type - Pass DEPLOYMENT_TYPE to Docker environment config - Replace hardcoded "Docker" error messages with runtime label - Add error field to configure-existing container operation failure * fix(docker): propagate OAuth secrets to compose and throw on missing compose - Use config.oauthSessionSecret and config.databaseUrl in compose env - Throw controlled error in tailLogs when no compose tool detected * fix(setup): implement deployment types, secure secrets, filter ungated categories - Exit non-zero from main when setup wizard fails - Add compose-bundle deployment with bundled postgres service - Store OAuth secret in .env file (0600) instead of plaintext in compose - Filter always-on categories from manual tool selection UI - Add deploymentType field to DockerConfig interface * fix(docker): require OAuth for postgres, use random password, fix exit code - docker init now exits non-zero on wizard failure (like init/setup) - compose-bundle only adds postgres service when oauthEnabled is true - POSTGRES_PASSWORD uses randomBytes(24) instead of weak fixed default - Add unit tests for setup subcommand parsing in cli-utils - Add tests for docker init exit codes in main.entry * fix(presets): correct tool names for webhooks/integrations, add return guard - Rename list_webhooks → browse_webhooks in webhooks category - Rename list_integrations → browse_integrations in integrations category - Add return after process.exit in docker init to prevent fall-through * refactor(availability): store minVersion as string for minor >= 10 support Change WidgetRequirement.minVersion from float to string to correctly represent GitLab minor versions >= 10 (e.g., "16.11") without lossy float-to-int conversion. Remove now-unnecessary minVersionToComparable and formatVersion helpers — parseVersion handles both instance and requirement versions uniformly. Clarify update validation semantics and use toHaveBeenLastCalledWith in tests to prevent false positives. * refactor(version): extract shared parseVersion utility Centralize version parsing (major*100+minor) into src/utils/version.ts and use it in WidgetAvailability, GitLabVersionDetector, and error-handler. This fixes GitLabVersionDetector incorrectly handling minor versions >= 10 (e.g., 8.14 was compared as 9.4). Make VERSION_RESTRICTED error message contextual — only mention the violated constraint (version, tier, or both). Update PARAMETER_WIDGET_MAP docstring to clarify planned #135 entries. * refactor(version): use self-documenting version thresholds and conditional tier fields Replace opaque numeric literals in determineFeatures with inline parseVersion("X.Y") calls for readability. Omit required_tier and current_tier from VERSION_RESTRICTED error when tier is sufficient, making the structured response unambiguous about which constraint is actually violated. * fix(availability): remove redundant type union and hoist tier hierarchy constant - Remove redundant `GitLabTier | "free"` union (GitLabTier already includes "free") - Hoist tierHierarchy to module-level TIER_HIERARCHY constant (avoid recreation per iteration) - Fix tierHierarchy type in error-handler from Record<string, number> to Record<GitLabTier, number> * fix(availability): skip validation for undetectable version and deduplicate tier hierarchy - Return null from validateWidgetParams when version is undetectable (parsedVersion === 0) instead of incorrectly blocking all parameters - Use shared TIER_HIERARCHY constant in isWidgetAvailable (was recreated per call) - Clear mockValidateWidgetParams in beforeEach to prevent test state leakage * refactor(availability): migrate ToolAvailability to shared parseVersion utility - Replace private float-based parseVersion (major + minor/100) with shared integer-based utility (major * 100 + minor) from src/utils/version.ts - Change minVersion type from number to string in ToolRequirement and ActionRequirement interfaces for consistency with WidgetAvailability - Remove duplicate parseVersion method from ToolAvailability class - Update all test assertions for string-based minVersion values * fix(availability): attach JSDoc to PARAMETER_WIDGET_MAP instead of TIER_HIERARCHY * fix(availability): add debug logging for unparseable version in validateWidgetParams
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
Closes #129
gitlab-mcp setupcommand that unifies three separate wizards (init,install,docker init) into a single entry point with discovery, mode selection, tool configuration, and multiple execution flowssrc/cli/setup/module with 18 tool categories, 6 preset definitions (developer, senior-dev, devops, code-reviewer, full-access, readonly), environment discovery, and local/server/configure-existing flowsinitas alias tosetup --mode=localanddocker initas alias tosetup --mode=serverfor backwards compatibilitycode-reviewer.yaml,full-access.yaml)Test plan
npx . setup— verify discovery, mode selection, flow executionnpx . init— verify alias routes to local setup flownpx . setup --mode=server— verify Docker flow