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.
- package/.env.example +37 -21
- package/CHANGELOG.md +184 -0
- package/README.md +300 -106
- 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/.env +0 -71
- 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/ui/index.html +0 -12
- package/ui/package.json +0 -27
- package/ui/server.ts +0 -53
- package/ui/vite.config.ts +0 -14
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
|
|
136
175
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
151
|
-
|
|
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
|
-
|
|
154
|
-
|
|
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
|
+
```
|
|
183
288
|
|
|
184
|
-
|
|
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
|
-
|
|
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
|
-
|
|
312
|
+
macOS / Linux:
|
|
191
313
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
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
|
-
|
|
319
|
+
Windows (PowerShell):
|
|
199
320
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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
|
|
248
|
-
registry.ts
|
|
249
|
-
|
|
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
|
|
252
|
-
json.ts
|
|
422
|
+
table.ts terminal table, symbols and colors from config
|
|
423
|
+
json.ts JSON output
|
|
253
424
|
cli/
|
|
254
|
-
index.ts
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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
|
-
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
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
|
-
|
|
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
|
-
(
|
|
274
|
-
|
|
275
|
-
|
|
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).
|