mars-nwe/doc/TOOLBOX_PLAN.md

# Toolbox and INI plan

This file consolidates the terminal UI/toolbox design and the shared INI
reader/writer plan for `libnwcore`.

---

## Terminal UI and toolbox

This section records the planned terminal UI direction for future mars-nwe
administration tools.  It is a design note, not a commitment that the runtime
implementation already exists.

### Goals

mars-nwe should not grow more direct `curses.h` users.  The FLAIM test utilities
currently show why this matters: an otherwise optional developer/test tool can
pull ncurses into the build shape.  Future interactive tools such as setup,
filer, salvage, metadata repair and backup helpers should share one small TUI
layer instead of each choosing a terminal library.

The preferred shape is:

```text
third_party/termbox2/      pinned MIT terminal/event backend, tag v2.5.0
third_party/iniparser/     pinned MIT INI reader/writer backend, tag v4.2.6
include/nwcore/ini.h         shared libnwcore INI API used by server and tools
src/nwcore/ini.c             mars-nwe INI wrapper/adaptation and policy
src/nwtui/                 mars-nwe terminal widgets and themes
include/nwtui.h            public tool-facing TUI API
src/nwi18n/                small mars-nwe translation catalog loader
include/nwi18n.h           public translation lookup API
src/nwtoolbox/             multi-call toolbox binary
```

Tool code must call `nwtui_*` and `nwi18n_*`, not the backend directly.  The
backend now starts with termbox2 behind the `libnwtui` facade.  A minimal
ANSI backend or another terminal backend can still replace it later without
rewriting `nwsetup`, `nwfiler` or `nwsalvage`.

Configuration/catalog parsing must not be private to the TUI layer.  The shared
INI parser/writer belongs in `libnwcore` so that production daemons, setup tools
and optional translation catalogs all use one policy.  See the INI section below.

### Default look

The default visual style should be a coloured DOS/NetWare-like text UI, not a
monochrome curses application.  Use ASCII borders as the mandatory base so old
terminals still work.  UTF-8 block graphics may become an optional theme later,
but are not required for the design.

The existing blue bar tradition in `dosutils/login.c` is the local mars-nwe
reference.  External DOS file-manager/BBS screenshots can be used as visual
inspiration for blue panels, cyan/bright borders, highlighted menu items and a
fixed help line, but should not be copied verbatim.

A typical screen should have this structure:

```text
+------------------------------------------------------------------------------+
| MARS-NWE Toolbox 0.99                         Server: MARS  SYS: OK  IPX: L2 |
+------------------------------------------------------------------------------+
| Setup | Filer | Salvage | Metadata | Backup | Logs | Exit                    |
+------------------------------------------------------------------------------+

  +------------------------------+  +----------------------------------------+
  | Setup steps                  |  | Networking                             |
  |                              |  | IPX backend: L2 Ethernet II            |
  | > Configure server name      |  | Interface:   eth0                      |
  |   Configure IPX              |  | Network:     0x00000002                |
  |   Configure volumes          |  |                                        |
  +------------------------------+  +----------------------------------------+

                                                  +---------------------------+
                                                  | Running: validate config  |
                                                  | Status : waiting          |
                                                  +---------------------------+

+------------------------------------------------------------------------------+
| F1 Help | Enter Select | Esc Back | Tab Next | Alt+S Setup                  |
+------------------------------------------------------------------------------+
```

The header should be wider and calmer than very compact DOS file managers:

1. header/version/system-status line;
2. top menu or wizard step line;
3. content/work area with panels, forms, lists or dialogs;
4. optional right/bottom running-action box;
5. bottom help/status line.

### Theme roles

Tools should never hard-code raw colours.  They should request style roles from
`nwtui`:

```c
typedef enum {
  NWTUI_STYLE_NORMAL,
  NWTUI_STYLE_HEADER,
  NWTUI_STYLE_MENU,
  NWTUI_STYLE_MENU_SELECTED,
  NWTUI_STYLE_PANEL,
  NWTUI_STYLE_PANEL_TITLE,
  NWTUI_STYLE_STATUS,
  NWTUI_STYLE_HELP,
  NWTUI_STYLE_ERROR,
  NWTUI_STYLE_WARNING,
  NWTUI_STYLE_OK,
  NWTUI_STYLE_DISABLED
} NwTuiStyle;
```

The first theme should be named `mars-blue`:

- header/menu/status bars: blue background;
- normal panel background: blue or terminal-default according to capability;
- borders: cyan/bright blue;
- selected menu/list items: inverted or high-contrast highlight;
- help/hotkeys: yellow/bright accent;
- errors: red/bright red;
- warnings: yellow/brown;
- successful/done states: green;
- disabled items: dim/grey.

### Navigation widgets

Top navigation is a first-class widget.  It is used both as a menu and as a
wizard-step bar.  It should be keyboard reachable and mouse clickable where the
backend supports mouse input.

Expected behaviour:

- Left/Right move between top items;
- Alt+hotkey activates a named item;
- Enter selects the focused item;
- Tab moves between fields/panels;
- F1 opens help;
- Esc goes back or exits the current modal action;
- mouse click selects a top item or panel item if mouse support is enabled.

`nwsetup` can use the same widget as a progress/step line, for example:

```text
Configuration | Networking | Volumes | Bindery | Logging | Finish
```

The bottom help line should be stable and translated.  It should not carry large
version text; version and system status belong in the header.

### Multi-call binary

The future interactive tools should be built as one multi-call binary, not as
several unrelated terminal programs:

```text
nwtoolbox        main interactive menu
nwsetup          symlink/hardlink/argv[0] entry to setup mode
nwfiler          symlink/hardlink/argv[0] entry to filer mode
nwsalvage        symlink/hardlink/argv[0] entry to salvage mode
nwmetadata       symlink/hardlink/argv[0] entry to metadata/repair mode
nwbackup         symlink/hardlink/argv[0] entry to backup/export mode
```

`nwtoolbox` without a specific applet name opens the main menu and lets the user
choose setup, filer, salvage, metadata, backup, logs and future tools.  If the
same binary is invoked through a specific symlink name, it should start that
applet directly.  This keeps shared UI, translation, config loading and privilege
checks in one executable while preserving familiar command names.

Conceptual dispatch:

```c
int main(int argc, char **argv)
{
  const char *name = nw_basename(argv[0]);

  if (!strcmp(name, "nwsetup"))
    return nwtoolbox_run_setup(argc, argv);
  if (!strcmp(name, "nwfiler"))
    return nwtoolbox_run_filer(argc, argv);
  if (!strcmp(name, "nwsalvage"))
    return nwtoolbox_run_salvage(argc, argv);

  return nwtoolbox_run_menu(argc, argv);
}
```

The applets should share process-wide initialisation:

- load configuration;
- load translation catalog;
- initialise logging;
- initialise terminal backend/theme;
- check privileges and server paths;
- then enter the selected applet.

Command-line subcommands may still exist for scripts, but the interactive TUI
entry should be the multi-call toolbox.

### Translation without gettext

Do not add a gettext dependency just for TUI strings.  Use a small mars-nwe
translation API.  The backing catalog can be an INI-like file, a generated C
table, or a small project-owned parser.  Tools should not know the storage
format.

Conceptual API:

```c
int nwi18n_load(const char *language, const char *catalog_path);
const char *nwi18n_get(const char *key);
const char *nwi18n_get_default(const char *key, const char *fallback);
```

Catalog keys should be stable English identifiers, not source strings:

```ini
[en]
toolbox.title = MARS-NWE Toolbox
menu.setup = Setup
menu.filer = Filer
menu.salvage = Salvage
help.main = F1 Help | Enter Select | Esc Back

[de]
toolbox.title = MARS-NWE Toolbox
menu.setup = Setup
menu.filer = Filer
menu.salvage = Salvage
help.main = F1 Hilfe | Enter Auswählen | Esc Zurück
```

The default built-in language should be English.  Missing keys fall back to the
built-in English string or to the key name in developer builds.

### FLAIM curses replacement path

The immediate dependency goal is to remove the ncurses requirement from FLAIM
test/tool paths.  Do not rewrite every FLAIM utility at once.  First isolate the
terminal dependency behind `nwtui`, then convert the small curses-using test
path to the wrapper.

Steps:

1. inventory the current FLAIM test/tool source that includes `curses.h`;
2. add `nwtui` declarations and a minimal backend plan;
3. convert the FLAIM test path from direct curses calls to `nwtui` calls;
4. remove ncurses from that tool path once the converted test compiles;
5. keep PAM/ncurses header extraction in `prepare-local-deps.sh` only while
   other compile checks still need it.

No production daemon should depend on the TUI stack.

---

## Shared INI reader/writer (libnwcore)

This section records the planned shared INI reader/writer layer for mars-nwe.
It is a design note; the runtime implementation is not present yet.

### Goals

mars-nwe needs one robust INI implementation that can be used by both server
processes and interactive tools.  It must not be a private helper inside the
future TUI or translation layer.

The same project API should support:

- legacy `nw.ini` compatibility readers;
- future named configuration sections such as `[transport.ipx]` and
  `[logging.process.nwconn]`;
- `nwsetup` generated configuration files;
- `nwtoolbox` applets that edit configuration interactively;
- `nwi18n` catalog files if the catalog format stays INI-like;
- safe read-modify-write operations that preserve administrator-friendly files
  well enough to avoid turning configuration into an opaque dump.

### Layering

The INI API belongs in `libnwcore`, not in `nwtui` or an individual tool:

```text
include/nwcore/ini.h         public mars-nwe core INI API
src/nwcore/ini.c             project-owned wrapper and policy over iniParser
```

Server code, `nwtoolbox`, `nwsetup`, `nwfiler`, `nwsalvage` and `nwi18n` should
call only the mars-nwe `nw_ini_*` API.  They must not call the vendored backend
directly.  This keeps the backend replaceable and keeps configuration semantics
centralized.

### Candidate backend

`iniParser` is the selected first backend.  It is small C code, MIT licensed,
can read and write INI files, and is pinned as `third_party/iniparser` at
release tag `v4.2.6` (`4bef811283e0ec1658c60e09950bd5a1ddc92e4b`).

The public contract remains the mars-nwe `nw_ini_*` API in `libnwcore`.  Server
code and tools must not include `iniparser.h` directly.  `minIni` remains only a
technical reference because the uploaded source is Apache-2.0 and is not a
GPL-2.0-only core target.  `inih` remains parser-only and is not enough for
`nwsetup`, because setup and toolbox applets must be able to update INI files.

### Project API shape

The first public API should stay small and boring:

```c
int nw_ini_load_file(NwIniFile *ini, const char *path);
const char *nw_ini_get_string(NwIniFile *ini,
                              const char *section,
                              const char *key,
                              const char *fallback);
int nw_ini_get_bool(NwIniFile *ini,
                    const char *section,
                    const char *key,
                    int fallback);
uint32_t nw_ini_get_u32(NwIniFile *ini,
                        const char *section,
                        const char *key,
                        uint32_t fallback);
int nw_ini_set_string(NwIniFile *ini,
                      const char *section,
                      const char *key,
                      const char *value);
int nw_ini_delete_key(NwIniFile *ini, const char *section, const char *key);
int nw_ini_save_file(NwIniFile *ini, const char *path);
void nw_ini_free(NwIniFile *ini);
```

Exact names can follow existing mars-nwe style when implemented, but the
capability set should cover read, update, delete and save.

### Writer rules

The writer must be good enough for administrator-facing configuration:

- preserve section/key ordering when possible;
- preserve comments around untouched entries when the backend makes that
  feasible;
- write known generated blocks in a stable order;
- save through a temporary file plus rename when practical;
- avoid rewriting a hand-edited configuration into a minimal key/value dump;
- report parse/write errors through the future `nwlog` facade, not direct
  backend prints.

If the backend cannot preserve all comments, generated files must still remain
readable and documented.  The project wrapper owns that policy, not individual
callers.

### Legacy compatibility

The old numeric `nw.ini` format remains supported.  The new core API should make
it possible to expose named sections without breaking the old path.  Compatibility
adapters may translate old numeric entries such as `100..106` logging levels into
new named process-level fields while still accepting old files.

### Relationship to nwi18n

`nwi18n` may use the core INI API to load translation catalogs, but `nwi18n` is
not the owner of the parser.  The dependency direction is:

```text
libnwcore INI -> nwi18n -> nwtui -> nwtoolbox applets
```

Production daemons may use the core INI API without pulling in `nwi18n`, `nwtui`
or the toolbox stack.