feat: migrate nostream scripts to unified CLI/TUI

.changeset/sour-dolls-sip.md

@@ -0,0 +1,8 @@
+---
+"nostream": major
+---
+
+Add a brand-new unified `nostream` CLI/TUI that replaces the legacy `scripts/*` shell wrappers for lifecycle, setup, info, config, data, and development workflows.
+
+**Fixes**
+    - fixed some consistnacy issues after the migration from `npm` to `pnpm`

.env.example

@@ -69,6 +69,6 @@ WORKER_COUNT=2 # Defaults to CPU count. Use 1 or 2 for local testing.
 # HIDDEN_SERVICE_PORT=80
 
 # --- I2P (Optional) ---
-# To enable I2P, use: ./scripts/start_with_i2p
+# To enable I2P, use: nostream start --i2p
 # I2P tunnel configuration lives in i2p/tunnels.conf and i2p/i2pd.conf.
 # No application-level env vars are needed; the i2pd sidecar handles everything.

.github/workflows/checks.yml

@@ -61,6 +61,10 @@ jobs:
         run: pnpm install --frozen-lockfile
       - name: Run build check
         run: pnpm run build:check
+      - name: Build artifacts
+        run: pnpm run build
+      - name: Verify built CLI entrypoint
+        run: pnpm run verify:cli:build
   test-units-and-cover:
     name: Unit Tests And Coverage
     runs-on: ubuntu-latest
@@ -80,6 +84,8 @@ jobs:
         run: pnpm install --frozen-lockfile
       - name: Run unit tests
         run: pnpm run test:unit
+      - name: Run CLI test suite
+        run: pnpm run test:cli
       - name: Run coverage for unit tests
         run: pnpm run cover:unit
         if: ${{ always() }}

.knip.json

@@ -1,22 +1,26 @@
 {
   "$schema": "https://unpkg.com/knip@2/schema.json",
   "entry": [
-    "src/index.ts",
-    "src/import-events.ts",
-    "knexfile.js"
+    "src/index.ts!",
+    "src/import-events.ts!",
+    "src/cli/index.ts!",
+    "src/scripts/benchmark-queries.ts!",
+    "knexfile.js!"
   ],
   "project": [
-    "src/**/*.ts"
+    "src/**/*.ts!"
   ],
   "ignoreDependencies": [
     "lzma-native"
   ],
-  "ignoreFiles": [],
+  "ignore": [
+    ".nostr/**"
+  ],
   "commitlint": false,
   "eslint": false,
   "github-actions": false,
   "husky": false,
   "mocha": false,
   "nyc": false,
   "semantic-release": false
-}
+}

CLI.md

@@ -0,0 +1,138 @@
+# Nostream CLI
+
+Nostream ships a unified command-line interface:
+
+```bash
+nostream --help
+pnpm run cli -- --help
+```
+
+When run with no arguments in an interactive terminal, `nostream` launches an interactive TUI.
+In non-interactive environments, it prints help and exits successfully.
+
+## Exit Codes
+
+- `0`: success
+- `1`: runtime/validation error
+- `2`: usage error (invalid command/options)
+
+## Core Commands
+
+```bash
+nostream start [--tor] [--i2p] [--nginx] [--debug] [--port 8008]
+nostream stop [--all|--tor|--i2p|--nginx|--local]
+nostream info [--tor-hostname] [--i2p-hostname] [--json]
+nostream update
+nostream clean
+nostream setup [--yes] [--start]
+nostream seed [--count 100]
+nostream import [file.jsonl|file.json] [--file file.jsonl|file.json] [--batch-size 1000]
+nostream export [output] [--output output] [--format jsonl|json]
+```
+
+## Removed Legacy Wrappers
+
+The old shell wrapper scripts are no longer shipped in `scripts/`.
+Use the unified `nostream` CLI directly instead:
+
+```bash
+scripts/start                -> nostream start
+scripts/start_with_tor       -> nostream start --tor
+scripts/start_with_i2p       -> nostream start --i2p
+scripts/start_with_nginx     -> nostream start --nginx
+scripts/stop                 -> nostream stop
+scripts/print_tor_hostname   -> nostream info --tor-hostname
+scripts/print_i2p_hostname   -> nostream info --i2p-hostname
+scripts/update               -> nostream update
+scripts/clean                -> nostream clean
+```
+
+## Configuration Commands
+
+```bash
+nostream config list
+nostream config list --json
+nostream config get <path>
+nostream config get <path> --json
+nostream config set <path> <value> [--type inferred|json] [--validate|--no-validate] [--restart]
+nostream config validate
+
+nostream config env list [--show-secrets]
+nostream config env get <key> [--show-secrets]
+nostream config env set <key> <value>
+nostream config env validate
+```
+
+Path syntax supports dot keys and array indexes:
+
+```bash
+nostream config get limits.event.content[0].maxLength
+nostream config set limits.event.content[0].maxLength 2048
+nostream config set nip05.domainWhitelist '["example.com","relay.io"]' --type json
+```
+
+## Development Commands
+
+```bash
+nostream dev db:clean [--all|--older-than=30|--kinds=1,7,4] [--dry-run] [--force]
+nostream dev db:reset [--yes]
+nostream dev seed:relay
+nostream dev docker:clean [--yes]
+nostream dev test:unit
+nostream dev test:cli
+nostream dev test:integration
+```
+
+## TUI Navigation
+
+Run:
+
+```bash
+nostream
+```
+
+Main menu includes:
+- Start relay
+- Stop relay
+- Configure settings
+- Manage data (export/import)
+- Development tools
+- View relay info
+- Exit
+
+TUI behavior highlights:
+- Each submenu includes an explicit `Back` option, so you can return without using signal keys.
+- Start menu prompts for Tor/I2P/Debug, optional custom port, and final confirmation.
+- Configure menu offers guided editing for common categories such as payments, network, and limits.
+- Advanced dot-path get/set remains available for full settings access.
+- Manage menu asks for import/export format and file paths.
+- Dev menu displays explicit destructive warnings before DB reset/clean and Docker clean.
+
+## Common Workflows
+
+```bash
+# Start relay with Tor + I2P
+nostream start --tor --i2p
+
+# Print Tor hostname
+nostream info --tor-hostname
+
+# Machine-readable output for automation
+nostream info --json
+nostream config list --json
+nostream config get payments.enabled --json
+
+# Import and export events
+nostream import --file ./events.jsonl --batch-size 500
+nostream import --file ./events.json --batch-size 500
+nostream export --output backup.jsonl --format jsonl
+nostream export --output backup.json --format json
+
+# Update YAML settings and restart relay
+nostream config set payments.enabled true --restart
+
+# Update env settings
+nostream config env set RELAY_PORT 8008
+nostream config env get SECRET --show-secrets
+nostream config env validate
+```

CONFIGURATION.md

@@ -73,8 +73,7 @@ Tunnel keys are persisted at `.nostr/i2p/data/` so the `.b32.i2p` address surviv
 
 The i2pd web console (tunnel status, `.b32.i2p` destinations) is published to the host on **`127.0.0.1:7070`** only. Remove the `ports:` mapping in `docker-compose.i2p.yml` to disable host-side access.
 
-- Start with I2P: `./scripts/start_with_i2p`
-- Print hostname hints: `./scripts/print_i2p_hostname`
+- Start with I2P: `nostream start --i2p`
 
 If you've set READ_REPLICAS to 4, you should configure RR0_ through RR3_.
 

CONTRIBUTING.md

@@ -47,6 +47,13 @@ corepack enable
 pnpm install
 ```
 
+Use the unified CLI for relay lifecycle and supported development operations from this source
+checkout:
+
+```
+pnpm run cli -- --help
+```
+
 > **Important:** Pre-commit hooks installed by Husky run linting and formatting checks on every
 > commit. Do **not** bypass them with `git commit --no-verify`. If a hook fails, fix the reported
 > issues before committing.
@@ -56,7 +63,7 @@ pnpm install
 Start the relay (runs in the foreground until stopped with Ctrl+C):
 
 ```
-./scripts/start
+pnpm run cli -- start
 ```
 
 ### Development Quick Start (Standalone)
@@ -149,7 +156,7 @@ cd /path/to/nostream
 Run unit tests:
 
 ```
-pnpm test:unit
+pnpm run cli -- dev test:unit
 ```
 
 Run unit tests in watch mode:
@@ -223,7 +230,7 @@ DB_MAX_POOL_SIZE=2
 Run the integration tests:
 
 ```
-pnpm test:integration
+pnpm run cli -- dev test:integration
 ```
 
 Open the integration test report: