@mmmbuto/nexuscrew 0.8.33 → 0.8.34

package/lib/cli/commands.js

@@ -112,8 +112,22 @@ function parseFlags(argv, valueFlags) {
 
 function serve(opts = {}) {
   const serverStart = opts.serverStart || require('../server.js').start;
+  const platform = opts.platform || detectPlatform();
+  // A legacy Termux:Boot script can start the new package from a replaceable
+  // npm directory. Correct the live process before it can create the shared
+  // tmux server, then atomically refresh both boot definitions for next boot.
+  if (platform === 'termux') {
+    stabilizeTermuxWorkingDirectory({ ...opts, platform });
+    try {
+      repairTermuxBootDefinitions({ ...opts, platform, clearMarker: true });
+    } catch (error) {
+      const warn = opts.lifecycleWarn || ((message) => process.stderr.write(`${message}\n`));
+      warn(`nexuscrew: Termux boot auto-repair pending — ${String(error && error.message || error)}`);
+    }
+  }
   // Service manager e Termux:Boot entrano direttamente da `serve`, senza
-  // passare per smartUp. Ripara solo fleet.json MANCANTE; un file invalido
+  // passare per smartUp. Su Termux ripara anche gli script di boot legacy.
+  // Per Fleet, ripara solo fleet.json MANCANTE; un file invalido
   // resta intatto e il provider continua a fallire chiuso.
   (opts.ensureFleetDefaultsImpl || ensureFleetDefaults)(opts);
   if (opts.pidfile) {
@@ -279,6 +293,37 @@ function restart(opts = {}) {
   const execImpl = opts.execImpl || execFileSync;
   const log = opts.log || console.log;
   if (!['linux', 'mac', 'termux'].includes(platform)) throw new Error(`restart: platform ${platform} non supportata`);
+  let termuxRepair = null;
+  if (platform === 'termux') {
+    try {
+      stabilizeTermuxWorkingDirectory({ ...opts, platform });
+      termuxRepair = repairTermuxBootDefinitions({
+        ...opts, platform, clearMarker: false,
+      });
+    } catch (error) {
+      return {
+        platform,
+        runtimeOwner: 'portable',
+        restarted: false,
+        reason: `Termux boot auto-repair failed: ${String(error && error.message || error)}`,
+      };
+    }
+  }
+  const complete = (result) => {
+    if (platform !== 'termux' || !result || result.restarted !== true || !termuxRepair?.markerPending) {
+      return result;
+    }
+    try {
+      clearServiceMigrationMarker(opts.home || require('node:os').homedir(), opts.serviceMigrationMarkerPath);
+      return result;
+    } catch (error) {
+      return {
+        ...result,
+        serviceRepairPending: true,
+        warning: `Termux boot repair marker cleanup pending: ${String(error && error.message || error)}`,
+      };
+    }
+  };
   const before = resolveRuntimeOwner({ ...opts, platform, execImpl });
 
   // A managed owner can use the service manager's atomic restart. In a
@@ -307,7 +352,7 @@ function restart(opts = {}) {
         execImpl('launchctl', ['kickstart', '-k', label], { stdio: 'ignore' });
         log(`restart: launchctl kickstart -k ${label}`);
       }
-      return { platform, owner: before.owner, runtimeOwner: 'managed', restarted: true };
+      return complete({ platform, owner: before.owner, runtimeOwner: 'managed', restarted: true });
     } catch (error) {
       return { platform, owner: before.owner, runtimeOwner: 'managed', restarted: false, reason: String(error.message || error) };
     }
@@ -319,7 +364,7 @@ function restart(opts = {}) {
     const started = (opts.startPortableImpl || startPortable)({ ...opts, platform, spawnImpl: opts.spawnImpl });
     const ok = !!(started && started.started !== false);
     if (ok) log('restart: portable runtime started');
-    return { platform, owner: before.owner, runtimeOwner: 'portable', restarted: ok, reason: ok ? undefined : started && started.reason };
+    return complete({ platform, owner: before.owner, runtimeOwner: 'portable', restarted: ok, reason: ok ? undefined : started && started.reason });
   }
 
   // `restart` on a stopped runtime follows the explicit boot owner; with boot
@@ -330,7 +375,7 @@ function restart(opts = {}) {
     : (opts.startPortableImpl || startPortable)({ ...opts, platform, spawnImpl: opts.spawnImpl });
   const ok = !!(started && started.started !== false);
   if (ok) log(`restart: ${useManaged ? 'managed' : 'portable'} runtime started`);
-  return { platform, owner: before.owner, runtimeOwner: useManaged ? 'managed' : 'portable', restarted: ok, reason: ok ? undefined : started && started.reason };
+  return complete({ platform, owner: before.owner, runtimeOwner: useManaged ? 'managed' : 'portable', restarted: ok, reason: ok ? undefined : started && started.reason });
 }
 
 function wizardComplete(configPath) {
@@ -406,6 +451,63 @@ function clearServiceMigrationMarker(home, override) {
   }
 }
 
+// Termux app updates replace the global npm package while existing boot
+// scripts remain on disk. Always enter the stable HOME before serving or
+// booting Fleet so a legacy script cannot make tmux inherit the package cwd.
+function stabilizeTermuxWorkingDirectory(opts = {}) {
+  const platform = opts.platform || detectPlatform();
+  if (platform !== 'termux') return { platform, changed: false };
+  const home = opts.home || require('node:os').homedir();
+  (opts.chdirImpl || process.chdir)(home);
+  return { platform, changed: true, cwd: home };
+}
+
+// Refresh only an already-enabled Termux:Boot installation. Boot remains
+// opt-in: missing scripts are never created by this repair path. A durable
+// marker makes an interrupted refresh visible and retryable.
+function repairTermuxBootDefinitions(opts = {}) {
+  const platform = opts.platform || detectPlatform();
+  const home = opts.home || require('node:os').homedir();
+  if (platform !== 'termux') return { platform, persistent: false, refreshed: false, markerPending: false };
+  const persistent = bootState({ ...opts, platform }).enabled;
+  if (!persistent) return { platform, persistent: false, refreshed: false, markerPending: false };
+
+  const markerPending = serviceMigrationPending(home, opts.serviceMigrationMarkerPath);
+  const refreshNeeded = serviceDefinitionNeedsRefresh(
+    platform, home, opts.installPath, opts.fleetInstallPath,
+  );
+  if (!markerPending && !refreshNeeded) {
+    return { platform, persistent: true, refreshed: false, markerPending: false };
+  }
+
+  if (refreshNeeded) {
+    ensureServiceMigrationMarker(home, opts.serviceMigrationMarkerPath);
+    const result = (opts.runInitImpl || runInit)({
+      ...opts,
+      home,
+      platform,
+      installBoot: true,
+      printUrl: false,
+      log: opts.lifecycleLog || (() => {}),
+    });
+    if (serviceDefinitionNeedsRefresh(platform, home, opts.installPath, opts.fleetInstallPath)) {
+      throw new Error('generated Termux boot definitions failed stable-HOME verification');
+    }
+    const failures = Array.isArray(result?.installFailures) ? result.installFailures : [];
+    if (failures.length) {
+      const components = [...new Set(failures.map((failure) => failure?.component)
+        .filter((component) => component === 'service' || component === 'fleet-companion'))];
+      throw new Error(`Termux boot definition install failed${components.length ? ` (${components.join(', ')})` : ''}`);
+    }
+  }
+
+  const pending = markerPending || refreshNeeded;
+  if (pending && opts.clearMarker !== false) {
+    clearServiceMigrationMarker(home, opts.serviceMigrationMarkerPath);
+  }
+  return { platform, persistent: true, refreshed: refreshNeeded, markerPending: pending };
+}
+
 function portAvailable(port, host = '127.0.0.1') {
   return new Promise((resolve) => {
     const s = net.createServer();
@@ -742,6 +844,7 @@ function update(opts = {}) {
 // / cfg / exit (per test, no process.exit che uccide il runner).
 async function runFleetBoot(opts = {}) {
   const log = opts.log || console.log;
+  stabilizeTermuxWorkingDirectory(opts);
   const loadConfig = opts.loadConfig || require('../config.js').loadConfig;
   const selectProvider = opts.selectProvider || require('../fleet/provider.js').selectProvider;
   const { bootCells } = require('../fleet/boot.js');
@@ -1065,6 +1168,8 @@ module.exports = {
   serviceDefinitionNeedsRefresh,
   fleetServiceDefinitionNeedsRefresh,
   serviceMigrationPending,
+  stabilizeTermuxWorkingDirectory,
+  repairTermuxBootDefinitions,
   portAvailable, findAvailablePort, probeNexusCrew, waitForNexusCrew, openPwa, startPortable, wizardComplete,
   servicePinsLegacyPort,
   isServiceRunning, readRoles,

package/lib/cli/pidfile.js

@@ -30,9 +30,24 @@ function removePidfile(p) {
   try { fs.unlinkSync(p); } catch (_) {}
 }
 
-function pidExists(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (e) { return e.code === 'EPERM'; } // EPERM = esiste ma non nostro
+// A PID can exist without belonging to this UID. Android commonly reuses PIDs
+// across app sandboxes; kill(pid, 0) then returns EPERM and /proc is hidden.
+// Keep generic existence separate from NexusCrew ownership so a foreign PID
+// can never keep one of our pidfiles "alive" forever.
+function pidOwnership(pid, killImpl = process.kill) {
+  try {
+    killImpl(pid, 0);
+    return 'owned';
+  } catch (e) {
+    if (e && e.code === 'EPERM') return 'foreign';
+    if (e && e.code === 'ESRCH') return 'missing';
+    return 'unknown';
+  }
+}
+
+function pidExists(pid, killImpl = process.kill) {
+  const ownership = pidOwnership(pid, killImpl);
+  return ownership === 'owned' || ownership === 'foreign';
 }
 
 function readCmdline(pid) {
@@ -50,36 +65,46 @@ function cmdMatches(savedCmd, liveCmd) {
   return liveCmd.includes(savedCmd) || savedCmd.includes(liveCmd);
 }
 
-// true se il pid esiste E il cmd matcha (o non verificabile).
-function isAlive(meta) {
+// true se il pid appartiene a questo UID E il cmd matcha (o non verificabile).
+// EPERM is deliberately false: NexusCrew must neither adopt nor signal a
+// process owned by another Android/Linux user.
+function isAlive(meta, impl = {}) {
   if (!meta || !Number.isFinite(meta.pid)) return false;
-  if (!pidExists(meta.pid)) return false;
+  if (pidOwnership(meta.pid, impl.killImpl || process.kill) !== 'owned') return false;
   if (meta.cmd) {
-    const live = readCmdline(meta.pid);
+    const live = (impl.readCmdlineImpl || readCmdline)(meta.pid);
     if (live) return cmdMatches(meta.cmd, live);
   }
   return true;
 }
 
 // Rimuove pidfile stale (pid morto o non verificabile). Ritorna true se rimosso.
-function cleanStale(p) {
+function cleanStale(p, impl = {}) {
   const meta = readPidfile(p);
   if (!meta) return false;
-  if (!isAlive(meta)) { removePidfile(p); return true; }
+  if (!isAlive(meta, impl)) { removePidfile(p); return true; }
   return false;
 }
 
 // Kill verificato: legge pidfile, verifica pid+cmd, signal. MAI broad match by name.
 // Ritorna { killed, pid?, reason? }.
-function killPidfile(p, signal = 'SIGTERM') {
+function killPidfile(p, signal = 'SIGTERM', impl = {}) {
   const meta = readPidfile(p);
   if (!meta) return { killed: false, reason: 'no pidfile' };
-  if (!pidExists(meta.pid)) {
+  const killImpl = impl.killImpl || process.kill;
+  const ownership = pidOwnership(meta.pid, killImpl);
+  if (ownership === 'missing' || ownership === 'unknown') {
     removePidfile(p);
     return { killed: false, reason: 'stale (pid dead)' };
   }
+  if (ownership === 'foreign') {
+    // Never send a real signal after an EPERM ownership probe. The pidfile is
+    // ours; the process is not.
+    removePidfile(p);
+    return { killed: false, reason: 'stale (pid not owned)' };
+  }
   if (meta.cmd) {
-    const live = readCmdline(meta.pid);
+    const live = (impl.readCmdlineImpl || readCmdline)(meta.pid);
     if (live && !cmdMatches(meta.cmd, live)) {
       // PID reuse: processo diverso. Non killare. Rimuovi pidfile stale.
       removePidfile(p);
@@ -87,7 +112,7 @@ function killPidfile(p, signal = 'SIGTERM') {
     }
   }
   try {
-    process.kill(meta.pid, signal);
+    killImpl(meta.pid, signal);
     removePidfile(p);
     return { killed: true, pid: meta.pid };
   } catch (e) {
@@ -97,5 +122,5 @@ function killPidfile(p, signal = 'SIGTERM') {
 
 module.exports = {
   defaultPidfilePath, readPidfile, writePidfile, removePidfile,
-  pidExists, readCmdline, isAlive, cleanStale, killPidfile,
+  pidOwnership, pidExists, readCmdline, isAlive, cleanStale, killPidfile,
 };

package/lib/nodes/tunnel.js

@@ -130,7 +130,12 @@ function reconcileTunnelSupervisors({ home = os.homedir(), configuredNames = [],
     .filter((name) => store.NODE_NAME_RE.test(String(name || ''))));
   const stopOne = typeof stopImpl === 'function' ? stopImpl : stopTunnel;
   const result = { kept: [], stopped: [], cleaned: [], failed: [] };
-  const safeAbsent = new Set(['no pidfile', 'stale (pid dead)', 'pid reuse (cmd mismatch)']);
+  const safeAbsent = new Set([
+    'no pidfile',
+    'stale (pid dead)',
+    'stale (pid not owned)',
+    'pid reuse (cmd mismatch)',
+  ]);
   for (const name of tunnelPidNames(home)) {
     if (keep.has(name)) { result.kept.push(name); continue; }
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.33",
+  "version": "0.8.34",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/fill-forms/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: fill-forms
+description: Use for inspecting, filling and visually validating local PDF or DOCX forms, including AcroForm fields, coordinate-based overlays, checkboxes, character boxes and an explicitly authorised signature image. Trigger when the user asks to fill in a PDF, complete a form, prepare paperwork for signature, populate a DOCX template or inspect a form before completion. Keep processing local, preserve the original, never invent personal data, and never sign or submit a document without explicit authorisation.
+---
+
+# Fill Forms
+
+Fill PDF and DOCX forms locally with the bundled scripts. Prefer named PDF
+fields when they exist; use coordinate overlays only for flat forms or scans.
+Always preserve the blank source and visually verify a new output file.
+
+## Select the response language
+
+Choose the language for questions, progress updates and explanations in this
+order:
+
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+
+Do not translate field values, names, identifiers, legal wording or document
+text merely to match the response language. Preserve the document's language
+unless the user explicitly requests a translation.
+
+## Apply the safety boundary
+
+- Work on local copies. Do not upload a form or its contents to an external
+  service unless the user explicitly requests and authorises that transfer.
+- Never invent a name, address, identifier, account number, date, selection or
+  legal answer. Ask for missing data or leave the field visibly unresolved.
+- Treat signatures as sensitive assets. Insert a signature image only when the
+  authorised signer supplies it and explicitly asks for insertion into the
+  identified document. Never keep signature images in source control.
+- Filling is not signing, sending or submitting. Obtain separate explicit
+  authorisation before any consequential external action.
+- Never overwrite the blank source. The scripts reject identical source and
+  output paths and require `--overwrite` before replacing an existing output.
+- Generated documents, prepared signatures and preview images are written as
+  owner-only files; generated preview/grid directories are owner-only.
+- Keep configuration files containing personal data out of source control and
+  remove temporary previews when the user no longer needs them.
+
+## Prepare dependencies
+
+Resolve every script relative to this `SKILL.md`. The scripts require Python 3
+and do not install packages automatically. Check the environment first:
+
+```bash
+python3 --version
+python3 -c "import fitz"
+```
+
+For PDF image/signature handling and DOCX support, the complete dependency set
+is listed in `requirements.txt`. If dependencies are missing, explain what is
+needed and ask before creating a virtual environment or installing packages.
+Never modify the system Python implicitly.
+
+## Inspect first
+
+Run the inspector before filling a PDF:
+
+```bash
+python3 <skill-dir>/scripts/inspect_pdf.py form.pdf
+```
+
+It reports AcroForm fields and produces coordinate-grid PNG files next to the
+source. Review those images rather than guessing positions. Replacing an
+existing grid requires an intentional `--overwrite`.
+
+- If named fields exist, prefer `mode: "acroform"`.
+- For a flat PDF or scan, use `mode: "overlay"`.
+- Use `mode: "both"` only when the document genuinely mixes both forms.
+
+For precise checkboxes and signature lines, anchor coordinates to nearby PDF
+text rather than estimating from a full-page image. Read
+[`references/overlay-technique.md`](references/overlay-technique.md) before a
+non-trivial overlay.
+
+## Fill a PDF
+
+Create a JSON configuration beside the working copy:
+
+```json
+{
+  "src": "blank-form.pdf",
+  "out": "completed-form.pdf",
+  "mode": "overlay",
+  "font_size": 9,
+  "overlay": [
+    {"page": 0, "x": 220, "y": 190, "text": "Example Person"},
+    {"page": 0, "x": 62, "y": 332, "check": true},
+    {
+      "page": 1,
+      "x": 70,
+      "y": 410,
+      "text": "XX00EXAMPLE0000000000000000",
+      "spread": {"step": 17.5}
+    }
+  ]
+}
+```
+
+Relative paths are resolved from the configuration file. Run:
+
+```bash
+python3 <skill-dir>/scripts/fill_pdf.py form-data.json
+```
+
+The script creates the output and a `<output>_preview/` directory. Use
+`--overwrite` only for an intentional revision of that output.
+
+Supported overlay items:
+
+- `text`, `x`, `y`, optional `size`;
+- `check: true`, `x`, `y`, optional `size`;
+- `text` plus `spread.step` and optional `spread.skip` for character boxes;
+- `image` plus `rect: [x0, y0, x1, y1]` for an explicitly authorised local
+  image;
+- optional top-level `font_file` for a user-provided TTF/OTF when the built-in
+  PDF font cannot represent the required text.
+
+For AcroForm mode, provide `"acroform": {"field-name": "value"}` and booleans
+for checkboxes. Unknown requested field names fail closed instead of silently
+producing an incomplete form.
+
+## Fill a DOCX template
+
+Inspect its paragraphs and tables:
+
+```bash
+python3 <skill-dir>/scripts/dump_docx.py template.docx
+```
+
+Use explicit `{{placeholder}}` tokens whenever possible, then run:
+
+```bash
+python3 <skill-dir>/scripts/fill_docx.py template.docx completed.docx \
+  --data form-data.json
+```
+
+Plain-text key replacement is available only with `--literal-keys` because it
+can otherwise replace unintended text. Unused data keys fail closed unless the
+user deliberately chooses `--allow-unused`.
+
+## Verify before handoff
+
+1. Review every generated preview page at full size.
+2. Zoom critical regions such as checkboxes, character boxes and signatures.
+3. Compare every populated value with the user's authoritative source.
+4. Confirm that the original file is unchanged and the output has a distinct
+   name.
+5. Show the final preview or document to the user before calling it ready.
+6. State clearly which fields remain empty, uncertain, unsigned or unsubmitted.

package/skills/fill-forms/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fill Forms"
+  short_description: "Safely fill and verify local PDF and DOCX forms"
+  default_prompt: "Use fill-forms to inspect and safely complete this local form."

package/skills/fill-forms/references/overlay-technique.md

@@ -0,0 +1,99 @@
+# Coordinate Overlay Technique
+
+Read this reference before filling a non-trivial flat PDF. For ordinary
+AcroForm documents, named fields are safer and this guide is unnecessary.
+
+## Coordinate system
+
+PyMuPDF uses PDF points (1 point is 1/72 inch), with the origin at the top-left.
+The x axis increases to the right and the y axis increases downward.
+`insert_text((x, y), ...)` places the text baseline at `(x, y)`.
+
+The PNG grids produced by `inspect_pdf.py` use the same coordinates. No manual
+pixel-to-point conversion is needed.
+
+## Anchor to existing text
+
+For a checkbox, signature line or narrow field, locate a nearby printed label
+and derive an offset from its exact PDF word bounds:
+
+```python
+import fitz
+
+doc = fitz.open("form.pdf")
+for word in doc[0].get_text("words"):
+    if word[4] == "Consent":
+        print(word[:5])
+```
+
+A word tuple starts with `(x0, y0, x1, y1, text)`. Position the field relative
+to those bounds and verify the result in a high-resolution clipped preview.
+Do not treat an estimated offset as final evidence.
+
+## Text baselines and boxes
+
+Use the line on which the text should sit as the initial y coordinate. If the
+text falls below the line, decrease y; if it floats too high, increase y.
+Adjust in small steps.
+
+For a checkbox, place the X near the horizontal centre and use the lower part
+of the box as the initial baseline. Verify at high zoom.
+
+## Character-by-character fields
+
+Use `spread.step` for account numbers, dates or identifiers printed as separate
+boxes:
+
+```json
+{
+  "page": 0,
+  "x": 70,
+  "y": 410,
+  "text": "XX00EXAMPLE0000000000000000",
+  "spread": {"step": 17.5}
+}
+```
+
+Measure `step` from two adjacent boxes on the coordinate grid. `spread.skip`
+accepts zero-based character indexes that should not be drawn while retaining
+their spacing.
+
+## Long text and fonts
+
+The overlay script does not wrap text automatically. Reduce the per-item
+`size`, split the content into explicitly positioned lines, or leave the field
+for manual completion rather than allowing text to overlap legal wording.
+
+The built-in PDF font is suitable for common Latin text. For another script or
+missing glyph, use a locally available, appropriately licensed TTF/OTF through
+the top-level `font_file` configuration. Do not bundle private or unlicensed
+fonts.
+
+## Signature images
+
+Insert a signature only after explicit authorisation from the signer for the
+specific document. Prepare the image locally with `prepare_signature.py` and
+keep the original and prepared image outside source control.
+
+Use a transparent PNG and a rectangle whose proportions are close to the
+signature. Avoid stretching it unnaturally. Place it so the visible stroke
+rests on the intended line, then inspect the result on a pure white background
+and in a clipped high-resolution preview.
+
+The fill script downsizes very large inserted images to the resolution needed
+for the target rectangle. This avoids embedding a multi-megapixel source into
+a small signature area.
+
+## Focused verification
+
+Render a critical region rather than relying only on a full-page preview:
+
+```python
+clip = fitz.Rect(x0, y0, x1, y1)
+pix = doc[page_number].get_pixmap(clip=clip, dpi=240)
+pix.save("verification-region.png")
+```
+
+Check every populated field, not only representative examples. Treat the
+completed file as a draft until the user has reviewed it. Filling a form does
+not authorise signing, sending or submission.

package/skills/fill-forms/requirements.txt

@@ -0,0 +1,4 @@
+PyMuPDF>=1.24,<2
+Pillow>=10,<13
+numpy>=1.26,<3
+python-docx>=1.1,<2

package/skills/fill-forms/scripts/dump_docx.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Print paragraphs, tables, headers and footers from a DOCX template."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Inspect text and table structure in a local DOCX form."
+    )
+    parser.add_argument("docx", type=Path)
+    return parser.parse_args()
+
+
+def load_docx():
+    try:
+        import docx
+    except ImportError as exc:
+        raise SystemExit(
+            "Missing dependency: python-docx. With user consent, install the "
+            "packages listed in the skill's requirements.txt."
+        ) from exc
+    return docx
+
+
+def print_paragraphs(paragraphs, heading: str) -> None:
+    print(f"== {heading} ==")
+    for index, paragraph in enumerate(paragraphs):
+        text = paragraph.text.strip()
+        if text:
+            print(f"[{index}] {text}")
+
+
+def print_tables(tables, heading: str) -> None:
+    for table_index, table in enumerate(tables):
+        print(
+            f"\n== {heading} TABLE {table_index} "
+            f"({len(table.rows)}x{len(table.columns)}) =="
+        )
+        for row_index, row in enumerate(table.rows):
+            cells = [cell.text.strip() for cell in row.cells]
+            print(f"  row {row_index}: {cells}")
+
+
+def main() -> None:
+    args = parse_args()
+    if not args.docx.is_file():
+        raise SystemExit(f"DOCX not found or not a regular file: {args.docx}")
+
+    docx = load_docx()
+    try:
+        document = docx.Document(args.docx)
+    except Exception as exc:
+        raise SystemExit(f"Could not open DOCX: {exc}") from exc
+
+    print_paragraphs(document.paragraphs, "BODY PARAGRAPHS")
+    print_tables(document.tables, "BODY")
+
+    for section_index, section in enumerate(document.sections):
+        print_paragraphs(section.header.paragraphs, f"HEADER {section_index}")
+        print_tables(section.header.tables, f"HEADER {section_index}")
+        print_paragraphs(section.footer.paragraphs, f"FOOTER {section_index}")
+        print_tables(section.footer.tables, f"FOOTER {section_index}")
+
+
+if __name__ == "__main__":
+    main()