nscout 0.2.1 → 0.2.2

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.
Files changed (76) hide show
  1. package/.env.example +37 -21
  2. package/CHANGELOG.md +184 -0
  3. package/README.md +300 -106
  4. package/config/nscout.json +279 -0
  5. package/dist/ai/parse.d.ts +5 -0
  6. package/dist/ai/parse.js +13 -0
  7. package/dist/ai/parse.js.map +1 -0
  8. package/dist/ai/providers/anthropic.js +11 -14
  9. package/dist/ai/providers/anthropic.js.map +1 -1
  10. package/dist/ai/providers/openai.js +10 -12
  11. package/dist/ai/providers/openai.js.map +1 -1
  12. package/dist/ai/providers/stub.d.ts +1 -0
  13. package/dist/ai/providers/stub.js +5 -3
  14. package/dist/ai/providers/stub.js.map +1 -1
  15. package/dist/ai/registry.js +9 -3
  16. package/dist/ai/registry.js.map +1 -1
  17. package/dist/ai/suggest.d.ts +1 -0
  18. package/dist/ai/suggest.js +21 -18
  19. package/dist/ai/suggest.js.map +1 -1
  20. package/dist/cli/index.js +78 -25
  21. package/dist/cli/index.js.map +1 -1
  22. package/dist/config/format.d.ts +2 -0
  23. package/dist/config/format.js +5 -0
  24. package/dist/config/format.js.map +1 -0
  25. package/dist/config/load.d.ts +6 -0
  26. package/dist/config/load.js +94 -0
  27. package/dist/config/load.js.map +1 -0
  28. package/dist/config/schema.d.ts +180 -0
  29. package/dist/config/schema.js +2 -0
  30. package/dist/config/schema.js.map +1 -0
  31. package/dist/registries/adapters.d.ts +8 -0
  32. package/dist/registries/adapters.js +23 -11
  33. package/dist/registries/adapters.js.map +1 -1
  34. package/dist/registries/domains.d.ts +11 -0
  35. package/dist/registries/domains.js +167 -0
  36. package/dist/registries/domains.js.map +1 -0
  37. package/dist/registries/http.d.ts +7 -0
  38. package/dist/registries/http.js +68 -0
  39. package/dist/registries/http.js.map +1 -0
  40. package/dist/registries/index.d.ts +2 -3
  41. package/dist/registries/index.js +11 -8
  42. package/dist/registries/index.js.map +1 -1
  43. package/dist/registries/whois.d.ts +3 -0
  44. package/dist/registries/whois.js +20 -0
  45. package/dist/registries/whois.js.map +1 -0
  46. package/dist/render/json.d.ts +2 -2
  47. package/dist/render/json.js +4 -2
  48. package/dist/render/json.js.map +1 -1
  49. package/dist/render/table.d.ts +4 -2
  50. package/dist/render/table.js +34 -27
  51. package/dist/render/table.js.map +1 -1
  52. package/dist/types.d.ts +2 -2
  53. package/package.json +21 -15
  54. package/.env +0 -71
  55. package/dist/config/defaults.d.ts +0 -43
  56. package/dist/config/defaults.js +0 -51
  57. package/dist/config/defaults.js.map +0 -1
  58. package/dist/registries/dockerhub.d.ts +0 -2
  59. package/dist/registries/dockerhub.js +0 -20
  60. package/dist/registries/dockerhub.js.map +0 -1
  61. package/dist/registries/github.d.ts +0 -2
  62. package/dist/registries/github.js +0 -50
  63. package/dist/registries/github.js.map +0 -1
  64. package/dist/registries/npm.d.ts +0 -2
  65. package/dist/registries/npm.js +0 -20
  66. package/dist/registries/npm.js.map +0 -1
  67. package/dist/registries/pypi.d.ts +0 -2
  68. package/dist/registries/pypi.js +0 -20
  69. package/dist/registries/pypi.js.map +0 -1
  70. package/dist/registries/rdap.d.ts +0 -2
  71. package/dist/registries/rdap.js +0 -44
  72. package/dist/registries/rdap.js.map +0 -1
  73. package/ui/index.html +0 -12
  74. package/ui/package.json +0 -27
  75. package/ui/server.ts +0 -53
  76. package/ui/vite.config.ts +0 -14
package/README.md CHANGED
@@ -2,13 +2,17 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/nscout)](https://www.npmjs.com/package/nscout)
4
4
 
5
- Scout a name across npm, GitHub, PyPI, and domain registries before you commit to it.
5
+ Scout a name across package registries, GitHub, Docker Hub, and domains before you commit to it.
6
6
  Optional AI suggest mode generates candidates from a description, then runs them all
7
7
  through the same check pipeline.
8
8
 
9
+ Every registry, URL, TLD, WHOIS server, symbol and AI prompt lives in one JSON config
10
+ file. Adding a registry is a config change, not a code change.
11
+
9
12
  ## Requirements
10
13
 
11
14
  - Node 24+
15
+ - Outbound HTTPS (registries, RDAP) and TCP port 43 (WHOIS for TLDs without RDAP)
12
16
  - Optional: OpenAI or Anthropic API key for `--suggest` mode
13
17
 
14
18
  ## Install
@@ -28,30 +32,46 @@ pnpm build
28
32
 
29
33
  **Before first use, create your `.env` file:**
30
34
 
35
+ macOS / Linux:
36
+
31
37
  ```bash
32
38
  cp .env.example .env
33
39
  ```
34
40
 
35
- Edit `.env` to add API keys or change defaults. If no `.env` is found, nscout warns on startup and runs with built-in defaults.
41
+ Windows (PowerShell):
42
+
43
+ ```powershell
44
+ Copy-Item .env.example .env
45
+ ```
46
+
47
+ Edit `.env` to add API keys or override defaults. nscout reads `.env` from the current
48
+ working directory. If no `.env` is found, nscout warns on startup and runs with the
49
+ defaults from `config/nscout.json`.
36
50
 
37
51
  ## Quick start
38
52
 
39
- Check names directly:
53
+ Check names with the default registries and TLDs:
40
54
 
41
55
  ```bash
42
56
  nscout myapp mytool myproject
43
57
  ```
44
58
 
45
- Check only specific registries (e.g. a JS package — skip PyPI and domains):
59
+ Check only specific registries (e.g. a JS package):
46
60
 
47
61
  ```bash
48
62
  nscout myapp mytool -r npm,github
49
63
  ```
50
64
 
65
+ Check registries that are not on by default:
66
+
67
+ ```bash
68
+ nscout myapp -r crates,rubygems,homebrew,nuget
69
+ ```
70
+
51
71
  Check with custom TLDs:
52
72
 
53
73
  ```bash
54
- nscout myapp -d .com,.net,.ai
74
+ nscout myapp -d .com,.fi,.de,.eu
55
75
  ```
56
76
 
57
77
  Show error details and expiry dates:
@@ -86,57 +106,104 @@ nscout myapp mytool --json | jq '.[] | select(.checks | all(.status == "availabl
86
106
 
87
107
  ## Usage
88
108
 
89
- ```
90
- nscout [names...] [options]
109
+ ```text
110
+ Usage: nscout [options] [names...]
91
111
 
92
- -r, --registries <list> npm,github,pypi,domains (default: all)
93
- -d, --domains <list> TLDs to probe (default: .com,.dev,.io,.sh)
112
+ Options:
113
+ -r, --registries <list> registries to check
114
+ (npm,github,pypi,dockerhub,crates,rubygems,homebrew,nuget,domains)
115
+ (default: "npm,github,pypi,dockerhub,domains")
116
+ -d, --domains <list> TLDs to probe (comma-separated) (default:
117
+ ".com,.net,.org,.io,.dev,.app,.ai,.co,.sh")
94
118
  -s, --suggest <description> AI-generate candidate names from a description
95
- --style <style> claw | short | portmanteau | free (default: free)
96
- -n, --limit <n> number of AI suggestions to generate (default: 10)
97
- -c, --concurrency <n> parallel name checks (default: 4)
98
- -t, --timeout <ms> per-request timeout in ms (default: 8000)
99
- --json print JSON instead of a table
100
- --no-color disable ANSI colors
101
- -v, --verbose print extra detail: errors and expiry dates
119
+ --style <style> naming style: claw, short, portmanteau, free
120
+ (default: "free")
121
+ -n, --limit <n> number of AI suggestions to generate (default:
122
+ "10")
123
+ -c, --concurrency <n> parallel name checks (default: "4")
124
+ -t, --timeout <ms> per-request timeout in ms (default: "8000")
125
+ --json print JSON instead of a table
126
+ --no-color disable ANSI colors
127
+ -v, --verbose print extra detail (errors, expiry dates)
128
+ --list-registries list available registries and exit
129
+ --print-config print the resolved configuration as JSON and exit
130
+ -h, --help display help for command
102
131
  ```
103
132
 
133
+ The registry list, defaults, styles and every description in the help text come from
134
+ the config file.
135
+
104
136
  ## Output
105
137
 
106
- Each column is one registry. Each cell shows availability:
138
+ Each column is one registry or TLD. Each cell shows availability. Real output:
107
139
 
108
- ```
109
- name npm github pypi domain:.com domain:.dev domain:.io domain:.sh
110
- ------------------------------------------------------------------------------
111
- myapp ✓ ✓ ✓ ✗ ✓ ✓ ✓
112
- mytool ✗ ✓ ✓ ✓ ✓ ✓ ✓
113
- mylib ✓ ✗ ✗ ✗ ✓ ✓ ✓
140
+ ```text
141
+ name npm github pypi dockerhub domain:.com domain:.net domain:.org domain:.io domain:.dev domain:.app domain:.ai domain:.co domain:.sh
142
+ ---------------------------------------------------------------------------------------------------------------------------------------------------------------
143
+ myapp ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗
144
+ mytool ✗ ✗ ✓ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✗ ✓
145
+ zzqqxxnotreal123 ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
114
146
 
115
147
  legend: ✓ available ✗ taken ⚠ reserved ⏳ expiring ? unknown ! error
116
148
  ```
117
149
 
118
150
  | Symbol | Meaning |
119
- |--------|---------|
151
+ | --- | --- |
120
152
  | ✓ | Name or domain is available |
121
153
  | ✗ | Name or domain is taken |
122
154
  | ⚠ | Domain is reserved by the registry |
123
155
  | ⏳ | Domain is expiring within 30 days |
124
- | ? | Could not determine status |
156
+ | ? | Could not determine status (unexpected response, rate limit, no RDAP or WHOIS server) |
125
157
  | ! | Request failed or timed out |
126
158
 
127
- Pass `-v` to show error details and expiry dates below the table.
159
+ Pass `-v` to show the reason for every `?` and `!` below the table.
128
160
 
129
161
  ## What it checks
130
162
 
131
- - **npm**: exact package match on the public registry
132
- - **GitHub**: checks both user and organization namespaces at `github.com/{name}` — taken if either exists
133
- - **PyPI**: exact package match
134
- - **Docker Hub**: checks official library namespace at `hub.docker.com/r/library/{name}`
135
- - **Domains via RDAP**: `.com`, `.dev`, `.io`, `.sh` by default
163
+ Run `nscout --list-registries` to see the registries in your config. Real output:
164
+
165
+ ```text
166
+ * npm npm package
167
+ * github GitHub user or organization
168
+ * pypi PyPI package
169
+ * dockerhub Docker Hub official image, user or organization
170
+ crates crates.io (Rust) crate
171
+ rubygems RubyGems gem
172
+ homebrew Homebrew formula or cask
173
+ nuget NuGet package
174
+ * domains Domain names via RDAP, with WHOIS for TLDs without RDAP
136
175
 
137
- All checks run in parallel per name. Names run with bounded concurrency. RDAP
138
- distinguishes available from taken from reserved from expiring, which most domain
139
- checkers collapse into one binary answer.
176
+ * checked by default
177
+ ```
178
+
179
+ | Registry | Endpoint | Taken when |
180
+ | --- | --- | --- |
181
+ | `npm` | `registry.npmjs.org/{name}` | the package exists |
182
+ | `github` | `api.github.com/users/{name}`, `api.github.com/orgs/{name}` | a user or an organization exists |
183
+ | `pypi` | `pypi.org/pypi/{name}/json` | the package exists |
184
+ | `dockerhub` | `hub.docker.com/v2/repositories/library/{name}`, `/v2/users/{name}`, `/v2/orgs/{name}` | an official image, user or organization exists |
185
+ | `crates` | `crates.io/api/v1/crates/{name}` | the crate exists |
186
+ | `rubygems` | `rubygems.org/api/v1/gems/{name}.json` | the gem exists |
187
+ | `homebrew` | `formulae.brew.sh/api/formula/{name}.json`, `/api/cask/{name}.json` | a formula or cask exists |
188
+ | `nuget` | `api.nuget.org/v3-flatcontainer/{name}/index.json` | the package exists |
189
+
190
+ Transient HTTP errors (429, 500, 502, 503, 504) are retried before a check reports `?`.
191
+
192
+ ### Domains
193
+
194
+ Each TLD is checked in this order:
195
+
196
+ 1. **RDAP.** nscout downloads the IANA RDAP bootstrap (`data.iana.org/rdap/dns.json`)
197
+ once per run and queries the TLD's own RDAP server. RDAP distinguishes available,
198
+ taken, reserved and expiring, which most domain checkers collapse into one answer.
199
+ 2. **WHOIS.** TLDs without RDAP (for example `.io`, `.co`, `.sh`, `.me`, `.de`, `.eu`,
200
+ `.se`, `.us`, `.jp`) are checked over WHOIS. Known TLDs use the server, query format
201
+ and "not found" pattern from the config. Other TLDs get their WHOIS server from
202
+ `whois.iana.org`.
203
+ 3. If a TLD has neither, the result is `?` with the reason shown under `-v`.
204
+
205
+ Verified against real registries for `.com .net .org .io .dev .app .ai .co .sh .me .de
206
+ .eu .fi .se .us .xyz`.
140
207
 
141
208
  ## AI suggest mode
142
209
 
@@ -147,66 +214,164 @@ nscout --suggest "rss reader with AI digest" --style claw -n 8
147
214
  ```
148
215
 
149
216
  Without a key, `--suggest` falls back to a deterministic stub and prints a warning
150
- to stderr. The CLI still runs end-to-end. The provider adapter pattern supports any
151
- LLM: OpenAI, Anthropic, or any future provider registered via the adapter interface.
217
+ to stderr. The CLI still runs end-to-end. The prompt template, styles, models, effort
218
+ and token limit are in the config file.
152
219
 
153
- ## Configuration
154
-
155
- All configuration is through environment variables in `.env`. Copy `.env.example` to `.env` and edit as needed. All values have built-in defaults so only set what you want to change.
220
+ Default models: `claude-haiku-5-5` (Anthropic) and `gpt-6-luna` (OpenAI), both with
221
+ effort `low`. Both models reason before answering, and reasoning counts toward
222
+ `ai.maxTokens` (default 16000). You are billed only for the tokens used.
156
223
 
157
- ### Registries
224
+ ## Configuration
158
225
 
159
- | Variable | Default | What it does |
160
- |---|---|---|
161
- | `NSCOUT_REGISTRIES` | `npm,github,pypi,domains,dockerhub` | Registries to check by default |
162
- | `NSCOUT_DOMAINS` | `.com,.dev,.io,.sh` | TLDs to check when domains registry is enabled |
226
+ Configuration is layered. Each layer overrides the one before it:
163
227
 
164
- ### Performance
228
+ 1. **`config/nscout.json`**: built-in config shipped with the package. All defaults,
229
+ registries, URLs, TLDs, WHOIS servers, retry settings, symbols, colors, table layout,
230
+ AI prompts and every user-facing message.
231
+ 2. **Your config file**: a JSON file named in `NSCOUT_CONFIG`. It is merged over the
232
+ built-in config, so it only needs the keys you add or change. Objects merge key by
233
+ key; arrays replace.
234
+ 3. **Environment variables**: from `.env` or the shell (table below).
235
+ 4. **CLI flags**.
165
236
 
166
- | Variable | Default | What it does |
167
- |---|---|---|
168
- | `NSCOUT_CONCURRENCY` | `4` | Number of names checked in parallel |
169
- | `NSCOUT_TIMEOUT` | `8000` | Per-request timeout in milliseconds |
237
+ Print the final merged config:
170
238
 
171
- ### AI suggest
239
+ ```bash
240
+ nscout --print-config
241
+ ```
172
242
 
173
- | Variable | Default | What it does |
174
- |---|---|---|
175
- | `NSCOUT_LIMIT` | `10` | Number of name candidates to generate with `--suggest` |
176
- | `NSCOUT_STYLE` | `free` | Default naming style: `free`, `claw`, `short`, `portmanteau` |
177
- | `NSCOUT_AI_MAX_TOKENS` | `512` | Maximum tokens returned by the AI provider |
178
- | `NSCOUT_AI_PROVIDER` | auto | Force a specific provider: `openai` or `anthropic`. Auto-selects if not set. |
243
+ ### Environment variables
244
+
245
+ Empty variables keep the value from the config file.
246
+
247
+ | Variable | Config path | What it does |
248
+ | --- | --- | --- |
249
+ | `NSCOUT_CONFIG` | | Path to your own JSON config file |
250
+ | `NSCOUT_REGISTRIES` | `defaults.registries` | Registries to check by default |
251
+ | `NSCOUT_DOMAINS` | `defaults.domains` | TLDs to check when the domains registry is enabled |
252
+ | `NSCOUT_USER_AGENT` | `userAgent` | User-Agent for every HTTP request |
253
+ | `NSCOUT_CONCURRENCY` | `defaults.concurrency` | Number of names checked in parallel |
254
+ | `NSCOUT_TIMEOUT` | `defaults.timeout` | Per-request timeout in milliseconds |
255
+ | `NSCOUT_LIMIT` | `defaults.limit` | Number of name candidates to generate with `--suggest` |
256
+ | `NSCOUT_STYLE` | `defaults.style` | Default naming style |
257
+ | `NSCOUT_AI_PROVIDER` | `ai.provider` | Force a provider: `openai` or `anthropic`. Auto-selects if not set |
258
+ | `NSCOUT_AI_MAX_TOKENS` | `ai.maxTokens` | Output token ceiling for the AI provider, reasoning included |
179
259
  | `OPENAI_API_KEY` | | Enables OpenAI-backed suggestions |
180
- | `OPENAI_MODEL` | `gpt-4.1-mini` | OpenAI model ID |
260
+ | `OPENAI_MODEL` | `ai.providers.openai.model` | OpenAI model ID |
261
+ | `OPENAI_EFFORT` | `ai.providers.openai.effort` | OpenAI reasoning effort |
181
262
  | `ANTHROPIC_API_KEY` | | Enables Anthropic-backed suggestions |
182
- | `ANTHROPIC_MODEL` | `claude-haiku-4-5-20251001` | Anthropic model ID |
263
+ | `ANTHROPIC_MODEL` | `ai.providers.anthropic.model` | Anthropic model ID |
264
+ | `ANTHROPIC_EFFORT` | `ai.providers.anthropic.effort` | Anthropic effort level |
265
+ | `GITHUB_TOKEN` | | Raises the GitHub API rate limit from 60 to 5000 req/hr |
266
+ | `NSCOUT_RDAP_RETRY_COUNT` | `domains.rdap.retryCount` | Retry attempts on non-404 RDAP errors |
267
+ | `NSCOUT_RDAP_RETRY_DELAY_MS` | `domains.rdap.retryDelayMs` | Delay between RDAP retries |
268
+ | `NSCOUT_EXPIRING_THRESHOLD_DAYS` | `domains.expiringThresholdDays` | Domains expiring within this many days show as expiring |
269
+ | `PORT` | `port` in `ui/ui.config.json` | Port for the nscout-ui web server |
270
+ | `NSCOUT_BIN` | `bin` in `ui/ui.config.json` | nscout binary for the web UI |
271
+
272
+ The mapping from variable to config path is itself in the `env` section of the config file.
273
+
274
+ ### Messages
275
+
276
+ Every text nscout prints is in the `messages` section of `config/nscout.json`: help
277
+ descriptions, warnings, errors and the details shown with `-v`. Placeholders in braces
278
+ are filled at runtime. To change or translate a message, override it in your
279
+ `NSCOUT_CONFIG` file:
280
+
281
+ ```json
282
+ {
283
+ "messages": {
284
+ "cli": { "unknownRegistry": "Varoitus: tuntematon rekisteri \"{registry}\" ohitettiin." }
285
+ }
286
+ }
287
+ ```
183
288
 
184
- ### GitHub
289
+ The web UI texts are in the `messages` section of `ui/ui.config.json`.
290
+
291
+ ### Adding a registry
292
+
293
+ Any registry that answers a name lookup with a distinct HTTP status can be added
294
+ without code. Create a JSON file:
295
+
296
+ ```json
297
+ {
298
+ "registries": {
299
+ "pubdev": {
300
+ "type": "http",
301
+ "description": "pub.dev (Dart/Flutter) package",
302
+ "urls": ["https://pub.dev/api/packages/{name}"],
303
+ "taken": [200],
304
+ "available": [404]
305
+ }
306
+ }
307
+ }
308
+ ```
185
309
 
186
- | Variable | Default | What it does |
187
- |---|---|---|
188
- | `GITHUB_TOKEN` | | Raises GitHub API rate limit from 60 to 5000 req/hr |
310
+ Point `NSCOUT_CONFIG` at it, then use the registry like any other:
189
311
 
190
- ### RDAP (domain checks)
312
+ macOS / Linux:
191
313
 
192
- | Variable | Default | What it does |
193
- |---|---|---|
194
- | `NSCOUT_RDAP_RETRY_COUNT` | `1` | Retry attempts on non-404 RDAP errors |
195
- | `NSCOUT_RDAP_RETRY_DELAY_MS` | `600` | Delay in milliseconds between RDAP retries |
196
- | `NSCOUT_EXPIRING_THRESHOLD_DAYS` | `30` | Domains expiring within this many days show as expiring |
314
+ ```bash
315
+ export NSCOUT_CONFIG=~/nscout.config.json
316
+ nscout http zzqqxxnotreal123 -r pubdev,npm
317
+ ```
197
318
 
198
- ### Web UI
319
+ Windows (PowerShell):
199
320
 
200
- | Variable | Default | What it does |
201
- |---|---|---|
202
- | `PORT` | `3000` | Port for the nscout-ui web server |
203
- | `NSCOUT_BIN` | `nscout` | Path to the nscout binary. Use `node ../dist/cli/index.js` if not installed globally |
321
+ ```powershell
322
+ $env:NSCOUT_CONFIG = "$HOME\nscout.config.json"
323
+ nscout http zzqqxxnotreal123 -r pubdev,npm
324
+ ```
325
+
326
+ Real output:
327
+
328
+ ```text
329
+ name pubdev npm
330
+ -----------------------------
331
+ http ✗ ✗
332
+ zzqqxxnotreal123 ✓ ✓
333
+
334
+ legend: ✓ available ✗ taken ⚠ reserved ⏳ expiring ? unknown ! error
335
+ ```
336
+
337
+ Fields for `"type": "http"` registries:
338
+
339
+ | Field | Required | What it does |
340
+ | --- | --- | --- |
341
+ | `urls` | yes | One or more URLs. `{name}` is replaced with the URL-encoded name |
342
+ | `taken` | yes | HTTP statuses that mean taken. Taken if **any** URL returns one |
343
+ | `available` | yes | HTTP statuses that mean available. Available only if **every** URL returns one |
344
+ | `description` | no | Shown in `--list-registries` and the web UI |
345
+ | `labels` | no | Names for each URL, used in `-v` details (e.g. `["user", "org"]`) |
346
+ | `headers` | no | Extra request headers |
347
+ | `auth` | no | `{ "env": "TOKEN_VAR", "header": "Authorization", "prefix": "Bearer " }`. Header is sent only when the variable is set |
348
+ | `retry` | no | `{ "statuses": [...], "count": n, "delayMs": n }`. Overrides the global `http.retry` |
349
+
350
+ To support a new domain TLD that has no RDAP and a non-standard WHOIS reply, add it
351
+ under `domains.whois.servers` with its `server`, optional `query` format and
352
+ `availablePatterns` (case-insensitive regular expressions).
204
353
 
205
354
  ## Web UI
206
355
 
207
- nscout includes a web interface in the `ui/` folder. It calls the nscout CLI and displays results in the browser.
356
+ nscout includes a web interface in the `ui/` folder. It reads the registry list,
357
+ defaults and symbols from the nscout config and runs the nscout CLI for each check.
358
+ It is not part of the npm package.
359
+
360
+ UI settings are in `ui/ui.config.json`:
208
361
 
209
- ### Requirements
362
+ | Key | Default | What it does |
363
+ | --- | --- | --- |
364
+ | `host` | `localhost` | Interface the server listens on, also used by the dev proxy |
365
+ | `port` | `3000` | Server port, also used by the dev proxy. Overridden by `PORT` |
366
+ | `bin` | `nscout` | nscout binary the server runs. Overridden by `NSCOUT_BIN` |
367
+ | `staticDir` | `dist/app` | Build output folder, served by the server |
368
+ | `apiPrefix` | `/api` | Path prefix of the API routes |
369
+ | `binArgSeparator` | `" "` | Separator between the binary and its arguments in `bin` |
370
+ | `envFile` | `../.env` | Dotenv file the server reads |
371
+ | `nameSeparatorPattern` | `\s+` | Regular expression that splits the name input |
372
+ | `messages` | | Every text shown in the web UI |
373
+
374
+ ### Web UI requirements
210
375
 
211
376
  - nscout built or installed globally
212
377
  - `.env` configured (same file as CLI)
@@ -217,10 +382,10 @@ nscout includes a web interface in the `ui/` folder. It calls the nscout CLI and
217
382
  cd ui
218
383
  pnpm install
219
384
  pnpm build
220
- pnpm tsx server.ts
385
+ pnpm start
221
386
  ```
222
387
 
223
- Open `http://localhost:3000`.
388
+ Open `http://localhost:3000` (or the port you set).
224
389
 
225
390
  In development (live reload):
226
391
 
@@ -228,58 +393,83 @@ In development (live reload):
228
393
  pnpm dev
229
394
  ```
230
395
 
231
- The UI runs on the port set in `PORT` (default 3000). The server spawns `nscout --json` and returns results to the browser.
396
+ The server exposes `GET /api/config` and `POST /api/check`. Names are passed to the
397
+ CLI after `--`, so a name can never be read as a CLI option.
232
398
 
233
399
  ## Architecture
234
400
 
235
- nscout is built as a set of independent modules with no coupling between layers.
236
-
237
- ```
401
+ ```text
402
+ config/
403
+ nscout.json all data: registries, URLs, TLDs, WHOIS servers, retries,
404
+ symbols, colors, AI prompts, env variable mapping
238
405
  src/
239
- registries/ pure registry adapters, no CLI awareness
240
- adapters.ts registry map: name -> RegistryAdapter
241
- index.ts orchestrator, bounded concurrency
242
- npm.ts npm adapter
243
- github.ts GitHub adapter, checks users + orgs
244
- pypi.ts PyPI adapter
245
- rdap.ts RDAP adapter, status-aware (available/taken/reserved/expiring)
406
+ config/
407
+ load.ts loads nscout.json, merges NSCOUT_CONFIG, reads .env, applies env variables
408
+ schema.ts TypeScript types for the config
409
+ format.ts fills {placeholders} in messages
410
+ registries/
411
+ adapters.ts builds one adapter per config entry from its "type"
412
+ http.ts "http" type: any registry defined by URLs and status codes
413
+ domains.ts "domains" type: RDAP via IANA bootstrap, WHOIS fallback
414
+ whois.ts WHOIS client over TCP port 43
415
+ index.ts orchestrator, bounded concurrency
246
416
  ai/
247
- suggest.ts name generation entry point
248
- registry.ts provider adapter registry, auto-resolves available provider
249
- providers/ openai | anthropic | stub | any future adapter
417
+ suggest.ts prompt from config, provider selection
418
+ registry.ts provider registry, auto-resolves an available provider
419
+ parse.ts turns a model reply into a list of names
420
+ providers/ openai | anthropic | stub
250
421
  render/
251
- table.ts terminal table with ANSI color
252
- json.ts JSON output
422
+ table.ts terminal table, symbols and colors from config
423
+ json.ts JSON output
253
424
  cli/
254
- index.ts CLI entry point, Commander wiring
255
- config/
256
- defaults.ts all defaults, URLs, symbols, and env vars in one place
257
- types.ts shared interfaces: RegistryAdapter, CheckResult, RunOptions, NameResult
425
+ index.ts CLI entry point, Commander wiring
426
+ types.ts shared interfaces: RegistryAdapter, CheckResult, RunOptions, NameResult
427
+ ui/
428
+ ui.config.json UI settings and texts: host, port, binary, build folder, API prefix, messages
429
+ ui-config.ts loads ui.config.json and applies PORT and NSCOUT_BIN
430
+ server.ts Hono server: GET /api/config, POST /api/check
431
+ src/App.vue Vue frontend
432
+ tests/ Vitest tests, mirroring src/, plus CLI tests in tests/cli/
258
433
  ```
259
434
 
260
435
  Design rules:
261
436
 
262
- - All registry adapters implement `RegistryAdapter` from `types.ts`. Adding a new registry requires only a new file and one line in `adapters.ts`.
263
- - All hardcoded values live in `config/defaults.ts`: URLs, headers, symbols, retry counts, timeouts, AI token limits. Nothing is hardcoded in logic files.
264
- - All timeouts, TLDs, concurrency limits, AI provider, model IDs, and display symbols come from config or environment variables.
265
- - Each module is independently testable and independently usable.
437
+ - Data and text live in `config/nscout.json` (CLI) and `ui/ui.config.json` (web UI).
438
+ Source files contain logic only: no URLs, TLDs, status codes, ports, symbols, table
439
+ layout, model IDs, prompts or user-facing messages. What remains in code are
440
+ identifiers the config refers to: option flags, registry type names, status names.
441
+ - A registry is a config entry with a `type`. The `http` type covers any registry that
442
+ answers with HTTP status codes. Code is needed only for a new `type`, registered in
443
+ `ADAPTER_TYPES` in `src/registries/adapters.ts`.
444
+ - Every adapter implements `RegistryAdapter` from `types.ts` and returns `CheckResult[]`.
445
+ - Tests make no network calls: the `http` type is tested with a stubbed global `fetch`,
446
+ the `domains` type with injected `fetch` and WHOIS clients, and the CLI tests use only
447
+ options that need no network.
266
448
  - Unknown registry names passed via `--registries` print a warning to stderr and are skipped.
267
- - When no AI provider is configured, `--suggest` falls back to stub and warns to stderr.
449
+
450
+ ## Development
451
+
452
+ ```bash
453
+ pnpm test # Vitest
454
+ pnpm typecheck # tsc --noEmit
455
+ pnpm check # Biome lint and format check for src and tests
456
+ pnpm build # compile to dist/
457
+ ```
268
458
 
269
459
  ## Notes on the lane
270
460
 
271
461
  There is a comprehensive incumbent in this space: `bradtraversy/namescout-cli`
272
462
  plus a website at namescout.dev, shipped May 2026. It checks more surfaces
273
- (Docker Hub, VS Code Marketplace, Homebrew, six TLDs, etc.) and scores names.
274
- `nscout` is intentionally smaller and built around Claw conventions: fast,
275
- focused, and the AI suggest mode is the headline that differentiates it.
463
+ (VS Code Marketplace and others) and scores names. `nscout` is intentionally smaller
464
+ and built around Claw conventions: fast, focused, config-driven, and the AI suggest
465
+ mode is the headline that differentiates it.
276
466
 
277
467
  ## Roadmap
278
468
 
279
469
  - [x] Docker Hub check.
470
+ - [x] Homebrew check.
280
471
  - [ ] VS Code Marketplace check.
281
472
 
282
-
283
473
  ## OpenClaw
284
474
 
285
475
  nscout works standalone or as an OpenClaw skill. Once installed globally, your
@@ -293,6 +483,10 @@ agent or script can parse and act on.
293
483
  To use `--suggest` through your OpenClaw agent's configured LLM instead of a
294
484
  separate API key, configure `NSCOUT_AI_PROVIDER` in your `.env`.
295
485
 
486
+ ## Changelog
487
+
488
+ See [CHANGELOG.md](CHANGELOG.md).
489
+
296
490
  ## License
297
491
 
298
492
  MIT. See [LICENSE](LICENSE).