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.
- package/.env.example +44 -18
- package/CHANGELOG.md +184 -0
- package/README.md +325 -98
- package/config/nscout.json +279 -0
- package/dist/ai/parse.d.ts +5 -0
- package/dist/ai/parse.js +13 -0
- package/dist/ai/parse.js.map +1 -0
- package/dist/ai/providers/anthropic.js +11 -14
- package/dist/ai/providers/anthropic.js.map +1 -1
- package/dist/ai/providers/openai.js +10 -12
- package/dist/ai/providers/openai.js.map +1 -1
- package/dist/ai/providers/stub.d.ts +1 -0
- package/dist/ai/providers/stub.js +5 -3
- package/dist/ai/providers/stub.js.map +1 -1
- package/dist/ai/registry.js +9 -3
- package/dist/ai/registry.js.map +1 -1
- package/dist/ai/suggest.d.ts +1 -0
- package/dist/ai/suggest.js +21 -18
- package/dist/ai/suggest.js.map +1 -1
- package/dist/cli/index.js +78 -25
- package/dist/cli/index.js.map +1 -1
- package/dist/config/format.d.ts +2 -0
- package/dist/config/format.js +5 -0
- package/dist/config/format.js.map +1 -0
- package/dist/config/load.d.ts +6 -0
- package/dist/config/load.js +94 -0
- package/dist/config/load.js.map +1 -0
- package/dist/config/schema.d.ts +180 -0
- package/dist/config/schema.js +2 -0
- package/dist/config/schema.js.map +1 -0
- package/dist/registries/adapters.d.ts +8 -0
- package/dist/registries/adapters.js +23 -11
- package/dist/registries/adapters.js.map +1 -1
- package/dist/registries/domains.d.ts +11 -0
- package/dist/registries/domains.js +167 -0
- package/dist/registries/domains.js.map +1 -0
- package/dist/registries/http.d.ts +7 -0
- package/dist/registries/http.js +68 -0
- package/dist/registries/http.js.map +1 -0
- package/dist/registries/index.d.ts +2 -3
- package/dist/registries/index.js +11 -8
- package/dist/registries/index.js.map +1 -1
- package/dist/registries/whois.d.ts +3 -0
- package/dist/registries/whois.js +20 -0
- package/dist/registries/whois.js.map +1 -0
- package/dist/render/json.d.ts +2 -2
- package/dist/render/json.js +4 -2
- package/dist/render/json.js.map +1 -1
- package/dist/render/table.d.ts +4 -2
- package/dist/render/table.js +34 -27
- package/dist/render/table.js.map +1 -1
- package/dist/types.d.ts +2 -2
- package/package.json +21 -15
- package/dist/config/defaults.d.ts +0 -43
- package/dist/config/defaults.js +0 -51
- package/dist/config/defaults.js.map +0 -1
- package/dist/registries/dockerhub.d.ts +0 -2
- package/dist/registries/dockerhub.js +0 -20
- package/dist/registries/dockerhub.js.map +0 -1
- package/dist/registries/github.d.ts +0 -2
- package/dist/registries/github.js +0 -50
- package/dist/registries/github.js.map +0 -1
- package/dist/registries/npm.d.ts +0 -2
- package/dist/registries/npm.js +0 -20
- package/dist/registries/npm.js.map +0 -1
- package/dist/registries/pypi.d.ts +0 -2
- package/dist/registries/pypi.js +0 -20
- package/dist/registries/pypi.js.map +0 -1
- package/dist/registries/rdap.d.ts +0 -2
- package/dist/registries/rdap.js +0 -44
- package/dist/registries/rdap.js.map +0 -1
package/README.md
CHANGED
|
@@ -2,13 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/nscout)
|
|
4
4
|
|
|
5
|
-
Scout a name across
|
|
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
|
-
|
|
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
|
|
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
|
|
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,.
|
|
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 [
|
|
109
|
+
```text
|
|
110
|
+
Usage: nscout [options] [names...]
|
|
91
111
|
|
|
92
|
-
|
|
93
|
-
-
|
|
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
|
-
|
|
96
|
-
|
|
97
|
-
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
|
110
|
-
|
|
111
|
-
myapp
|
|
112
|
-
mytool
|
|
113
|
-
|
|
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
|
|
159
|
+
Pass `-v` to show the reason for every `?` and `!` below the table.
|
|
128
160
|
|
|
129
161
|
## What it checks
|
|
130
162
|
|
|
131
|
-
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
151
|
-
|
|
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
|
-
|
|
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
|
-
|
|
224
|
+
## Configuration
|
|
158
225
|
|
|
159
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
239
|
+
```bash
|
|
240
|
+
nscout --print-config
|
|
241
|
+
```
|
|
172
242
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
|
178
|
-
|
|
|
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` | `
|
|
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` | `
|
|
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
|
-
|
|
312
|
+
macOS / Linux:
|
|
185
313
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
314
|
+
```bash
|
|
315
|
+
export NSCOUT_CONFIG=~/nscout.config.json
|
|
316
|
+
nscout http zzqqxxnotreal123 -r pubdev,npm
|
|
317
|
+
```
|
|
189
318
|
|
|
190
|
-
|
|
319
|
+
Windows (PowerShell):
|
|
191
320
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
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
|
-
|
|
326
|
+
Real output:
|
|
199
327
|
|
|
200
|
-
|
|
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
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
|
213
|
-
registry.ts
|
|
214
|
-
|
|
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
|
|
217
|
-
json.ts
|
|
422
|
+
table.ts terminal table, symbols and colors from config
|
|
423
|
+
json.ts JSON output
|
|
218
424
|
cli/
|
|
219
|
-
index.ts
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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
|
-
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
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
|
-
|
|
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
|
-
(
|
|
239
|
-
|
|
240
|
-
|
|
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,
|
|
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
|
|