diff --git a/AI.md b/AI.md new file mode 100644 index 0000000..418a979 --- /dev/null +++ b/AI.md @@ -0,0 +1,124 @@ +# AI working notes for mars-nwe + +This file is for future ChatGPT sessions. It records general working rules and +local build/test notes only. It should not be used as the current project +status log; the current patch stack and task context should be pasted into a new +chat separately. + +## Start of a new chat + +When the user says this is a new chat or asks to continue mars-nwe work, first +read this file before proposing patches or making assumptions. Then ask for, or +use, the current project status that the user pasted into the chat. + +## Patch workflow + +- Produce patches that apply with exactly: + + ```sh + git am patchname.patch + ``` + +- Assume the user has already applied and committed accepted earlier patches. + Build every new patch against the current tree the user provides. +- Do not ask the user to apply a long patch chain unless they explicitly say + earlier patches were not committed. +- Keep follow-up patches small and reviewable. Do not mix functional changes, + cleanup, and logging refactors unless the user asks for that. +- If a patch is only documentation or test cleanup, keep it that way. + +## mars-nwe coding style rules + +- Prefer existing mars_nwe / NetWare functions over new helper code. +- Before adding a helper, search the tree for an existing equivalent. +- Do not introduce parallel mechanisms for paths, trustees, xattrs, AFP + metadata, copy/write/restore, u16/u32 packing, or logging. +- Use existing integer and wire-format macros such as `GET_16`, `GET_32`, + `U16_TO_16`, `U32_TO_32`, and related mars_nwe helpers instead of open-coded + byte parsing/serialization. +- Use existing namespace/path conversion and basehandle logic instead of parsing + NetWare paths by hand. +- For file restore/copy/write behavior, prefer the existing Novell/mars_nwe file + functions over direct POSIX operations. Use POSIX only where there is no + suitable internal mechanism, and keep it clearly isolated. +- Do not add a new trustee or xattr database. Salvage JSON is a snapshot; real + restore should feed existing mars_nwe trustee/xattr/AFP mechanisms. + +## Salvage endpoint rules + +- `NCP 0x2222 / 87 / 16` is decimal 87/16, implemented as function `0x57`, + subfunction `0x10`. +- `NCP 0x2222 / 87 / 17` is decimal 87/17, function `0x57`, subfunction + `0x11`. +- `NCP 0x2222 / 87 / 18` is decimal 87/18, function `0x57`, subfunction + `0x12`. +- Keep `0x57` subfunction dispatch in `handle_func_0x57()` / namespace code, + not as a second subfunction switch in `nwconn.c`. +- Versioned salvage entries may have different `.recycle`/`.salvage` names but + `87/16` returns the original deleted filename for every version. Do not match + recover/purge by display name alone. +- Scan, recover, and purge should share the same scan/sequence/basehandle view + so that a sequence returned by scan identifies the exact sidecar used later. +- Append salvage endpoint tests to `tests/salvage/salvage_smoke_suite.sh` rather + than creating unrelated top-level scripts. + +## Logging rules + +Desired future server log format: + +```text + key=value ... +``` + +- `LVL4` is exactly four characters: `INFO`, `DBUG`, `WARN`, `ERRR`. +- `AREA` examples: `NCP`, `SALVAGE`, `AFP`, `MAP`, `BIND`, `TRUST`, `AUTH`, + `CONN`, `FILE`, `QUEUE`. +- The front code should be human/protocol decimal where applicable, for example + `87/16`, `87/17`, `87/18`. +- Exact wire values should still be logged later as key/value hex fields, for + example `fn=0x57 sub=0x10 seq=0x00000000 base=0x00000004 result=0x89ff`. +- Unknown or unimplemented endpoints should be easy to grep, for example: + + ```text + INFO NCP 87/18 UNKNOWN fn=0x57 sub=0x12 msg="not implemented" + INFO NCP 87/255 UNKNOWN fn=0x57 sub=0xff msg="unknown subfunction" + INFO NCP 136 UNKNOWN fn=0x88 msg="unknown function" + ``` + +- Do not invent a parallel logger casually. Reuse existing mars_nwe logging + functions/macros and normalize message format gradually. + +## Build and test notes + +Dependencies used during local checks in this conversation: + +- `gdbm-1.26.tar.gz` +- `Linux-PAM-1.7.2.tar.xz` for PAM headers; link against system PAM if present +- `ncpfs-master.zip` for the salvage smoke helper client build +- `yyjson` under `third_party/yyjson` + +If CMake finds GDBM but a target still cannot see `gdbm.h`, pass include paths +explicitly for local verification, for example: + +```sh +CFLAGS="-I/path/to/gdbm/include -I/path/to/Linux-PAM-1.7.2/libpam/include" \ +cmake -S . -B build +cmake --build build --target nwconn ncp_salvage_scan_smoke ncp_salvage_recover_smoke +``` + +Useful quick checks: + +```sh +bash -n tests/salvage/salvage_smoke_suite.sh +cc -DLINUX -fsyntax-only -Iinclude -Isrc -Ithird_party/yyjson/src src/nwsalvage.c src/namspace.c +``` + +Runtime smoke suite: + +```sh +tests/salvage/salvage_smoke_suite.sh +``` + +The suite may run pre-clean warning-only when `.recycle` or `.salvage` artifacts +are server/root-owned. Treat the final summary (`failures=0`, `ncp_warnings=0`) +as the important signal. diff --git a/TODO.md b/TODO.md index 279a8ec..08437fd 100644 --- a/TODO.md +++ b/TODO.md @@ -153,6 +153,53 @@ Follow-up: - Verify that the quota-disabled fallback remains compatible with requesters and with the WebSDK rule for invalid object IDs. + + +### Server logging schema + +Current status: + +- Server logging is useful during protocol work, but output is still noisy and + not formatted consistently across NCP, namespace/path mapping, AFP, bindery, + file, queue, trustee, and salvage code. +- During salvage endpoint development, verbose logs are preferred over missing + diagnostic information, but the messages should become easier to grep and + compare across subsystems. + +Follow-up: + +- Normalize new server log lines toward this shape: + + ```text + key=value ... + ``` + +- Use four-character levels so columns do not jump around: + - `INFO` + - `DBUG` + - `WARN` + - `ERRR` +- Put the level first, then the subsystem/function area, for example `NCP`, + `SALVAGE`, `AFP`, `MAP`, `BIND`, `TRUST`, `AUTH`, `CONN`, `FILE`, or `QUEUE`. +- Use decimal/protocol-facing endpoint identifiers near the front when they are + what the documentation uses, for example `87/16`, `87/17`, and `87/18`. +- Keep exact wire values as hex key/value fields later in the same line, for + example `fn=0x57 sub=0x10 ns=0x00 seq=0x00000000 vol=0x0000 + base=0x00000004 result=0x89ff`. +- Mark missing or unimplemented endpoints with a stable `UNKNOWN` event, for + example: + + ```text + INFO NCP 87/18 UNKNOWN fn=0x57 sub=0x12 msg="not implemented" + INFO NCP 87/255 UNKNOWN fn=0x57 sub=0xff msg="unknown subfunction" + INFO NCP 136 UNKNOWN fn=0x88 msg="unknown function" + ``` + +- Prefer existing mars_nwe logging functions/macros. Do not introduce a second + logging subsystem just to change the message format. +- Convert noisy areas gradually, starting with NCP function/subfunction dispatch + and the salvage endpoints. + ## Printing / Queue backend ### Q_UNIX_PRINT backend status