M8: non-functional close-out audit + cheap fixes

Five-dimension audit (coverage, quality, performance, security, docs) of
the post-M7 state; full report in M8-AUDIT.md. Verdict: pure CCFE::*
modules are excellent across the board (Devel::Cover: 92-100%); residual
debt is the oversized ccfe.pl subs and, most importantly, RESTRICTED mode
being a guardrail rather than a security boundary.

Cheap fixes applied (all 313 tests green):
- code: 3 string-vs-numeric operator mismatches on counts ($c eq 0,
  $nfound eq/ge 2 -> ==/>=); removed 2 dead lexicals ($labelLen, $sc);
  ralign() eval-string -> sprintf (also closes a latent injection smell).
- security/docs: documented RESTRICTED's true scope in the README (it read
  stronger than the code delivers).
- consistency: version 2.1.1 across README/RPM/Alpine/packaging-README;
  perl >= 5.36 floor on RPM + Alpine (matching use v5.36 / debian); fixed
  README man-page names (ccfe_menu/ccfe_form) and a stale backup caveat;
  resolved the ROADMAP / M7-CTX-PLAN "M7 in progress vs complete"
  contradiction.

Filed (in M8-AUDIT.md / FEATURE-REQUESTS): RESTRICTED hardening (locked
config, read-only objects, shell-free argv exec, eval-free colour parsing);
browser/exec/shell-escape test coverage; do_form-led sub refactor + man-page
rewrite; man pages onto MANPATH + module POD. None block a 2.2 release.

ROADMAP: M8 done -> all milestones M0-M8 delivered.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: claude

M7-CTX-PLAN.md

@@ -1,8 +1,12 @@
 # M7 — `$ctx` threading plan (de-globalisation finish)
 
+> **STATUS: COMPLETE.** All phases 0–6 below are done; `ccfe.pl` runs under
+> `use v5.36`. This document is kept as the record of how the de-globalisation
+> was carried out. The narrative below is written from the start of that work.
+
 The pure-parser/geometry extractions (REFACTOR.md §3.1–3.2, first half) are
 done: `CCFE::MenuFile`, `FormFile`, `Config`, `Action`, `Layout` are split out,
-unit-tested, and released in 2.1.1. What remains of M7 is the harder half:
+unit-tested, and released in 2.1.1. What remained of M7 was the harder half:
 **replace the package globals and `local` dynamic scope in `ccfe.pl` with an
 explicit `$ctx` state object** (REFACTOR.md §3.2, bullet 3 — "the spookiest
 action-at-a-distance in the code").

M8-AUDIT.md

@@ -0,0 +1,187 @@
+# M8 — Non-functional close-out audit
+
+Five-dimension review of CCFE at the post-M7 state (v2.1.1, `use v5.36`, 313
+tests). Each dimension below gives a verdict, the findings, and whether each was
+**fixed in this audit** or **filed** for later. Cheap, safe fixes were applied
+now; structural and design-level items are filed (tracked in
+`FEATURE-REQUESTS.md`).
+
+Overall: the codebase is in good shape. The pure `CCFE::*` modules are
+excellent across every dimension; the residual debt is concentrated in the
+legacy `ccfe.pl` body (size/complexity) and in the **security model of
+RESTRICTED mode**, which is the one finding that materially changes how CCFE
+should be described and deployed.
+
+---
+
+## 1. Test coverage
+
+**Verdict: strong where it's been invested (modules), with real gaps in the
+`ccfe.pl` interior.** Measured with `Devel::Cover` (require-based + module
+tests; the pty tests exec a separate, uninstrumented process, so true `ccfe.pl`
+coverage is higher than the raw number):
+
+| Unit | stmt | branch | sub | total |
+|------|------|--------|-----|-------|
+| Action / Config / Context | 100 | 100 | 100 | **100** |
+| MenuFile | 100 | 100 | 100 | 97.3 |
+| Restrict | 100 | 100 | 100 | 97.0 |
+| Layout | 100 | 87.5 | 100 | 96.6 |
+| FormFile | 98.9 | 93.7 | 100 | 92.7 |
+| Theme | 70.6 | 75.0 | 80 | 70.1 |
+
+Findings:
+- **[med] Output-browser interior untested** — `run_browse`'s `/`+`n` search
+  (`get_search_buff`/`search_next`/`search_all`) and the save-to-file /
+  save-to-runnable-script paths never run. The pty harness makes these
+  testable. *Filed.*
+- **[med] Error/failure branches untested** — `exec_command` command-not-found,
+  the silent `list_cmd` failure behind issue #1 (guarded only by source-pattern
+  match in `t/02`), file-open errors in save. The pty harness those tests asked
+  for now exists. *Filed.*
+- **[med] F7 shell-escape runtime path** — denial is unit-tested; the allowed
+  spawn-and-return is not. *Filed.*
+- **[low] `Theme.pm` at 70 %** — the colour-pair init paths need a live
+  terminal; could be covered with a small `Curses` mock or a pty assertion.
+  *Filed.*
+- **[low] CLI: `-s`/`list_shortcuts`, `--help`/`--version`** untested (vs
+  `-k`/`--dump`/`--plugins` which are). Trivial to add to `t/07`. *Filed.*
+
+## 2. Code quality
+
+**Verdict: modules pristine; the debt is all in `ccfe.pl`, correctly kept out
+of the CI perlcritic gate.** `perlcritic src/lib` is clean at severity 3.
+`ccfe.pl` shows 107 sev-5 / 441 sev-3 — but the bulk is intentional legacy idiom
+(bareword filehandles, stringy `eval` for colour config, non-lexical loop
+iterators) that would be churn-for-churn to "fix".
+
+**Fixed now:**
+- 3 string-vs-numeric operator mismatches on counts (`$c eq 0`, `$nfound eq 2`,
+  `$nfound ge 2` → `==`/`>=`).
+- 2 confirmed-unused lexicals removed (`$labelLen`, `$sc` — the latter left over
+  from the FormFile extraction).
+- `ralign()` rewritten from an `eval`-string to a plain `sprintf` (also a
+  security fix — see §4).
+- Version strings reconciled to 2.1.1 (README, RPM spec, Alpine APKBUILD,
+  packaging README) and the RPM/Alpine perl floor set to `>= 5.36`.
+
+**Filed:**
+- **Six oversized subs** dominate the complexity — `do_form` (1392 lines,
+  cyclomatic 285), `load_config` (582), `run_browse` (543), `do_list` (350),
+  `do_menu` (331), `load_form` (224). `do_form` is the clear refactor target.
+- The colour/attribute config dispatch is a long copy-pasted `if/elsif` of
+  `eval "$ctx->{cfg}{X} = …"` arms — table-driveable (and see §4 for the eval).
+- `ccfe.pl` is ~817 lines off perltidy; reformatting is high-churn and best done
+  alongside breaking up the big subs, so it stays ungated for now.
+
+## 3. Performance
+
+**Verdict: sound for an interactive TUI — no must-fix.** Scrolling uses a
+pre-built `curses` pad with O(1) `prefresh`; menu/form navigation delegates to
+the ncurses `menu_driver`/`form_driver`; heavy window/field rebuild is correctly
+gated to `KEY_RESIZE`, not run per keystroke. Startup parsing is linear and
+one-shot.
+
+Findings (all low, all filed):
+- The streaming output-capture loop calls `trace(…, $LOG_ACTION_OUT)` per line,
+  and both `trace()` and the new `$SIG{__WARN__}` handler open/append/close the
+  log **per event**. In normal use this is dormant (`$LOG_ACTION_OUT` is off at
+  the default log level; warnings are rare on hot paths), but a user who raises
+  the log level gets per-line file I/O while a command streams. Cheap future
+  fix: open the log once around the capture loop / hold a handle.
+- `trace()` builds `@months` + `localtime` before checking whether logging is
+  even on — trivial, move the gate first.
+- `/`-search reads each pad cell with a char-at-a-time `inchnstr`; one-shot per
+  search, bounded by `MAX_PAD_LINES`. Could read a row per call. Low.
+
+## 4. Security
+
+**Verdict: RESTRICTED mode is a *guardrail*, not a security boundary.** It
+reliably blocks the casual interactive escapes it was built for (F7 shell,
+save-as-runnable-script, `system:`/`exec:` of non-allowlisted program names),
+and the supporting hygiene is sound — `harden_child_env` strips `LD_*`/`BASH_ENV`
+/`ENV`/`CDPATH` and resets `IFS`; temp files use `O_EXCL`; persistent files are
+`0600` under the user's own dir; the log is `umask 0177`. But it is **not** a
+boundary against a motivated local user.
+
+**Fixed now:**
+- `ralign()` `eval`-string → `sprintf` (removed a latent Perl-injection smell on
+  boolean-field defaults).
+- Documented the real scope of RESTRICTED in the README (it previously read as a
+  stronger guarantee than the code provides).
+
+**Filed (the RESTRICTED hardening — needs design, see FEATURE-REQUESTS):**
+- **[high] User config can switch RESTRICTED off.** `load_config` applies every
+  file on `@cnf_path` in order (system → `~/.config/ccfe` → legacy) with
+  last-wins and no "system locks the value", and the search paths honour
+  user-controlled `CCFE_*_DIR`/`XDG_*`. A user re-sets `restricted = no`. Fix
+  direction: a locked/system-config mode that user config cannot weaken.
+- **[high] Menus/forms load from user-writable dirs.** `@mf_path` includes
+  `~/.local/share/ccfe` and honours `CCFE_OBJ_DIR`/`-l`. A user authors any
+  `run:` action (never allowlisted) → arbitrary command execution. Fix
+  direction: refuse user-writable object/config dirs in restricted deployments.
+- **[high] Allowlist is bypassable by shell chaining.** Actions run via
+  `/bin/sh -c`, but the allowlist only checks the first token's basename, so
+  `system: df; sh`, `df $(sh)`, backticks all pass. Same for `%{FIELD}` values
+  substituted into args before the check. Fix direction: argv-based (shell-free)
+  exec so the allowlist actually constrains what runs.
+- **[med] `eval "$VAR = $attrv"` in `load_config`** executes arbitrary Perl from
+  a config value (colour/attr settings). Trusted-config assumption, but combined
+  with the above it's an in-process code-exec primitive. Fix direction: validate
+  `$attrv` against the expected `A_*`/`COLOR_PAIR(n)`/`color_pair('x','y')`
+  grammar (or parse, don't eval).
+- **[low] CWD (`.`) on `$PATH`** in `run_browse`; **[low]** `$prompt` in
+  `call_shell` interpolated into a shell string. Both filed (the `.`-on-PATH
+  change risks breaking menus that call a script in their own dir, so it needs a
+  deliberate decision, not a drive-by edit).
+
+## 5. Documentation
+
+**Verdict: README prose is good and current on M6 features; the gaps are the
+man pages and a couple of self-contradictions, mostly cheap.**
+
+**Fixed now:**
+- README version line 2.0 → 2.1.1; the `man ccfe-menu`/`ccfe-form` (hyphen)
+  references corrected to the actual `ccfe_menu`/`ccfe_form` page names; the
+  stale "a future release reorganises these paths" caveat updated (that reorg
+  shipped in 2.0).
+- ROADMAP self-contradiction (the `$ctx` bullet still tagged 🔄 "in progress"
+  while the rest says M7 complete) → ✅; `M7-CTX-PLAN.md` given a COMPLETE
+  banner.
+
+**Filed:**
+- **[high] Man pages are stale** — `ccfe.1` etc. still say version 1.58, document
+  the pre-v2 `/usr/lib/ccfe` layout, and omit every M6 flag (`-k`, `-D/--dump`,
+  `-P/--plugins`) and feature (mouse, colour, resize). Needs a rewrite pass.
+- **[med] Deb ships man pages off the MANPATH** (`/usr/lib/ccfe/man/...`), so
+  `man ccfe` won't resolve from a package install despite the README saying it
+  will. Packaging fix (symlink/install into the man hierarchy).
+- **[med] No POD / contributor architecture doc** — the `CCFE::*` modules have
+  good header comments but zero POD, and there's no "lib/CCFE overview" for a
+  new contributor. Additive.
+- **[low] Two licence files** (`LICENCE` 2021 + `LICENSE` 2026) and a stale
+  `doc/ChangeLog` in the staged tree — tidy up.
+
+---
+
+## What was fixed in this audit
+
+`ccfe.pl`: 3 numeric operators, 2 dead lexicals, `ralign` eval→sprintf.
+Docs: README (version, man-page names, RESTRICTED scope, backup caveat),
+ROADMAP + M7-CTX-PLAN consistency. Packaging: version 2.1.1 across
+RPM/Alpine/packaging-README, perl `>= 5.36` floor on RPM/Alpine. All 313 tests
+stay green.
+
+## What is filed (recommended next, roughly by priority)
+
+1. **RESTRICTED-mode hardening** (the §4 high items) — locked system config,
+   read-only object dirs in restricted deployments, shell-free argv exec, and
+   `eval`-free colour-config parsing. This is the highest-value follow-up.
+2. **Coverage**: pty tests for the browser search/save paths, `exec_command`
+   failure (the real issue-#1 repro), and F7 shell-escape.
+3. **`do_form` (and the other oversized subs) refactor**, with a perltidy pass
+   and man-page rewrite once the structure settles.
+4. **Packaging**: man pages onto the MANPATH; module POD + a contributor doc.
+
+Performance items are genuinely low priority. None of the filed items block a
+2.2 release.

README.MD

@@ -15,7 +15,7 @@ the manual pages are under `src/man/`.
 
 ## Status
 
-`src/ccfe.pl` is the program (currently version **2.0**). The ongoing
+`src/ccfe.pl` is the program (currently version **2.1.1**). The ongoing
 modernisation — packaging, security hardening, optional colour and a move to a
 modular, more functional structure — is described in
 [`REFACTOR.md`](REFACTOR.md) and [`ROADMAP.md`](ROADMAP.md). CCFE depends on
@@ -111,6 +111,19 @@ environment variables, so menus can consume input safely (e.g.
 `run:grep -- "$CCFE_FIELD_PATTERN" /var/log/syslog`) instead of interpolating
 `%{PATTERN}` into a shell string.
 
+**Scope of the guarantee.** Restricted mode is a *guardrail against wandering
+off the menu*, not a hardened security boundary against a determined local
+user. Be aware that: the allowlist matches the command's program name, but
+actions run through a shell, so `system: df; sh` (chaining) or a `%{FIELD}`
+value containing shell metacharacters can reach a shell — prefer `run:` with
+`"$CCFE_FIELD_*"` and avoid `%{...}` interpolation; `run:` itself is never
+allowlisted; and CCFE reads config and menu/form files from the user's own
+`~/.config/ccfe` and `~/.local/share/ccfe` (and honours `CCFE_*_DIR`/`-l`), so
+a user who can write those can change what runs. For a genuine kiosk boundary,
+deploy CCFE with system-owned, user-unwritable config and object directories
+(and consider the OS-level confinement you'd use for any restricted login). See
+`M8-AUDIT.md` for the full analysis.
+
 ## Colour and styles
 
 CCFE is monochrome by default. When the terminal supports colour (and
@@ -212,7 +225,7 @@ item { id=NET   descr=Network connections  action=run:ss -tunap }
 ```
 
 then run `ccfe mytools`. See the manual pages under `src/man/` (or
-`man ccfe`, `man ccfe-menu`, `man ccfe-form` after install) for the full
+`man ccfe`, `man ccfe_menu`, `man ccfe_form` after install) for the full
 file-format reference, and `ccfe-plugin-sysmon` for forms and `list_cmd`
 dropdowns.
 
@@ -259,8 +272,8 @@ git add . && git commit -m "My CCFE config and menus"
 
 To restore on a new machine, install CCFE (or the package), then copy these
 files back into place. `ccfe -k <name>` parse-checks a menu/form after you
-restore or edit it. (A future release reorganises these paths and adds a
-guided config/backup workflow — see `ROADMAP.md`.)
+restore or edit it. (A guided config/backup workflow is a planned enhancement —
+see `FEATURE-REQUESTS.md`.)
 
 ## Tests
 

ROADMAP.md

@@ -151,7 +151,8 @@ the manifest at install time (dependency checks, clean uninstall).
 landed in two halves: the pure parser/geometry extractions (`CCFE::MenuFile`/
 `FormFile`/`Config`/`Action`/`Layout`, released in 2.1.1) and the `$ctx`
 threading (phases 0–6, see **M7-CTX-PLAN.md**), finishing with `use v5.36` on
-`ccfe.pl`.  Next: **M8** (the non-functional close-out audit).
+`ccfe.pl`.  **M8** (the non-functional close-out audit) is also complete — see
+`M8-AUDIT.md`. **All ROADMAP milestones M0–M8 are now delivered.**
 
 ## M7 — De-globalisation / full modularisation  _(REFACTOR §3 — deferred to end)_
 Extract `MenuFile`/`FormFile`/`Action`/`Layout`/`Exec`/`UI::*` into
@@ -204,7 +205,7 @@ the conformance tests.
   `new_field`/`move_field` calls and tracing stay in `ccfe.pl`. Unit-tested with
   hand-computed expectations in `t/17-layout.t` (27 cases); the resize/layout/
   multipage tty tests and full suite (302 tests) stay green.
-- 🔄 **`$ctx` threading** (in progress): replacing `ccfe.pl`'s package globals
+- ✅ **`$ctx` threading** (done): replacing `ccfe.pl`'s package globals
   and `local` dynamic scope with one explicit run-state object. Planned in
   **M7-CTX-PLAN.md** (phases 0–6, all in scope). **Phase 0 done:**
   `CCFE::Context::new()` container built at startup, `t/18-context.t`, and the
@@ -235,9 +236,15 @@ the conformance tests.
   undef trace level, undef boolean descriptions headless, negative rule-line
   repeat). 313 tests green, zero runtime warnings; CI's `perl -c` enforces it.
 
-## M8 — Non-functional close-out audit  _(final gate)_
+## M8 — Non-functional close-out audit  _(final gate)_  ✅ **done**
 Five dimensions: **test coverage, code quality, performance, security,
-documentation**. Produce a short report, fix what's cheap, file the rest.
+documentation**. Report in **`M8-AUDIT.md`**; cheap fixes applied (numeric
+operators, dead lexicals, `ralign` eval→sprintf, version sync, README/ROADMAP
+consistency, RESTRICTED-scope doc), the rest filed. Headline finding: the pure
+modules are excellent on every dimension; the residual debt is the oversized
+`ccfe.pl` subs and — most importantly — **RESTRICTED mode is a guardrail, not a
+security boundary** (user-writable config/objects + shell-based exec defeat it);
+hardening it is the top filed follow-up. No filed item blocks a 2.2 release.
 
 ---
 

packaging/README.md

@@ -14,8 +14,8 @@ Runtime dependencies are only **perl** and the **Curses** module
 Built and tested in this repo:
 
 ```sh
-dpkg-buildpackage -b -us -uc      # produces ../ccfe_2.0_all.deb
-sudo apt install ../ccfe_2.0_all.deb
+dpkg-buildpackage -b -us -uc      # produces ../ccfe_2.1.1_all.deb
+sudo apt install ../ccfe_2.1.1_all.deb
 ```
 
 (`build-essential` is not actually needed — CCFE compiles nothing — so add

packaging/alpine/APKBUILD

@@ -9,13 +9,13 @@
 #
 # NOTE: not built/tested in this environment (no abuild available here).
 pkgname=ccfe
-pkgver=2.0
+pkgver=2.1.1
 pkgrel=0
 pkgdesc="Curses Command Front-end"
 url="https://github.com/OpusVL/perl-ccfe"
 arch="noarch"
 license="GPL-2.0-or-later"
-depends="perl perl-curses"
+depends="perl>=5.36 perl-curses"
 makedepends="perl"
 source="$pkgname-$pkgver.tar.gz"
 builddir="$srcdir/$pkgname-$pkgver"

packaging/rpm/ccfe.spec

@@ -10,15 +10,15 @@
 # NOTE: not built/tested in this environment (no rpmbuild available here).
 
 Name:           ccfe
-Version:        2.0
+Version:        2.1.1
 Release:        1%{?dist}
 Summary:        Curses Command Front-end
 License:        GPLv2+
 URL:            https://github.com/OpusVL/perl-ccfe
 Source0:        %{name}-%{version}.tar.gz
 BuildArch:      noarch
 BuildRequires:  perl
-Requires:       perl
+Requires:       perl >= 5.36.0
 Requires:       perl-Curses
 
 %description
@@ -46,6 +46,11 @@ ln -sf ../lib/ccfe/bin/ccfe %{buildroot}%{_bindir}/ccfe
 %doc README.MD
 
 %changelog
+* Wed Jun 11 2026 CCFE maintainers <ccfedevel@gmail.com> - 2.1.1-1
+- CCFE 2.1.1: terminal-resize reflow, display-column (wide-char) layout, full
+  colour palette + panel theme, opt-in mouse, --dump/--plugins, and an internal
+  de-globalisation onto pure CCFE::* modules (requires Perl >= 5.36).
+
 * Tue Jun 10 2026 CCFE maintainers <ccfedevel@gmail.com> - 2.0-1
 - CCFE 2.0: reorganised layout, runtime path resolution, restricted mode,
   optional colour with SMIT themes, and the -k linter.