Sweep every README/doc for accuracy and remove fabricated or stale content: - README/CLAUDE: add the live roadmap-page link and a rule to keep the rendered page in sync with docs/ROADMAP.md; fix the stale cov alias and the already-moved-shells note. - .github/CONTRIBUTING+SECURITY: drop the fabricated nuncio.mx site link and the aspirational release/security claims; state honest pre-alpha status. - docs/RUNNING, DEVELOPING, ARCHITECTURE, BACKLOG, Home, NSQL spec, corruption notes, proto/README: correct crate count/list, service list, CLI flags, phase status, and remove claims of unshipped/removed things (IPC-as-current, hardcoded-keys, unwired engines); mark superseded api-surface-draft historical. - Remove the fabricated benchmark baked into nsql_pipeline.svg and delete the orphaned ipc_sequence.svg (depicted the removed IPC with a fake timing).
78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
# Running Nuncio (dogfooding guide)
|
|
|
|
How to build, run, and use the daemon + CLI locally. These steps are **verified**
|
|
on Windows (the daemon boots and the CLI round-trips over real gRPC + the OS
|
|
keyring). Commands use `nuncio-cli.exe`; on macOS/Linux drop the `.exe`.
|
|
|
|
> **Status:** pre-alpha. The mail spine (accounts, sync, read, send) is real and
|
|
> works, but the IMAP/SMTP engines have so far only been exercised against mock
|
|
> servers — **your first real `mail sync` is the first live-server test**, and it
|
|
> may surface real-world issues (server quirks, auth methods, TLS). That's the
|
|
> point of dogfooding; report anything odd and it becomes a fix.
|
|
|
|
## 1. Build
|
|
|
|
```
|
|
cargo build-release # alias for: build --release -p nunciod -p nuncio-cli
|
|
```
|
|
|
|
Produces two self-contained executables (copy them anywhere; they only need the
|
|
network and the OS credential store):
|
|
- `target\release\nunciod.exe` — the daemon (the product)
|
|
- `target\release\nuncio-cli.exe` — the CLI (how you drive it)
|
|
|
|
(Use plain `cargo build -p nunciod -p nuncio-cli` for a faster debug build while
|
|
we're iterating.)
|
|
|
|
## 2. Start the daemon
|
|
|
|
```
|
|
target\release\nunciod.exe
|
|
```
|
|
|
|
It runs in the foreground and:
|
|
- serves the gRPC API on `127.0.0.1:9420` (loopback only) — services `System`,
|
|
`Accounts`, `Mail`, `Filters`, `Export`, `Audit`, all bearer-token authenticated;
|
|
- opens its database at `%USERPROFILE%\.nuncio\nuncio.db` (override with
|
|
`NUNCIO_DB_PATH`); the `~/.nuncio` directory is created on first run;
|
|
- provisions its keys + the CLI's bearer token in **Windows Credential Manager**
|
|
(never on disk);
|
|
- the autonomous auto-updater is intentionally **disabled** (pending a Phase 4
|
|
fail-open fix).
|
|
|
|
Leave it running; `Ctrl+C` stops it. Use the CLI from a second terminal.
|
|
|
|
## 3. Use it
|
|
|
|
```
|
|
:: confirm the CLI reaches the daemon (verified):
|
|
nuncio-cli.exe system status :: -> "Idle (nunciod v0.1.0, 127.0.0.1:9420)"
|
|
|
|
:: add your real account (defaults target mail.kof22.com:993/:465; prompts for the
|
|
:: password, which goes straight to the OS keyring):
|
|
nuncio-cli.exe account add --email you@kof22.com
|
|
:: override if needed: --imap-host --imap-port --smtp-host --smtp-port --imap-mode --smtp-mode
|
|
nuncio-cli.exe account list
|
|
|
|
:: the real spine:
|
|
nuncio-cli.exe mail sync :: real IMAP fetch -> local store
|
|
nuncio-cli.exe mail list
|
|
nuncio-cli.exe mail read --id <message-id>
|
|
nuncio-cli.exe mail search --query "invoice"
|
|
nuncio-cli.exe mail send --to a@b.com --subject "hi" --body "test"
|
|
|
|
:: filters, folders, etc.:
|
|
nuncio-cli.exe filter list
|
|
nuncio-cli.exe folder list
|
|
```
|
|
|
|
Add `--json` to any command for machine-readable output. `nuncio-cli.exe <noun> --help`
|
|
lists every verb and flag.
|
|
|
|
## The dogfooding loop
|
|
|
|
Use it for real; when something breaks or feels wrong, tell me (or I'll hit it
|
|
too). I reproduce against the real path, fix it, commit, and you pull `dev`.
|
|
Because the toolchain is pinned, every fix is validated locally exactly as CI
|
|
would validate it — so fixes land without waiting on CI.
|