feat: migrate nostream scripts to unified CLI/TUI

[Mahmoud-s-Khedr]

Description

This PR migrates the existing shell-script-based workflows to a unified nostream CLI built with cac, with an interactive TUI fallback powered by @clack/prompts when run without arguments in an interactive terminal.

The change consolidates relay management, data management, setup, info, configuration, and development utilities under a single entrypoint. It adds command-specific help, guided TUI menus, config read/write/validation flows, JSON output for machine-readable paths, and updates documentation to reflect the new CLI-first workflow. Legacy wrapper scripts are removed in favor of the new command surface.

This PR also includes follow-up fixes for issues found during review:

• package/install support for the CLI entrypoint and runtime assets
• setup replacing placeholder or empty SECRET values
• info --i2p-hostname --json returning structured machine-readable output

Related Issue

Closes #535

Motivation and Context

Nostream previously relied on a collection of shell scripts for common operational tasks such as start, stop, update, export, import, and hostname lookup. That made the UX fragmented and increased maintenance burden across multiple entrypoints.

This change provides a single, consistent interface for operators and contributors:

• one command surface via nostream or npm run cli
• discoverable help and nested subcommand help
• an interactive TUI for users who prefer guided flows
• CLI-based configuration management without editing files directly
• clearer error handling, confirmations, and status output
• reduced dependence on ad hoc shell wrappers

How Has This Been Tested?

Tested with the existing unit and CLI integration suites, plus targeted coverage for the new CLI and follow-up fixes.

Commands run:

• npm run test:cli
• npm run verify:cli:build

Coverage added/validated includes:

• top-level and nested CLI help output
• npm run cli and built CLI entrypoint behavior
• package tarball contents required for installability
• config get/set/list/validate flows, including JSON output
• import/export command adapters and runtime routing
• TUI menu routing and prompt-driven flows
• setup handling of placeholder, empty, existing, and generated SECRET values
• info --i2p-hostname --json success, error, and fallback guidance paths
• legacy command replacements such as clean and update

Testing environment:

• local development environment using the project’s current Node/npm tooling
• CLI spawn tests against built output in dist

Screenshots (if appropriate):

N/A

Types of changes

• Non-functional change (docs, style, minor refactor)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my code changes.
• I added a changeset, or this is docs-only and I added an empty changeset.
• All new and existing tests passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: a9ecb6a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
nostream	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cac@​7.0.0
	stream-json@​2.1.0
	ora@​9.4.0
	@​clack/​prompts@​1.2.0

View full report

[coveralls]

coverage: 63.096% (-11.8%) from 74.929% — Mahmoud-s-Khedr:feat-001 into cameri:main

[Copilot]

Pull request overview

Migrates Nostream’s operational shell scripts to a single nostream TypeScript CLI (cac) with an interactive TUI mode (@clack/prompts), consolidating start/stop/update/info/setup/config/dev/data workflows under one entrypoint.

Changes:

• Added a unified CLI/TUI command surface (src/cli/**) and wired it into packaging/CI (bin mapping, packed files, build verification).
• Extended import/export tooling to support JSON array format alongside JSONL, plus improved runtime routing and stats/error reporting.
• Removed legacy scripts/* wrappers and updated docs/tests to reflect the CLI-first workflow.

Reviewed changes

Copilot reviewed 66 out of 67 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/unit/services/event-import-service.spec.ts	Adds unit tests for JSON array import batching/error handling.
test/unit/seeds/0000-events.spec.ts	Tests deterministic seed expansion via NOSTREAM_SEED_COUNT.
test/unit/import-events.spec.ts	Updates CLI arg error expectation for .jsonl/.json.
test/unit/cli/update.spec.ts	Adds unit tests for update command stash restore behavior.
test/unit/cli/tui.spec.ts	Adds routing tests for TUI menus to command handlers.
test/unit/cli/setup.spec.ts	Adds setup command tests for SECRET placeholder/empty handling.
test/unit/cli/info.spec.ts	Adds tests for info --i2p-hostname --json structured output.
test/unit/cli/import.runtime.spec.ts	Tests runtime routing between JSONL vs JSON array import modes.
test/unit/cli/export.spec.ts	Tests JSON vs JSONL export output formats.
test/unit/cli/export-command.spec.ts	Tests export command adapter passthrough/flag handling.
test/unit/cli/docs.spec.ts	Ensures docs mention script removal + wrappers aren’t shipped.
test/unit/cli/docker.spec.ts	Tests docker compose arg building + port override file creation.
test/unit/cli/config.spec.ts	Tests config path parsing, set/get, typed parsing, validation helpers.
test/unit/cli/commands.spec.ts	Tests env config key support + numeric/boolean validation.
test/unit/cli/cli.integration.spec.ts	Spawn-based integration tests for CLI help, config flows, start/stop shims, packaging checks.
src/services/event-import-service.ts	Adds JSON array streaming import path and refactors JSONL import into shared candidate pipeline.
src/scripts/export-events.ts	Adds structured JSON/JSONL export mode and refactors event formatting.
src/import-events.ts	Adds .json import routing, improves usage/help text, and refactors input validation/stream creation.
src/cli/utils/process.ts	Adds shared child-process helpers used by CLI commands.
src/cli/utils/paths.ts	Centralizes project/config/settings/env path resolution.
src/cli/utils/output.ts	Adds consistent stdout/stderr logging helpers (colored).
src/cli/utils/env-config.ts	Adds .env read/write + supported key validation + secret masking.
src/cli/utils/docker.ts	Adds compose file resolution, arg building, and port override compose generator.
src/cli/utils/config.ts	Adds settings load/merge/save, dot-path get/set, and shape/required-field validation.
src/cli/utils/bootstrap.ts	Adds CLI bootstrap checks (not root, config bootstrap, tor/i2p dirs).
src/cli/types.ts	Introduces shared CLI option types.
src/cli/tui/state.ts	Adds minimal shared TUI state.
src/cli/tui/prompts.ts	Wraps clack prompt APIs for stubbing/testing.
src/cli/tui/menus/stop.ts	Implements stop flow in TUI.
src/cli/tui/menus/start.ts	Implements start flow in TUI (tor/i2p/debug/port prompts).
src/cli/tui/menus/manage.ts	Implements import/export flows in TUI.
src/cli/tui/menus/dev.ts	Implements dev tools menu with destructive confirmations.
src/cli/tui/menus/configure.ts	Implements guided + advanced config editing flows in TUI.
src/cli/tui/main.ts	Implements TUI main loop + routing to menus/commands.
src/cli/index.ts	Adds nostream CLI entrypoint with subcommands, help, and error boundary handling.
src/cli/commands/update.ts	Implements update workflow (stop, stash, pull, restore, restart).
src/cli/commands/stop.ts	Implements stop command via docker compose down.
src/cli/commands/start.ts	Implements start command with overlays, nginx bootstrap, port override, and compose up.
src/cli/commands/setup.ts	Implements setup wizard for settings + .env SECRET handling and optional start.
src/cli/commands/seed.ts	Adds CLI seed wrapper (optional count via env).
src/cli/commands/info.ts	Implements info command with JSON output and I2P/Tor hostname helpers.
src/cli/commands/import.ts	Adds CLI adapter to existing import runtime.
src/cli/commands/export.ts	Adds CLI adapter to existing export runtime with legacy flag forwarding.
src/cli/commands/dev.ts	Adds dev utilities command group (db clean/reset, docker clean, test runners).
src/cli/commands/config.ts	Implements settings + env config subcommands with optional JSON output and restart support.
src/clean-db.ts	Updates help text to point to nostream dev db:clean.
seeds/0000-events.js	Adds deterministic synthetic event expansion controlled by NOSTREAM_SEED_COUNT.
scripts/verify-cli-build.js	Adds build verification script for CLI entrypoint + packed artifact contents.
scripts/update	Removes legacy shell wrapper.
scripts/stop	Removes legacy shell wrapper.
scripts/start_with_tor	Removes legacy shell wrapper.
scripts/start_with_nginx	Removes legacy shell wrapper.
scripts/start_with_i2p	Removes legacy shell wrapper.
scripts/start	Removes legacy shell wrapper.
scripts/print_tor_hostname	Removes legacy shell wrapper.
scripts/print_i2p_hostname	Removes legacy shell wrapper.
scripts/clean	Removes legacy shell wrapper.
package.json	Adds bin mapping/files list, adds cli + test:cli scripts, updates import/export script aliases, adds CLI deps, and enforces build before pack/tests.
docker-compose.yml	Assigns static IPs for db/cache services on the default network.
README.md	Updates docs to CLI-first workflow, adds CLI exit code contract, and documents wrapper removal + JSON array import/export.
CONFIGURATION.md	Updates I2P start instructions to CLI usage.
CLI.md	Adds full CLI/TUI reference and common workflow examples.
.knip.json	Updates Knip entry/project/ignore config for new CLI entrypoints and .nostr ignore.
.github/workflows/checks.yml	Adds built CLI verification step and runs new CLI test suite in CI.
.env.example	Updates I2P enable instructions to CLI usage.
.changeset/sour-dolls-sip.md	Adds a changeset entry describing follow-up fixes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.