@buildkitgg/dev-domains 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,12 +1,20 @@
1
1
  # Change Log - @buildkitgg/dev-domains
2
2
 
3
- <!-- This log was last generated on Tue, 03 Nov 2026 11:28:14 GMT and should not be manually modified. -->
3
+ <!-- This log was last generated on Wed, 18 Nov 2026 02:20:14 GMT and should not be manually modified. -->
4
4
 
5
5
  <!-- Start content -->
6
6
 
7
+ ## 0.1.4
8
+
9
+ Wed, 18 Nov 2026 02:20:14 GMT
10
+
11
+ ### Patches
12
+
13
+ - Accept a separate --cwd or --config value without a command name, and detect next dev --turbo servers (ajcraswell@gmail.com)
14
+
7
15
  ## 0.1.3
8
16
 
9
- Tue, 03 Nov 2026 11:28:14 GMT
17
+ Tue, 03 Nov 2026 11:33:33 GMT
10
18
 
11
19
  ### Patches
12
20
 
package/README.md CHANGED
@@ -5,7 +5,7 @@ Stable local URLs for your app, Storybook, and end-to-end test servers, across r
5
5
  `@buildkitgg/dev-domains` gives each server a predictable hostname and runs it through
6
6
  [Portless](https://github.com/vercel-labs/portless). You can open `https://shop.localhost` in your primary checkout and
7
7
  `https://shop-fix-login.localhost` in a worktree, with ports assigned automatically. A configuration file lets you
8
- choose your own names, use a real domain, describe authentication callbacks, and expose selected webhook routes.
8
+ choose your own names, use a real domain, list authentication callback URLs, and expose selected webhook routes.
9
9
 
10
10
  Requires Node.js 24 or later. Supports Windows, macOS, and Linux.
11
11
 
@@ -43,16 +43,16 @@ routes served by the same process share that endpoint.
43
43
 
44
44
  The package follows a few principles:
45
45
 
46
- - **Useful defaults, explicit overrides.** Discover conventional setups without a config file, then save a typed
47
- configuration when your project needs different names or commands.
48
- - **Readable checkout names.** Identify linked worktrees by their folder names. The primary checkout has no `main`
49
- label, and hostnames do not acquire random hashes.
50
- - **A convenience helper around Portless.** [Portless](https://github.com/vercel-labs/portless) provides local routing
51
- and HTTPS. This package adds tool detection, typed configuration, and consistent domains across apps and worktrees.
52
- - **Report conflicts.** A running endpoint keeps its hostname. Another process must choose a different name instead of
53
- taking over the route.
54
- - **Keep application choices with the application.** Authentication providers, cloud resources, DNS administration, and
55
- deployment remain under your control. A Buildkit account or hosted service is not required.
46
+ - Conventional setups work without a config file. Save a typed configuration when your project needs different names or
47
+ commands.
48
+ - Linked worktrees are named after their folders. The primary checkout gets no `main` label, and hostnames never carry
49
+ random hashes.
50
+ - [Portless](https://github.com/vercel-labs/portless) provides local routing and HTTPS. This package adds tool
51
+ detection, typed configuration, and consistent domains across apps and worktrees.
52
+ - A running endpoint keeps its hostname. Another process that wants the same name gets an error and must choose a
53
+ different one; it never takes over the route.
54
+ - Authentication providers, cloud resources, DNS administration, and deployment stay under your control. You don't need
55
+ a Buildkit account or hosted service.
56
56
 
57
57
  Separate hostnames and ports do not isolate databases, storage, credentials, or framework build directories. This
58
58
  package manages local server addresses and processes; resource isolation remains part of your application setup.
@@ -70,9 +70,10 @@ the root; installing it only in `apps/web` may not satisfy that import. A worksp
70
70
  or owns its own typed configuration must also be able to resolve the package. Declare a dependency in that workspace
71
71
  when your package manager isolates workspace dependencies.
72
72
 
73
- Consumer-facing commands use `npx @buildkitgg/dev-domains`, which runs the locally installed package's CLI. Installing
74
- and locking the dependency keeps the CLI and configuration helpers on the same version. Portless is included; a separate
75
- global installation is unnecessary. Your application frameworks and any tunnel executable must already be installed.
73
+ The commands in this guide use `npx @buildkitgg/dev-domains`, which runs the locally installed CLI. Installing and
74
+ locking the dependency keeps the CLI and configuration helpers on the same version. Portless is a dependency of this
75
+ package, so you don't install it separately. Your application frameworks and any tunnel executable must already be
76
+ installed.
76
77
 
77
78
  On Windows, Portless also requires OpenSSL on `PATH`. Initial HTTPS setup can require permission to trust a local
78
79
  certificate authority, bind the proxy port, or update the hosts file. Run setup interactively on each development
@@ -114,12 +115,19 @@ Run the wizard when you want to choose and save your endpoints:
114
115
  npx @buildkitgg/dev-domains init
115
116
  ```
116
117
 
117
- The wizard detects servers, lets you select them and rename the primary-checkout and worktree templates, and offers
118
- optional authentication callback paths, a dedicated Playwright server, and webhook tunneling. Detected E2E servers start
119
- unchecked. Review the resulting domains before saving `dev-domains.json` at the checkout root.
118
+ The wizard walks through these steps:
120
119
 
121
- Use arrow keys to move, Space to toggle a selection, and Enter to continue. Cancellation writes nothing. Existing
122
- configuration files are never overwritten, and package scripts are not rewritten.
120
+ 1. Confirm the project name and the local domain suffix.
121
+ 2. Select which detected servers get domains. Detected E2E servers start unchecked. If nothing is detected, enter a
122
+ server command as a JSON argument array instead.
123
+ 3. Set the primary-checkout and worktree name templates for each endpoint.
124
+ 4. For each app endpoint, optionally add authentication callback paths, a dedicated Playwright server, or a webhook
125
+ tunnel.
126
+ 5. Review the resulting domains and save `dev-domains.json` at the checkout root.
127
+
128
+ Use arrow keys to move, Space to toggle a selection, and Enter to continue. Ctrl+C cancels, and cancelling writes
129
+ nothing. If the checkout root already has a dev-domains config, `init` stops without changing it. It never rewrites
130
+ package scripts.
123
131
 
124
132
  For noninteractive setup:
125
133
 
@@ -128,33 +136,35 @@ npx @buildkitgg/dev-domains init --yes --dry-run
128
136
  npx @buildkitgg/dev-domains init --yes --project shop --domain localhost
129
137
  ```
130
138
 
131
- `--yes` accepts detected ordinary servers and omits optional E2E servers. `--dry-run` prints the proposed configuration
132
- without saving it. Without `--yes`, a dry run still uses the interactive wizard. `--domain` changes the suffix; custom
133
- hostname layouts also require the name templates described under [Domain naming](#domain-naming).
139
+ `--yes` accepts detected ordinary servers and omits optional E2E servers. Without a terminal, `init` requires `--yes`.
140
+ `--dry-run` prints the proposed configuration without saving it. Without `--yes`, a dry run still uses the interactive
141
+ wizard. `--domain` changes the suffix; custom hostname layouts also require the name templates described under
142
+ [Domain naming](#domain-naming).
134
143
 
135
144
  ## Zero-configuration behavior
136
145
 
137
146
  When no configuration file is found, these conventions determine the candidates:
138
147
 
139
- | Concern | Behavior |
140
- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
141
- | Project root | The current Git checkout root; outside Git, the current directory or `--cwd` |
142
- | Project name | Root `package.json` name, otherwise the root folder name, normalized as described below |
143
- | Package manager | Root `packageManager`, then `devEngines.packageManager`, then lockfiles, then installation metadata; npm if none is found |
144
- | Workspace packages | Root plus declared `pnpm-workspace.yaml` packages or `package.json` workspaces; without declarations, packages found recursively below the root |
145
- | App server | The package's `dev` script, when it starts one server; other script names require explicit configuration |
146
- | Storybook server | A script containing `storybook dev`; otherwise a discovered `.storybook/main.*` config |
147
- | Playwright candidate | A `playwright.config.*` file, an `@playwright/test` dependency, or a `playwright test` script, together with an app dev script in the same package |
148
- | Framework | Recognized simple Next.js, Vite, and Storybook commands receive framework-specific flags; other commands are `custom` |
149
- | Local proxy | HTTPS on port 443, suffix `localhost`, hosts synchronization enabled |
150
- | Auth and public access | No callback paths or tunnels are inferred |
148
+ | Concern | Behavior |
149
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
150
+ | Project root | The current Git checkout root; outside Git, the current directory or `--cwd` |
151
+ | Project name | Root `package.json` name, otherwise the root folder name, normalized as described below |
152
+ | Package manager | Root `packageManager`, then `devEngines.packageManager`, then lockfiles, then installation metadata; npm if none is found |
153
+ | Workspace packages | Root plus declared `pnpm-workspace.yaml` packages or `package.json` workspaces; without declarations, packages found recursively below the root |
154
+ | App server | The package's `dev` script, unless it runs `storybook dev` or `playwright test`; other script names require explicit configuration |
155
+ | Storybook server | A script containing `storybook dev`; otherwise a discovered `.storybook/main.*` config |
156
+ | Playwright candidate | A `playwright.config.*` file, an `@playwright/test` dependency, or a `playwright test` script, together with an app dev script in the same package |
157
+ | Framework | A script that starts with `next dev`, `vite`, or `storybook dev` and contains no `;`, `&`, `\|`, `#`, or standalone `--` gets framework flags; anything else is `custom` |
158
+ | Local proxy | HTTPS on port 443, suffix `localhost`, hosts synchronization enabled |
159
+ | Auth and public access | No callback paths or tunnels are inferred |
151
160
 
152
161
  Package-manager detection stays at the selected project root. A declaration takes precedence over stale lockfiles.
153
162
  Conflicting lockfiles without a declaration require you to choose a manager in `package.json` or an explicit config.
154
163
 
155
- Scripts that invoke `dev-domains`, `portless`, `turbo`, `run-p`, or `concurrently` are excluded from detection. Point
156
- configuration at the underlying server script when an aggregate or wrapper command is involved. A `playwright test`
157
- script is never used as the app server.
164
+ Scripts that contain the word `dev-domains`, `portless`, `run-p`, or `concurrently`, or that run the `turbo` command,
165
+ are excluded from detection. A `--turbo` flag doesn't count, so `next dev --turbo` is still detected as a Next.js
166
+ server. Point configuration at the underlying server script when an aggregate or wrapper command is involved. A
167
+ `playwright test` script is never used as the app server.
158
168
 
159
169
  There is no universally required development script name. `dev` is the default convention; scripts with any other name
160
170
  work through an explicit `script` setting. Detection does not guess whether `start`, `serve`, or a custom script is a
@@ -162,24 +172,35 @@ development server, production server, or build task.
162
172
 
163
173
  ### Storybook and Playwright discovery
164
174
 
165
- Discovery finds both `.storybook/main.*` and `playwright.config.*`. It recognizes `ts`, `mts`, `cts`, `js`, `mjs`,
166
- `cjs`, `tsx`, and `jsx` filenames. Configs belong to their nearest package, including nested paths such as
167
- `tests/playwright.config.ts`. Tool configuration files are located without being imported or executed.
175
+ Discovery makes one walk through the project, looking for `.storybook/main.*` and `playwright.config.*` files with a
176
+ `ts`, `mts`, `cts`, `js`, `mjs`, `cjs`, `tsx`, or `jsx` extension. It finds them without importing or running them.
177
+
178
+ - A config belongs to its nearest package, including nested paths such as `tests/playwright.config.ts`. A config inside
179
+ a package that your workspace declarations leave out is ignored.
180
+ - The walk honors workspace exclusions. It skips symlinks, `node_modules`, generated output (`dist`, `build`, `out`,
181
+ `coverage`, `storybook-static`, `playwright-report`, and `test-results`), and hidden directories other than
182
+ `.storybook`.
183
+ - Use explicit configuration for unusual layouts, or when discovery reports too many packages or directories.
184
+
185
+ For Storybook:
186
+
187
+ - A script containing `storybook dev` takes precedence over a config file.
188
+ - With one config and no such script, the candidate runs the installed binary as `storybook dev --config-dir`, followed
189
+ by the config's directory. Nothing is downloaded.
190
+ - Several Storybook scripts in one package, or several configs without a script, require explicit configuration.
191
+ - An empty `.storybook` folder or a Storybook dependency alone doesn't make a runnable server.
168
192
 
169
- Discovery honors workspace exclusions and skips dependencies, generated output, symlinks, and hidden directories other
170
- than `.storybook`. Use explicit configuration for unusual layouts or when discovery reports that a project is too large.
193
+ Finding Playwright doesn't reveal which server your tests need, so the suggested E2E endpoint keeps to the package's own
194
+ dev server:
171
195
 
172
- For Storybook, a dev script takes precedence over config-file discovery. With one config and no dev script, the
173
- candidate runs the installed `storybook dev --config-dir <directory>` binary. Nothing is downloaded. Multiple dev
174
- scripts, or multiple configs without a clear dev script, require explicit configuration. An empty `.storybook` folder or
175
- a Storybook dependency alone does not establish a runnable server.
196
+ - It starts a separate copy of the package's `dev` server. It doesn't read Playwright's `webServer` configuration.
197
+ - It's named `app-e2e`, or `<package>-app-e2e` in a workspace package.
198
+ - `init --yes` omits it, and the wizard lists it unchecked. Select it there, or run it by name when using zero
199
+ configuration.
176
200
 
177
- Finding Playwright does not reveal which server your tests need. The suggested endpoint starts a separate copy of the
178
- package's `dev` server; it does not read Playwright's `webServer` configuration. It is named `app-e2e`, or
179
- `<package>-app-e2e` in a workspace. Select it explicitly in the wizard or run it by name when using zero configuration.
180
- `init --yes` omits it. A dependency on the `playwright` browser library alone does not imply an E2E test setup. Separate
181
- test-only packages and cross-package server relationships need explicit configuration. See [Playwright](#playwright)
182
- before running an E2E server alongside your app.
201
+ A dependency on the `playwright` browser library alone doesn't count as an E2E test setup. Separate test-only packages
202
+ and cross-package server relationships need explicit configuration. See [Playwright](#playwright) before running an E2E
203
+ server alongside your app.
183
204
 
184
205
  ## Domain naming
185
206
 
@@ -248,7 +269,8 @@ export default defineConfig({
248
269
  ```
249
270
 
250
271
  Use `domain: "example.com"` with `primaryName: "local"` to get the bare `local.example.com` address. Setting only
251
- `domain: "local.example.com"` retains an endpoint-name prefix, such as `shop.local.example.com`.
272
+ `domain: "local.example.com"` keeps the name template's prefix, such as `shop.local.example.com` for a detected root
273
+ app.
252
274
 
253
275
  The same convention can cover additional servers you configure:
254
276
 
@@ -407,18 +429,18 @@ Names, paths, and templates are validated when the config is loaded or resolved.
407
429
 
408
430
  Each entry in `endpoints` has these fields. Set **exactly one** of `script` or `command`.
409
431
 
410
- | Field | Type | Default or requirement | Description |
411
- | ------------- | ------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------- |
412
- | `kind` | `"app"`, `"storybook"`, or `"e2e"` | `"app"` | Endpoint purpose; the Playwright helper requires `"e2e"` |
413
- | `cwd` | `string` | `"."` | Server working directory, relative to the configuration root |
414
- | `primaryName` | `string` | `"{project}-{service}"` | Name template used in the primary checkout |
415
- | `name` | `string` | `"{project}-{worktree}-{service}"` | Name template used in a linked worktree |
416
- | `script` | Nonempty string | Required unless `command` is set | Script from `cwd`'s `package.json`; the script must exist |
417
- | `command` | Nonempty string array | Required unless `script` is set | Executable followed by arguments; each element must be nonempty and contain no NUL character |
418
- | `framework` | `"next"`, `"vite"`, `"storybook"`, or `"custom"` | `"custom"` | Selects host and port flag adaptation; it is independent of `kind` |
419
- | `env` | Record of string values | `{}` | Additional child-process environment variables; supports templates |
420
- | `auth` | String array | `[]` | Callback paths included in the `urls` output |
421
- | `tunnel` | Object | Omitted | Optional public webhook tunnel settings below |
432
+ | Field | Type | Default or requirement | Description |
433
+ | ------------- | ------------------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
434
+ | `kind` | `"app"`, `"storybook"`, or `"e2e"` | `"app"` | Endpoint purpose; the Playwright helper requires `"e2e"` |
435
+ | `cwd` | `string` | `"."` | Server working directory, relative to the configuration root |
436
+ | `primaryName` | `string` | `"{project}-{service}"` | Name template used in the primary checkout |
437
+ | `name` | `string` | `"{project}-{worktree}-{service}"` | Name template used in a linked worktree |
438
+ | `script` | Nonempty string | Required unless `command` is set | Script from `cwd`'s `package.json`; it must exist and must not call `dev-domains` or `portless` |
439
+ | `command` | Nonempty string array | Required unless `script` is set | Executable followed by arguments; each element must be nonempty and contain no NUL character |
440
+ | `framework` | `"next"`, `"vite"`, `"storybook"`, or `"custom"` | `"custom"` | Selects host and port flag adaptation; it is independent of `kind` |
441
+ | `env` | Record of string values | `{}` | Additional child-process environment variables; supports templates |
442
+ | `auth` | String array | `[]` | Callback paths included in the `urls` output |
443
+ | `tunnel` | Object | Omitted | Optional public webhook tunnel settings below |
422
444
 
423
445
  Environment keys must start with a letter or underscore and contain only letters, digits, and underscores. `PORT`,
424
446
  `HOST`, keys starting with `PORTLESS`, and keys starting with `BUILDKIT_` are reserved. Keep secrets in your environment
@@ -428,11 +450,11 @@ or your application's secret-loading mechanism rather than committing them to th
428
450
 
429
451
  These fields apply only when an endpoint has a `tunnel` object:
430
452
 
431
- | Field | Type | Default or requirement | Description |
432
- | ------------------ | --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------- |
433
- | `tunnel.command` | Nonempty string array | Required | Tunnel executable and arguments; must contain `{url}` to target the restricted local gateway |
434
- | `tunnel.paths` | Nonempty string array | Required | Exact allowed POST paths |
435
- | `tunnel.publicUrl` | HTTPS origin string | Optional | An existing stable public origin, used for display and `urls` output; it does not provision a tunnel |
453
+ | Field | Type | Default or requirement | Description |
454
+ | ------------------ | --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
455
+ | `tunnel.command` | Nonempty string array | Required | Tunnel executable and arguments; one argument must contain `{url}`, the local gateway's address, or the tunnel won't start |
456
+ | `tunnel.paths` | Nonempty string array | Required | Exact allowed POST paths |
457
+ | `tunnel.publicUrl` | HTTPS origin string | Optional | An existing stable public origin, used for display and `urls` output; it does not provision a tunnel |
436
458
 
437
459
  `auth` and `tunnel.paths` values must begin with one `/`. They cannot include query strings, fragments, backslashes,
438
460
  percent encoding, or `.` / `..` path segments. Tunnel paths are exact matches, not wildcard patterns. `tunnel.publicUrl`
@@ -468,6 +490,15 @@ For example, an endpoint can set `env: { APP_URL: "{origin}", AUTH_REDIRECT_URI:
468
490
  process environment variables are inherited. The runtime values listed above take precedence over same-named values
469
491
  inherited from the shell or supplied through `env`.
470
492
 
493
+ The server also receives a few variables for its tools:
494
+
495
+ - `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` lists the endpoint's hostnames, so Vite accepts them without allowed-hosts
496
+ configuration.
497
+ - With HTTPS, `NODE_EXTRA_CA_CERTS` points at Portless's local certificate authority, so Node.js code in the server
498
+ trusts the local origins. A value you already set is kept.
499
+ - `PORTLESS_URL` holds the origin.
500
+ - `BUILDKIT_ACTIVE` makes a nested `dev-domains run` inside the server stop with a recursion error.
501
+
471
502
  ## Server commands and frameworks
472
503
 
473
504
  Use `script` to run an existing package script, or `command` for an executable and argument array. Arguments remain
@@ -503,8 +534,8 @@ command directly, such as `command: ["vite"]` and `framework: "vite"`. Pointing
503
534
  would start the CLI again and is rejected. You do not need a second package script with a special name.
504
535
 
505
536
  Your framework still controls allowed hosts, development origins, and output directories. Add your generated hostnames
506
- to its configuration where required. When a server exits, its exit code is propagated. Custom servers must fail on a
507
- port conflict rather than silently switching ports.
537
+ to its configuration where required; Vite reads them from the environment. When a server exits, its exit code is
538
+ propagated. Custom servers must fail on a port conflict rather than silently switching ports.
508
539
 
509
540
  ## Playwright
510
541
 
@@ -533,11 +564,11 @@ export default defineConfig({
533
564
  })
534
565
  ```
535
566
 
536
- `playwrightServer(endpoint, cwd?)` loads the project from `cwd` or `process.cwd()`. It returns `use.baseURL` and a
537
- `webServer` configuration that runs the endpoint, waits up to 120 seconds, and sets `reuseExistingServer: false`. If you
538
- add other Playwright `use` or `webServer` options, merge those nested objects so you preserve the helper's values. In a
539
- monorepo, use the exact configured endpoint key, such as `web-app-e2e`, and a working directory from which the intended
540
- dev-domains config can be found.
567
+ `playwrightServer(service, cwd?)` loads the project from `cwd` or `process.cwd()`. It returns `use.baseURL` and a
568
+ `webServer` configuration that runs `dev-domains run` for the endpoint from the configuration root, waits up to 120
569
+ seconds, and sets `reuseExistingServer: false`. If you add other Playwright `use` or `webServer` options, merge those
570
+ nested objects so you preserve the helper's values. In a monorepo, use the exact configured endpoint key, such as
571
+ `web-app-e2e`, and a working directory from which the intended dev-domains config can be found.
541
572
 
542
573
  The endpoint's script must start a server, not run `playwright test`. The helper does not install Playwright or edit its
543
574
  configuration. Run `npx @buildkitgg/dev-domains setup` before the test run on a development machine.
@@ -614,11 +645,17 @@ No separate webhook subdomain is required. A quick tunnel URL may change after r
614
645
  configure a stable tunnel with your provider and optionally record its HTTPS origin in `tunnel.publicUrl`. That property
615
646
  reports an existing address; it does not reserve a domain or configure the tunnel command.
616
647
 
617
- The tunnel accepts only POST requests whose paths exactly match `tunnel.paths`. Query strings, raw request bytes, and
618
- signature headers are preserved; hop-by-hop headers and the inbound `Forwarded`, `X-Forwarded-For`, and
619
- `X-Forwarded-Host` headers are stripped. Request bodies are limited to 1 MiB, upstream requests time out after 15
620
- seconds, and payloads are not logged or stored. Your application must validate provider signatures. Providers that
621
- require a GET verification challenge need a different ingress arrangement; this gateway is POST-only.
648
+ The tunnel reaches your app through a restricted local gateway, which:
649
+
650
+ - Accepts only POST requests whose path exactly matches an entry in `tunnel.paths`, and answers anything else with 404.
651
+ - Preserves query strings, raw request bytes, and signature headers.
652
+ - Strips hop-by-hop headers and the inbound `Forwarded`, `X-Forwarded-For`, and `X-Forwarded-Host` headers.
653
+ - Rejects request bodies over 1 MiB with 413.
654
+ - Answers 502 when the app can't be reached or doesn't respond within 15 seconds, and 503 when the endpoint has stopped.
655
+ - Never logs or stores payloads.
656
+
657
+ Your application must validate provider signatures. Providers that require a GET verification challenge need a different
658
+ ingress arrangement, because this gateway is POST-only.
622
659
 
623
660
  Install and authenticate the tunnel executable separately. It runs from the configuration root and inherits the shell
624
661
  environment, rather than the endpoint's server `env` overrides. Keep credentials in the provider's login store or
@@ -627,8 +664,23 @@ running. A hosted receiver, durable delivery, and replay are not included.
627
664
 
628
665
  ## Sharing a proxy across projects
629
666
 
630
- One machine can run many endpoints through one Portless proxy, with a separate domain for each project. Keep the proxy
631
- port and TLS mode aligned. To give one project's endpoints additional aliases, configure an explicit list:
667
+ One Portless proxy can serve every project on a machine, each with its own domain: `local.example.com` and
668
+ `local.example.org` can run together on the same proxy. Starting an endpoint leaves other servers running. Projects that
669
+ share the proxy follow these rules:
670
+
671
+ - Every project must use the same proxy port and TLS setting. If the running proxy differs, startup stops with an error
672
+ and leaves the proxy running.
673
+ - Hosts synchronization is set when the proxy starts. If it started with synchronization disabled, `syncHosts: true`
674
+ cannot change that running process; coordinate proxy configuration or configure DNS yourself. Either way, every custom
675
+ hostname must resolve to loopback.
676
+ - A collision means the **complete hostname** is occupied, not just the endpoint name. A running server keeps its
677
+ hostname; choose another name if the CLI reports a collision.
678
+ - Backend ports are assigned automatically. After a port conflict, startup can run the server command up to three times,
679
+ so server commands should be safe to repeat.
680
+
681
+ `npx @buildkitgg/dev-domains doctor` helps diagnose the current state.
682
+
683
+ To give one project's endpoints additional aliases, configure an explicit list:
632
684
 
633
685
  ```ts
634
686
  // Root configuration fields, alongside project and endpoints.
@@ -641,34 +693,26 @@ proxy: {
641
693
  }
642
694
  ```
643
695
 
644
- Projects can use different domains: `local.example.com` and `local.example.org` can run together on the same proxy.
645
- Leave `proxy.domains` unset unless this project's endpoints should have additional aliases. An explicit list registers
646
- each endpoint under those suffixes only; `domain` selects its canonical origin. A collision means the **complete
647
- hostname** is occupied, not just the endpoint name.
648
-
649
- Projects sharing one proxy must agree on its port and TLS settings. Starting an endpoint leaves other servers running.
650
- DNS must resolve every custom hostname to loopback; either use Portless's hosts synchronization or configure DNS
651
- yourself. If the existing proxy was started with hosts synchronization disabled, `syncHosts: true` cannot change that
652
- running process. Coordinate proxy configuration or configure DNS separately. `npx @buildkitgg/dev-domains doctor` helps
653
- diagnose the current state.
654
-
655
- Backend ports are assigned automatically. Startup may be retried after a port conflict, so server commands should be
656
- safe to repeat. A running server keeps its hostname; choose another name if the CLI reports a collision.
696
+ An explicit list registers each endpoint under those suffixes only, and `domain` selects its canonical origin. Leave
697
+ `proxy.domains` unset unless this project's endpoints need aliases.
657
698
 
658
699
  ## CI usage
659
700
 
660
701
  Commit a configuration and use explicit endpoint names in noninteractive jobs. The Playwright helper can start a
661
702
  dedicated test server, or you can keep your existing loopback-based Playwright setup.
662
703
 
663
- For jobs that use Portless, set a job-specific `PORTLESS_STATE_DIR` and choose an unprivileged proxy port. For example,
664
- a CI config can use `proxy: { https: false, port: 8080, syncHosts: false }`. Ensure generated hostnames resolve to
665
- loopback in the runner when hosts synchronization is disabled. HTTP avoids a certificate-trust step; HTTPS requires the
666
- runner to trust the local certificate authority. Select a complete CI config through the normal file-loading rules or
667
- `--config` for CLI commands; there is no implicit environment-specific config merge.
704
+ For jobs that use Portless:
668
705
 
669
- The Playwright helper uses normal config discovery from its `cwd`; it does not accept the CLI's `--config` option. Place
670
- a CI config where that lookup finds it if you use the helper. Concurrent jobs sharing a machine also need compatible
671
- shared proxy settings or distinct proxy ports; a separate state directory alone does not free a bound port.
706
+ - Set a job-specific `PORTLESS_STATE_DIR` and choose an unprivileged proxy port. For example, a CI config can use
707
+ `proxy: { https: false, port: 8080, syncHosts: false }`.
708
+ - With hosts synchronization disabled, make sure generated hostnames resolve to loopback on the runner.
709
+ - HTTP avoids a certificate-trust step; HTTPS requires the runner to trust the local certificate authority.
710
+ - Select a complete CI config through the normal file-loading rules, or with `--config` for CLI commands. There is no
711
+ implicit environment-specific config merge.
712
+ - The Playwright helper uses normal config discovery from its `cwd` and doesn't accept the CLI's `--config` option. If
713
+ you use the helper, place the CI config where that lookup finds it.
714
+ - Concurrent jobs sharing a machine need compatible shared proxy settings or distinct proxy ports. A separate state
715
+ directory alone doesn't free a bound port.
672
716
 
673
717
  ## Command reference
674
718
 
@@ -677,7 +721,7 @@ first.
677
721
 
678
722
  | Command | Purpose | Supported project options |
679
723
  | ----------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
680
- | `npx @buildkitgg/dev-domains` | Run the default command; select an endpoint if several exist | `--cwd`, `--config` |
724
+ | `npx @buildkitgg/dev-domains` | Same as `run` with no endpoint name; select an endpoint if several exist | `--cwd`, `--config` |
681
725
  | `npx @buildkitgg/dev-domains run [endpoint]` | Start one detected or configured endpoint | `--cwd`, `--config` |
682
726
  | `npx @buildkitgg/dev-domains init` | Run the setup wizard and save `dev-domains.json` | `--cwd`, `--yes`, `--dry-run`, `--project`, `--domain` |
683
727
  | `npx @buildkitgg/dev-domains detect` | Print detected candidates as JSON, ignoring saved dev-domains config | `--cwd` |
@@ -689,26 +733,29 @@ first.
689
733
  | `npx @buildkitgg/dev-domains schema` | Print the configuration JSON Schema | None |
690
734
 
691
735
  `--cwd` defaults to the current directory. `--config` is a file path relative to `--cwd`. Use `--help` on a command for
692
- its options. `run` and `tunnel` require an endpoint name in noninteractive sessions when more than one candidate exists.
736
+ its options. `run` and `tunnel` require an endpoint name in noninteractive sessions when more than one candidate exists;
737
+ `tunnel` only offers endpoints that have a `tunnel` object. Put options after the command name.
693
738
 
694
- The CLI never rewrites package scripts. It propagates server exit codes and releases the endpoint's hostname when the
695
- server stops normally. The shared proxy stays available for other servers. After a forced termination, check `status`
696
- and stop any remaining server process you own before restarting it. `PORTLESS_STATE_DIR` can select a separate state
697
- directory; most consumers should keep the default shared state.
739
+ The CLI never rewrites package scripts. It propagates server exit codes, exits with 1 on an error and 130 when you
740
+ cancel a prompt, and releases the endpoint's hostname when the server stops normally. The shared proxy stays available
741
+ for other servers. After a forced termination, check `status` and stop any remaining server process you own before
742
+ restarting it. `PORTLESS_STATE_DIR` can select a separate state directory; most consumers should keep the default shared
743
+ state.
698
744
 
699
745
  ## Troubleshooting
700
746
 
701
- | Symptom | What to check |
702
- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
703
- | No endpoints were detected | Run `detect`; check the app script conventions or add an explicit `command` / `script` endpoint |
704
- | A wrapped script is rejected | Set `command` to the server executable, or reference a script that starts the server directly |
705
- | An endpoint name is ambiguous | Use `urls` for configured names or `detect` for discovered names, then pass one to `run` |
706
- | Multiple configs or Storybook candidates were found | Keep one dev-domains config per directory; select the intended Storybook script or config directory explicitly |
707
- | The wrong package manager is used | In a saved config, set `packageManager`; during discovery, check the root declaration and conflicting lockfiles |
708
- | A hostname is already in use | Check `status`, then choose a distinct name or stop the server you own; do not take over another process's route |
709
- | The proxy has different settings | Align port and TLS settings with the existing shared proxy before restarting your endpoint |
710
- | The hostname does not resolve or HTTPS is untrusted | Run `doctor`; check loopback DNS or hosts synchronization and complete Portless certificate setup |
711
- | The framework rejects the hostname | Configure its allowed hosts or development origins for your generated domains |
712
- | App and E2E servers conflict despite different ports | Configure separate framework build/output directories or caches |
713
- | A webhook returns 404 | Confirm it is a POST request to an exact allowed path; GET verification challenges are not supported by this gateway |
714
- | A webhook cannot reach the app | Start the target endpoint first, verify the provider's current public URL, and check the tunnel process |
747
+ | Symptom | What to check |
748
+ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
749
+ | No endpoints were detected | Run `detect`; check the app script conventions or add an explicit `command` / `script` endpoint |
750
+ | A wrapped script is rejected | Set `command` to the server executable, or reference a script that starts the server directly |
751
+ | An endpoint name is ambiguous | Use `urls` for configured names or `detect` for discovered names, then pass one to `run` |
752
+ | Multiple configs or Storybook candidates were found | Keep one dev-domains config per directory; select the intended Storybook script or config directory explicitly |
753
+ | The wrong package manager is used | In a saved config, set `packageManager`; during discovery, check the root declaration and conflicting lockfiles |
754
+ | A hostname is already in use | Check `status`, then choose a distinct name or stop the server you own; do not take over another process's route |
755
+ | The proxy has different settings | Align port and TLS settings with the existing shared proxy before restarting your endpoint |
756
+ | The hostname does not resolve or HTTPS is untrusted | Run `doctor`; check loopback DNS or hosts synchronization and complete Portless certificate setup |
757
+ | The framework rejects the hostname | Configure its allowed hosts or development origins for your generated domains |
758
+ | App and E2E servers conflict despite different ports | Configure separate framework build/output directories or caches |
759
+ | A webhook returns 404 | Confirm it is a POST request to an exact allowed path; GET verification challenges are not supported by this gateway |
760
+ | A webhook returns 502, 503, or 413 | 502: the app couldn't be reached or didn't respond within 15 seconds; 503: start the endpoint again; 413: the body exceeds 1 MiB |
761
+ | A webhook cannot reach the app | Start the target endpoint first, verify the provider's current public URL, and check the tunnel process |
@@ -123,3 +123,14 @@ export declare const commands: {
123
123
  }>;
124
124
  schema: import("citty").CommandDef<import("citty").ArgsDef>;
125
125
  };
126
+ export declare const cli: import("citty").CommandDef<{
127
+ readonly cwd: {
128
+ readonly type: "string";
129
+ readonly description: "Project directory";
130
+ readonly default: ".";
131
+ };
132
+ readonly config: {
133
+ readonly type: "string";
134
+ readonly description: "Explicit config file (relative to cwd)";
135
+ };
136
+ }>;
@@ -1,3 +1,5 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { defineCommand as defineRootCommand } from "citty";
1
3
  import { z } from "zod";
2
4
  import { loadProject } from "../config/load.js";
3
5
  import { configSchema } from "../config/schema.js";
@@ -97,3 +99,14 @@ export const commands = {
97
99
  }
98
100
  })
99
101
  };
102
+ const { version } = z
103
+ .object({ version: z.string() })
104
+ .parse(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")));
105
+ export const cli = defineRootCommand({
106
+ meta: { name: "dev-domains", version, description: "Stable local domains for every app and checkout" },
107
+ // Without a command name the CLI runs `run`. Citty only skips an option's separate value (`--cwd apps/web`) when
108
+ // looking for a command name if the option is declared here.
109
+ args: location,
110
+ default: "run",
111
+ subCommands: commands
112
+ });
package/dist/cli/main.js CHANGED
@@ -1,13 +1,4 @@
1
1
  #!/usr/bin/env node
2
- import { readFileSync } from "node:fs";
3
- import { defineCommand, runMain } from "citty";
4
- import { z } from "zod";
5
- import { commands } from "./commands.js";
6
- const { version } = z
7
- .object({ version: z.string() })
8
- .parse(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")));
9
- await runMain(defineCommand({
10
- meta: { name: "dev-domains", version, description: "Stable local domains for every app and checkout" },
11
- default: "run",
12
- subCommands: commands
13
- }));
2
+ import { runMain } from "citty";
3
+ import { cli } from "./commands.js";
4
+ await runMain(cli);
@@ -6,7 +6,8 @@ import { discoverProjects } from "./discovery.js";
6
6
  import { slug } from "./identity.js";
7
7
  import { readManifest, workspaceList } from "./manifest.js";
8
8
  import { detectPackageManager } from "./package-manager.js";
9
- const wrappers = /\b(dev-domains|portless|turbo|run-p|concurrently)\b/;
9
+ // `turbo` counts only as a command (`turbo dev`, `pnpm turbo dev`); `next dev --turbo` is still an app server.
10
+ const wrappers = /\b(?:dev-domains|portless|run-p|concurrently)\b|(?:^|[\s/;&|(])turbo(?=$|[\s@;&|)])/;
10
11
  const storybookDev = /\bstorybook\s+dev\b/;
11
12
  const playwrightTest = /\bplaywright\s+test\b/;
12
13
  function frameworkFor(source) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@buildkitgg/dev-domains",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },