mars-nwe/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Key context before starting

Read AI.md first — it is the handoff/rules document and contains the current patch marker, rejected patches, and immediate direction. Then read TODO.md (active backlog) and REDESIGN.md (architecture record) before touching namespace, salvage, transport, or NSS code. For focused topic detail, check the relevant doc/*.md file (see list in AI.md).

Current immediate direction (from AI.md): XAttr/LSA import track — the first real XAttr/EA and LSA dependency blocks are now in libnwnss (zXattr.h, lsaXattr.c, extAttrBeast.c, lsaComn.c, lsaErr.c, lsaUser.c). Continue resolving compile/link dependencies from the real NSS source drops, keep imported files original-near, and keep future HostFS/OtherFS/FUSE policy in role-specific boundary files. The XAttr/LSA provider is likely part of the future nwnssmount/FUSE metadata path, but FUSE callbacks are not active yet.

Default language with the user is German; repository documentation stays English unless the existing file is already German.

Building

Out-of-tree build (preferred):

cmake -S . -B build
cmake --build build
sudo cmake --install build

In-tree build (legacy style):

cmake .
make
sudo make install

Useful CMake options

Option	Default	Purpose
ENABLE_DEBUG_BUILD	OFF	Add -g3 -O0 debug compiler flags
ENABLE_DEBUG	OFF	Compile in XDPRINTF/DO_DEBUG logging code
MAINTAINER_BUILD	OFF	Enable maintainer-only test helpers; also forces new DOS utils
MARS_NWE_BUILD_TESTS	OFF	Build integration tests under tests/
MARS_NWE_BUILD_NWFS_TESTS	OFF	Build libnwfs unit tests
ENABLE_DIRECTORY	OFF	Build optional nwdirectory/TinyLDAP subsystem
ENABLE_BURSTMODE	ON	Experimental packet burst support

Required dependencies

libcrypt, gdbm, libpam, libdl. Optional: libacl (POSIX ACL trustee projection), quota, libattr (xattr).

For an offline/CI bootstrap from uploaded tarballs, run prepare-local-deps.sh from the repo root before CMake. It stages yyjson, libsodium, a local gdbm build under .local-deps/prefix, and PAM/ncurses fake headers.

Running tests

# Build with tests enabled
cmake -S . -B build -DMARS_NWE_BUILD_TESTS=ON -DMARS_NWE_BUILD_NWFS_TESTS=ON
cmake --build build

# Run all CTests from the build directory
ctest --test-dir build

# Run a single named test
ctest --test-dir build -R nwcore.ini

# Run a specific built test binary directly (verbose)
build/tests/nwfs/nwfs_dirquota_test -v

CTest names use dotted prefixes: nwcore.*, nwtui.*, nwfs.*, nwflaim.*, nwnss.*. Keep new tests in that shape.

Live NCPFS/NCP integration smokes (require a running server and mounted NCPFS volume) live under tests/nwfs/ and tests/salvage/. Entry points are the *.sh scripts — see tests/README.md for details.

Architecture overview

Server processes

MARS_NWE runs as a set of cooperating daemons managed through nwserv:

• nwserv — master supervisor; spawns and monitors child processes.
• nwconn — NCP request dispatcher; the main protocol handler. Forks per connection.
• nwbind — bindery service (user/group/object database via GDBM).
• nwrouted — RIP/SAP IPX router daemon (only when ENABLE_INTERNAL_RIP_SAP=ON).
• ncpserv / nwclient — auxiliary NCP helpers.
• dbmtool / ftrustee — admin utilities.

Library layers (src/ subdirectories)

Library	CMake target	Purpose
src/nwcore	mars_nwe::core	Shared Mars helpers: INI reader/writer (nw_ini_*), logging facade (nwlog_*)
src/nwfs	mars_nwe::nwfs	NWFS bridge: namespace glue, metadata, streams, EA, salvage, compression, quota, xattr persistence
src/nwtui	mars_nwe::tui	Terminal UI using bundled termbox2; nwtoolbox multi-call applet model
src/nwssl	mars_nwe::ssl	TLS/SSL via bundled MatrixSSL; backs nwwebui HTTPS daemon
src/nwnss	mars_nwe::nwnss	Imported NSS userspace library — low-level runtime helpers (Unicode, codepage, UTC, GUID, xCtype, xString, WIO, stdio formatter) plus namespace, trustee/effective-rights, XATTR/EA, AdminVol semantics

include/ layout mirrors src/:

• include/nwcore/ — headers for libnwcore
• include/nwnss/ — NSS SDK headers, mapped from original shared/sdk/{include,internal,public,comnSA}/
• include/nwfs/, include/nwtransport/, include/nwtui/, include/nwssl/

NCP dispatch path

IPX/TCP → nwtransport → nwconn (dispatcher) → NCP providers

nwconn handles 0x2222 NCP packets via a top-level switch on the function code, then calls into nwfile.c, namspace.c, nwbind.c, nwsalvage.c, nwxattr.c, etc. Magic return(-1) / return(-2) values carry handoff state between nwconn and nwbind; see doc/HANDOFF_AUDIT.md and include/ncp_endpoint.h for the ongoing annotation work.

NCP numbering rule: always record both decimal and wire/code hex — e.g. decimal 22/35 == wire/code 0x16/0x23. ENDPOINTS.md is the complete audit table.

Key design boundaries

• libnwcore must not link against libnwnss.
• libnwnss is a semantics layer first, storage engine later — namespace, Unicode, rights, EA/XAttr, AdminVolume. No disk/VFS I/O; libnwfs persists to host xattrs/sidecar state.
• libnwnss userspace backend split: original NSS files (e.g. lsaXattr.c, comnIO.c) stay as close to the source drops as possible. Host-FS, OtherFS, sidecar, FUSE and io_uring policy belongs in parallel Mars boundary files with NSS-shaped names: *Userspace.c / *Userspace.h (e.g. lsaXattrUserspace.c, comnIOUserspace.c). Do not add host-filesystem policy inline in imported original files.
• XAttr boundary status: lsaXattrUserspace.c / lsaXattrUserspace.h is now the first libnwnss XAttr adapter. It may construct kernel-shaped dentry/inode/super-block context and call original netware_*xattr; it must not contain FUSE callbacks, HostFS paths or sidecar policy. When NSS-volume detection exists, the NSS-vs-OtherFS/HostFS decision belongs here: NSS volumes use original NSS XAttr semantics, non-NSS storage uses an explicit backend or fails clearly until one exists. New XAttr tests should use this boundary first. Trustees are part of netware.metadata (zNW_metadata_s.nwm_trustee[]), not a separate active netware.trustees/user.netware.trustees xattr.
• virtualIO is not a disk/block backend. It is the NSS _ADMIN/management virtual-file and XML datastream layer. Future io_uring async storage belongs behind an explicit backend context/vtable; FUSE is the mount/VFS surface.
• Compression belongs in libnwfs, not libnwcore.
• Logging: new code uses nwlog_* levels 1=error … 5=trace; never add zlog (Apache-2.0, incompatible with GPL-2.0-only policy). MAINTAINER_BUILD enables nwlog_detail() only — no INI switch may enable it in production builds.
• TUI: do not add new direct curses.h users; route future interactive tools through nwtui/nwi18n and the nwtoolbox applet model.
• Transport: TCP/IP is a future split under nwtransport, not a new daemon. NCP providers stay transport-neutral.

Original NSS reference sources

The complete original NSS source tree is at /home/mario/mars/nss:

/home/mario/mars/nss/
├── Makefile                        — top-level build entry point
├── buildtools/                     — build helper scripts and tools
├── docs/                           — NSS documentation
├── public_core/                    — NSS C sources
│   ├── Makefile
│   ├── admindrv/   admindrvModules.mk
│   ├── comn/       comnModules.mk      ← namespace, beast, common, compression, …
│   ├── library/    libraryModules.mk   ← stdio, wio, OS helpers, …
│   ├── lsa/        lsaModules.mk
│   ├── manage/     manageModules.mk
│   ├── ndpmod/     ndpmodModules.mk
│   ├── nebdrv/     nebdrvModules.mk
│   ├── nss/        nssModules.mk
│   ├── nsslnxlib/  nsslnxlibModules.mk
│   ├── nwraid/     nwraidModules.mk
│   ├── sharedsrc/                  — shared .c.h source fragments
│   └── zlss/       zlssModules.mk
└── shared/
    ├── sdk/                        — include/, internal/, public/, comnSA/ headers
    ├── schema/
    └── support/

The *Modules.mk files list the exact object files each subsystem builds — use them to find the authoritative source set for any subsystem before importing or auditing files into src/nwnss/ and include/nwnss/.

NSS import layout

Imported NSS sources follow provenance-preserving paths:

Original NSS path	Mars path
public_core/library/…	src/nwnss/library/…
public_core/nss/…	src/nwnss/nss/…
public_core/comn/…	src/nwnss/comn/…
public_core/lsa/…	src/nwnss/lsa/…
shared/sdk/include/…	include/nwnss/include/…
shared/sdk/internal/…	include/nwnss/internal/…
shared/sdk/public/…	include/nwnss/public/…
shared/sdk/comnSA/…	include/nwnss/comnSA/…

Allowed changes in imported NSS files: compile fixes, modern compiler callback casts, include path fixes, and explicit NSS_USERSPACE guards. Host-FS/FUSE/io_uring policy belongs in *Userspace.c/*Userspace.h files alongside the imported original, not inline in it. Do not replace missing NSS symbols with local semantic wrappers — find and import the real bottom-up dependency instead.

Salvage and metadata backend

• .recycle/ — Samba-compatible deleted-payload store (rename-based; xattrs stay on inode).
• netware.metadata xattr — authoritative for deleted-file state; replaces the old .salvage JSON sidecars (legacy/migration only).
• Private stream/compression data lives under .nwfs_streams/<stable-file-id>/.
• Dot-directories (.recycle, .salvage) are not exposed through normal NCP path resolution.

Third-party submodules (third_party/)

libowfat, iniparser, libsodium, matrixssl, termbox2, yyjson, unicodeTables, flaim (optional, for nwdirectory). Use audited libowfat API names from the bundled source (e.g. socket_tcp4(), io_* readiness helpers).

License

Project code: GPL-2.0-only. Library components: LGPL-2.1-only. New/updated files carry the matching SPDX identifier. Do not import Apache-2.0 or GPL-3.0-or-later code.

Documentation map

File	Purpose
AI.md	Handoff rules, current patch marker, rejected patches, immediate direction
TODO.md	Active backlog with implementation dashboard
REDESIGN.md	Durable architecture and design record
ENDPOINTS.md	NCP decimal/hex audit table
nwnss-audit.md	libnwnss import audit checklist
doc/NSS_IMPORT_NOTES.md	NSS import notes: adaptation boundary, public_core audit, namespace audit
doc/HANDOFF_AUDIT.md	nwconn→nwbind magic-return annotation work
doc/NWFS_SALVAGE_COMPRESSION_TOOLS.md	Salvage/compression/tool planning
doc/TOOLBOX_PLAN.md	Terminal UI, nwtoolbox roadmap, and INI reader/writer plan
doc/DIRECTORY_AND_ADMIN_PLAN.md	Directory stack, LDAP, nwAdmin and nwConsole roadmap
doc/LOG_LEVEL_AUDIT.md	Logging level audit