@hasna/domains 0.0.24 → 0.0.25

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/domains
 
-Domain portfolio, registrar, marketplace, and DNS management for AI agents — CLI + MCP server with SQLite.
+Domain portfolio, registrar, marketplace, and DNS management for AI agents — CLI + MCP server with SQLite. Core registrar/DNS commands load by default; heavier integrations are optional command groups.
 
 ## Features
 
@@ -9,7 +9,8 @@ Domain portfolio, registrar, marketplace, and DNS management for AI agents — C
 - **Nameserver delegation** — Route 53 and Namecheap adapters can update registrar nameservers when the provider API supports it
 - **DNS provider management** — create or reuse Cloudflare or Route 53 zones and manage DNS records through the DNS provider layer
 - **DNS record CRUD** — A, AAAA, CNAME, MX, TXT, NS, SRV records
-- **Sedo marketplace tools** — search, portfolio/listing management, blacklist checks, and recorded Sedo purchases
+- **DNS desired state** — plan/diff/apply provider DNS records from JSON with explicit delete opt-in and post-apply verification
+- **Sedo marketplace tools** — optional search, portfolio/listing management, blacklist checks, and recorded Sedo purchases
 - **AWS diagnostics** — sync Route 53 registered domains and hosted zones without printing secret values
 - **Credential diagnostics** — redacted checks for Route 53, Cloudflare, Namecheap, GoDaddy, Brandsight, and Sedo
 - **Expiry alerts** — set alerts for domain expiry and SSL certificate expiry
@@ -20,9 +21,10 @@ Domain portfolio, registrar, marketplace, and DNS management for AI agents — C
 - **Subdomain discovery** — via crt.sh certificate transparency logs
 - **DNS validation** — detect CNAME conflicts, missing MX, and more
 - **Portfolio export** — CSV or JSON with all domain data
-- **Brand monitoring** — typosquat/threat detection via Brandsight API
+- **Brand monitoring** — optional typosquat/threat detection via Brandsight API
 - **MCP server** — Model Context Protocol support for AI agents
-- **Interactive TUI** — browse the portfolio in the terminal with `domains interactive`
+- **MCP safe mode** — expose read-only tools only with `DOMAINS_MCP_SAFE_MODE=1`
+- **Interactive TUI** — optional portfolio browser in the terminal with `domains interactive`
 
 ## Installation
 
@@ -32,6 +34,18 @@ npm install -g @hasna/domains
 
 Data is stored in the local domains data directory (`$XDG_DATA_HOME/open-domains` or `~/.local/share/open-domains` for new installs; existing legacy installs continue using their current directory). Override with `DOMAINS_DB_PATH`, `DOMAINS_DIR`, or the legacy `HASNA_DOMAINS_DB_PATH` / `HASNA_DOMAINS_DIR` names.
 
+## Optional Command Groups
+
+The default CLI keeps core portfolio, registrar, DNS, provider, Route 53, doctor, MCP, and server commands loaded. Optional groups are enabled per invocation:
+
+```bash
+domains extras
+DOMAINS_COMMAND_GROUPS=marketplace,storage domains --help
+DOMAINS_ENABLE_EXTRAS=1 domains --help
+```
+
+Available groups: `brandsight`, `events`, `history`, `interactive`, `marketplace`, `outreach`, `owner`, `provision`, `research`, `storage`, `wallet`.
+
 ## Quick Start
 
 ```bash
@@ -69,10 +83,6 @@ domains doctor
 ## CLI Usage
 
 ```bash
-# Interactive portfolio browser
-domains interactive
-domains interactive --status active
-
 # Portfolio management
 domains domain add --name example.com --registrar Namecheap --expires-at 2027-01-01
 domains domain list
@@ -136,23 +146,49 @@ domains dns validate <domain-id>
 domains dns pull example.com --provider cloudflare
 domains dns push <domain-id> --provider cloudflare
 
-# Sedo marketplace
-domains sedo search example
-domains sedo status example.com
-domains sedo portfolio --limit 25
-domains sedo add example.com --price 2500
-domains sedo edit example.com --price 3000
-domains sedo remove example.com
-domains sedo buy example.com --price 2500 --order-id SEDO-ORDER-ID
-
-# Brand monitoring
-domains monitor mybrand
-domains similar example.com
-domains threats example.com
+# Desired DNS state against a provider zone
+domains dns plan example.com --provider cloudflare --file dns.example.json
+domains dns diff example.com --provider cloudflare --file dns.example.json
+domains dns apply example.com --provider cloudflare --file dns.example.json --yes
+# Delete plans require --allow-delete and may still be refused before writes
+# when the provider path cannot guarantee safe convergence.
+
+# Optional Sedo marketplace
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo search example
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo status example.com
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo portfolio --limit 25
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo add example.com --price 2500
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo edit example.com --price 3000
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo remove example.com
+DOMAINS_COMMAND_GROUPS=marketplace domains sedo buy example.com --price 2500 --order-id SEDO-ORDER-ID
+
+# Optional brand monitoring
+DOMAINS_COMMAND_GROUPS=brandsight domains monitor watch mybrand
+DOMAINS_COMMAND_GROUPS=brandsight domains monitor similar example.com
+DOMAINS_COMMAND_GROUPS=brandsight domains monitor threats example.com
+
+# Optional interactive portfolio browser
+DOMAINS_COMMAND_GROUPS=interactive domains interactive
+DOMAINS_COMMAND_GROUPS=interactive domains interactive --status active
 ```
 
 Prefer the `domains` CLI over raw registrar CLIs for Route 53 availability, registration status, local portfolio updates, and DNS delegation. The CLI applies configured defaults, records outcomes in the local portfolio DB, and keeps behavior consistent across providers.
 
+Desired DNS state files are JSON:
+
+```json
+{
+  "domain": "example.com",
+  "records": [
+    { "type": "A", "name": "@", "value": "192.0.2.10", "ttl": 300 },
+    { "type": "MX", "name": "@", "value": "mail.example.com", "ttl": 300, "priority": 10 },
+    { "type": "TXT", "name": "@", "value": "v=spf1 -all", "ttl": 300 }
+  ]
+}
+```
+
+`dns apply` refuses to run without `--yes`. If the plan includes deletes, it also requires `--allow-delete`, then refuses before writing unless the provider path can guarantee delete convergence without partial mutation. Non-delete applies re-read provider records after writing and fail if the live zone still differs from the desired file.
+
 ## AWS Domain Discovery
 
 ```bash
@@ -174,9 +210,9 @@ Set one of these environment variables to sync with a remote PostgreSQL storage
 ```bash
 export DOMAINS_DATABASE_URL="postgres://..."
 
-domains storage status
-domains storage push
-domains storage pull
+DOMAINS_COMMAND_GROUPS=storage domains storage status
+DOMAINS_COMMAND_GROUPS=storage domains storage push
+DOMAINS_COMMAND_GROUPS=storage domains storage pull
 ```
 
 ## MCP Server
@@ -212,6 +248,15 @@ MCP_HTTP=1 MCP_HTTP_PORT=8814 domains-mcp
 
 Stdio remains the default transport for gradual rollout.
 
+For read-only agent sessions:
+
+```bash
+DOMAINS_MCP_SAFE_MODE=1 domains-mcp
+DOMAINS_MCP_SAFE_MODE=1 domains-mcp --http
+```
+
+Safe mode registers only read-only/list/check/export tools. Mutating tools such as domain creation, DNS writes, provider sync, Route 53 registration, and storage push/pull are withheld.
+
 ## Environment Variables
 
 | Variable | Description |
@@ -222,6 +267,9 @@ Stdio remains the default transport for gradual rollout.
 | `DOMAINS_CONFIG_DIR` | Override config directory |
 | `HASNA_DOMAINS_DIR` | Override database directory |
 | `DOMAINS_DIR` | Override database directory fallback |
+| `DOMAINS_COMMAND_GROUPS` | Comma-separated optional command groups to load, or `all` |
+| `DOMAINS_ENABLE_EXTRAS` | Set to `1` to load all optional command groups |
+| `DOMAINS_MCP_SAFE_MODE` | Set to `1` to expose only read-only MCP tools |
 | `DOMAINS_DATABASE_URL` | Remote storage PostgreSQL database URL |
 | `HASNA_DOMAINS_DATABASE_URL` | Legacy remote storage PostgreSQL database URL fallback |
 | `DOMAINS_STORAGE_MODE` | Storage mode: `local`, `remote`, or `hybrid` |
@@ -238,6 +286,7 @@ Stdio remains the default transport for gradual rollout.
 | `NAMECHEAP_SANDBOX` | Use Namecheap sandbox API |
 | `GODADDY_API_KEY`, `GODADDY_API_SECRET` | GoDaddy API credentials |
 | `BRANDSIGHT_API_KEY`, `BRANDSIGHT_API_SECRET`, `BRANDSIGHT_CUSTOMER_ID` | Brandsight / GoDaddy Corporate Domains credentials |
+| `BRANDSIGHT_DEMO_STUBS`, `BRANDSIGHT_ALLOW_STUBS` | Set either to `1` to allow demo stub responses when the Brandsight API is unreachable |
 | `SEDO_PARTNER_ID`, `SEDO_API_KEY`, `SEDO_USERNAME`, `SEDO_PASSWORD` | Sedo marketplace API credentials |
 
 ## License

package/dist/cli/commands/dns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAsR1D"}
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuCzC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgX1D"}

package/dist/cli/commands/domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/domain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8DzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA00B5D"}
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/domain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+DzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAq1B5D"}