nscout 0.1.3 → 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 (71) hide show
  1. package/.env.example +44 -18
  2. package/CHANGELOG.md +184 -0
  3. package/README.md +325 -98
  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/dist/config/defaults.d.ts +0 -43
  55. package/dist/config/defaults.js +0 -51
  56. package/dist/config/defaults.js.map +0 -1
  57. package/dist/registries/dockerhub.d.ts +0 -2
  58. package/dist/registries/dockerhub.js +0 -20
  59. package/dist/registries/dockerhub.js.map +0 -1
  60. package/dist/registries/github.d.ts +0 -2
  61. package/dist/registries/github.js +0 -50
  62. package/dist/registries/github.js.map +0 -1
  63. package/dist/registries/npm.d.ts +0 -2
  64. package/dist/registries/npm.js +0 -20
  65. package/dist/registries/npm.js.map +0 -1
  66. package/dist/registries/pypi.d.ts +0 -2
  67. package/dist/registries/pypi.js +0 -20
  68. package/dist/registries/pypi.js.map +0 -1
  69. package/dist/registries/rdap.d.ts +0 -2
  70. package/dist/registries/rdap.js +0 -44
  71. package/dist/registries/rdap.js.map +0 -1
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
175
+
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 `?`.
136
191
 
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.
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,105 +214,261 @@ 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.
152
-
153
- ## Configuration
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.
154
219
 
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
+ ```
288
+
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
+ ```
309
+
310
+ Point `NSCOUT_CONFIG` at it, then use the registry like any other:
183
311
 
184
- ### GitHub
312
+ macOS / Linux:
185
313
 
186
- | Variable | Default | What it does |
187
- |---|---|---|
188
- | `GITHUB_TOKEN` | | Raises GitHub API rate limit from 60 to 5000 req/hr |
314
+ ```bash
315
+ export NSCOUT_CONFIG=~/nscout.config.json
316
+ nscout http zzqqxxnotreal123 -r pubdev,npm
317
+ ```
189
318
 
190
- ### RDAP (domain checks)
319
+ Windows (PowerShell):
191
320
 
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 |
321
+ ```powershell
322
+ $env:NSCOUT_CONFIG = "$HOME\nscout.config.json"
323
+ nscout http zzqqxxnotreal123 -r pubdev,npm
324
+ ```
197
325
 
198
- ## Architecture
326
+ Real output:
199
327
 
200
- nscout is built as a set of independent modules with no coupling between layers.
328
+ ```text
329
+ name pubdev npm
330
+ -----------------------------
331
+ http ✗ ✗
332
+ zzqqxxnotreal123 ✓ ✓
201
333
 
334
+ legend: ✓ available ✗ taken ⚠ reserved ⏳ expiring ? unknown ! error
202
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).
353
+
354
+ ## Web UI
355
+
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`:
361
+
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
375
+
376
+ - nscout built or installed globally
377
+ - `.env` configured (same file as CLI)
378
+
379
+ ### Start
380
+
381
+ ```bash
382
+ cd ui
383
+ pnpm install
384
+ pnpm build
385
+ pnpm start
386
+ ```
387
+
388
+ Open `http://localhost:3000` (or the port you set).
389
+
390
+ In development (live reload):
391
+
392
+ ```bash
393
+ pnpm dev
394
+ ```
395
+
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.
398
+
399
+ ## Architecture
400
+
401
+ ```text
402
+ config/
403
+ nscout.json all data: registries, URLs, TLDs, WHOIS servers, retries,
404
+ symbols, colors, AI prompts, env variable mapping
203
405
  src/
204
- registries/ pure registry adapters, no CLI awareness
205
- adapters.ts registry map: name -> RegistryAdapter
206
- index.ts orchestrator, bounded concurrency
207
- npm.ts npm adapter
208
- github.ts GitHub adapter, checks users + orgs
209
- pypi.ts PyPI adapter
210
- 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
211
416
  ai/
212
- suggest.ts name generation entry point
213
- registry.ts provider adapter registry, auto-resolves available provider
214
- 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
215
421
  render/
216
- table.ts terminal table with ANSI color
217
- json.ts JSON output
422
+ table.ts terminal table, symbols and colors from config
423
+ json.ts JSON output
218
424
  cli/
219
- index.ts CLI entry point, Commander wiring
220
- config/
221
- defaults.ts all defaults, URLs, symbols, and env vars in one place
222
- 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/
223
433
  ```
224
434
 
225
435
  Design rules:
226
436
 
227
- - All registry adapters implement `RegistryAdapter` from `types.ts`. Adding a new registry requires only a new file and one line in `adapters.ts`.
228
- - All hardcoded values live in `config/defaults.ts`: URLs, headers, symbols, retry counts, timeouts, AI token limits. Nothing is hardcoded in logic files.
229
- - All timeouts, TLDs, concurrency limits, AI provider, model IDs, and display symbols come from config or environment variables.
230
- - 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.
231
448
  - Unknown registry names passed via `--registries` print a warning to stderr and are skipped.
232
- - 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
+ ```
233
458
 
234
459
  ## Notes on the lane
235
460
 
236
461
  There is a comprehensive incumbent in this space: `bradtraversy/namescout-cli`
237
462
  plus a website at namescout.dev, shipped May 2026. It checks more surfaces
238
- (Docker Hub, VS Code Marketplace, Homebrew, six TLDs, etc.) and scores names.
239
- `nscout` is intentionally smaller and built around Claw conventions: fast,
240
- 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.
241
466
 
242
467
  ## Roadmap
243
468
 
244
469
  - [x] Docker Hub check.
470
+ - [x] Homebrew check.
245
471
  - [ ] VS Code Marketplace check.
246
- - [ ] Homebrew tap availability.
247
- - [ ] Premium-domain detection (would need a paid API like Domainr).
248
- - [ ] Watch mode: poll an expiring domain until it frees up.
249
472
 
250
473
  ## OpenClaw
251
474
 
@@ -258,7 +481,11 @@ The `--json` output makes nscout agent-friendly: structured results that any
258
481
  agent or script can parse and act on.
259
482
 
260
483
  To use `--suggest` through your OpenClaw agent's configured LLM instead of a
261
- separate API key, see the `psclawmcp` roadmap item above.
484
+ separate API key, configure `NSCOUT_AI_PROVIDER` in your `.env`.
485
+
486
+ ## Changelog
487
+
488
+ See [CHANGELOG.md](CHANGELOG.md).
262
489
 
263
490
  ## License
264
491