WIP: Update usability and repo clarity

[petrs]

This pull request introduces several improvements to the AlgTest JavaCard testing tools, focusing on enhanced usability, error handling, and support for new smartcard profiles. The most significant changes are:

• more detailed help system for users
• improved logging with a new verbosity option
• better error reporting and recovery during performance tests
• cleanup of repository for improved clarity

More detailed description is provided below.

---

Usability and Documentation Improvements:

• Added a more detailed help system to AlgTestJClient, including usage examples, common troubleshooting tips, and bug reporting instructions. This is shown when the -help flag is used. [1] [2]
• Updated the version history and changelog to reflect the new help features.

Logging and Output Enhancements:

• Introduced a -verbose command-line flag to control console output detail; detailed per-algorithm logs are now shown on the console only when verbose mode is enabled, but always written to the log file. [1] [2] [3] [4]
• Improved end-of-test messaging, clarifying where results are stored and encouraging users to submit results.

Error Handling and Recovery:

• Enhanced error handling in performance testing: detects card removal or communication loss, provides clearer recovery instructions, and prompts the user to retry or skip problematic algorithms. [1] [2]

[Copilot]

Pull request overview

This PR aims to improve JCAlgTest usability and repository clarity by expanding user-facing documentation/help, introducing a console verbosity flag, hardening performance-test recovery behavior, and updating project/repo housekeeping files.

Changes:

• Expanded README/help guidance (examples, troubleshooting, contribution instructions) and added several new reference docs under docs/.
• Added a -verbose CLI flag and extended logging/error-handling paths for performance testing.
• Updated NetBeans/Ant project metadata and repo ignore rules as part of cleanup.

Reviewed changes

Copilot reviewed 17 out of 20 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
docs/smartcard_shops.txt	Adds a short list of smartcard vendor links.
docs/card_identification.txt	Adds reference links for identifying cards (NXP IDENTIFY, tooling sources).
docs/RID_list.txt	Adds a large RID-to-applicant mapping list (data/reference).
docs/DESFireSupportReadme.md	Adds extensive DESFire/Chameleon Mini documentation and usage examples.
coverity_model	Removes a previously-empty Coverity model stub.
README.md	Major usability/documentation expansion (modes, prerequisites, FAQ, contribution flow).
AlgTest_Process/run.bat	Changes output paths for generated web artifacts.
AlgTest_Process/nbproject/project.properties	Updates build classpath references for AlgTestProcess.
AlgTest_Process/cplc.py	Extends IC type mapping and removes duplicated logic.
AlgTest_JClient/src/algtestjclient/PerformanceTesting.java	Improves exception messaging and adds reconnect/retry guidance during perf tests.
AlgTest_JClient/src/algtestjclient/DirtyLogger.java	Adds “detail” logging methods and a verbose flag on the logger.
AlgTest_JClient/src/algtestjclient/Args.java	Introduces -verbose CLI flag.
AlgTest_JClient/src/algtestjclient/AlgTestJClient.java	Adds richer --help output and a top-level error banner; wires verbose into logger construction.
AlgTest_JClient/nbproject/project.xml	Adds a NetBeans build extension referencing build-native.xml.
AlgTest_JClient/nbproject/project.properties	Updates jcardsim jar reference and enables native bundling (and tweaks classpath).
AlgTest_JClient/nbproject/genfiles.properties	Updates generated CRCs for NetBeans build files.
AlgTest_JClient/nbproject/build-impl.xml	Imports build-native.xml into the generated Ant build.
.gitignore	Adds additional ignored paths (e.g., heap/, client logs, store output).

Comments suppressed due to low confidence (1)

AlgTest_JClient/src/algtestjclient/DirtyLogger.java:67

• m_verbose is set via the new constructor, but the regular print/println methods ignore it, and printlnDetail/printDetail aren’t used anywhere else in the codebase. As a result, the -verbose flag currently has no effect on console verbosity. Either route the noisy per-algorithm output through the *Detail methods, or have print/println support log levels so the flag actually changes what is printed to stdout.

    boolean             m_verbose = false;

    public DirtyLogger(FileOutputStream logFile, boolean bOutputSystemOut) {
        m_logFile = logFile;
        m_bOutputSystemOut = bOutputSystemOut;
    }

    public DirtyLogger(FileOutputStream logFile, boolean bOutputSystemOut, boolean verbose) {
        m_logFile = logFile;
        m_bOutputSystemOut = bOutputSystemOut;
        m_verbose = verbose;
    }

    public void println() {
        String logLine = "\n";
        print(logLine);
    }
    public void println(String logLine)  {
        logLine += "\n";
        print(logLine);
    }
    public void print(String logLine) {
        if (m_bOutputSystemOut) {
            System.out.print(logLine);
        }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Typos/grammar in the new table section reduce readability: “ussage” → “usage”, and “scales with increases data size” should be rephrased (e.g., “scales with increasing data size”). Also the last cell ends with an extra trailing semicolon.

Suggested change

	| **ALG_SUPPORT_EXTENDED** | Which JCA/JCE algorithms the card firmware supports and which key sizes are accepted | Knowing exactly what a card offers for ussage in your applet; checking whether firmware updates added new algorithms |
	| **ALG_PERFORMANCE_STATIC** | Throughput and latency of every supported algorithm on 256-byte payloads | Comparing the speed of crypto operations across cards or choosing the fastest algorithm for your protocol |
	| **ALG_PERFORMANCE_VARIABLE** | Same as above, using payload sizes from 16 to 512 bytes (16, 32, 64, 128, 256, 512) | Understanding how performance scales with increases data size (due to limited internal memory); |
	| **ALG_SUPPORT_EXTENDED** | Which JCA/JCE algorithms the card firmware supports and which key sizes are accepted | Knowing exactly what a card offers for usage in your applet; checking whether firmware updates added new algorithms |
	| **ALG_PERFORMANCE_STATIC** | Throughput and latency of every supported algorithm on 256-byte payloads | Comparing the speed of crypto operations across cards or choosing the fastest algorithm for your protocol |
	| **ALG_PERFORMANCE_VARIABLE** | Same as above, using payload sizes from 16 to 512 bytes (16, 32, 64, 128, 256, 512) | Understanding how performance scales with increasing data size (due to limited internal memory). |

[MaryBak]

Indeed, the found typos should be addressed

[Copilot]

Several typos in this safety note make it hard to read: “itslef”, “cannot effort”, and “loose” should be corrected (e.g., “itself”, “cannot afford”, “lose”).

Suggested change

The AlgTest applet only performs allocation and cryptographic test operations — it does not modify persistent card data outside its own applet storage. However, the extensive testing may cause your card to temporarily block/cripple itslef due to faulty firmware. The problem is typically solved after card restart and applet removal, but some cards can be completely blocked (see [KNOWN_ISSUES.md](KNOWN_ISSUES.md)). **ALG_SUPPORT_EXTENDED** operation is typically safe, more extensive performance testing is potentially more dangerous. It is good practice to test on a dedicated card and uninstall the applet when done (see Uninstall above). Assume that your card can be blocked and do not use card you cannot effort to loose.

The AlgTest applet only performs allocation and cryptographic test operations — it does not modify persistent card data outside its own applet storage. However, the extensive testing may cause your card to temporarily block/cripple itself due to faulty firmware. The problem is typically solved after card restart and applet removal, but some cards can be completely blocked (see [KNOWN_ISSUES.md](KNOWN_ISSUES.md)). **ALG_SUPPORT_EXTENDED** operation is typically safe, more extensive performance testing is potentially more dangerous. It is good practice to test on a dedicated card and uninstall the applet when done (see Uninstall above). Assume that your card can be blocked and do not use card you cannot afford to lose.

[MaryBak]

Indeed, the found typos should be addressed

[Copilot]

This section has multiple issues: the second header repeats DF_COMM_MODE but the examples below are for DF_ENCMODE, and there are several typos (“congiguration”, “let's”, “commanf”). Please rename the second header to match the command being documented and fix the typos to avoid confusing users.

Suggested change

	#### DF_COMM_MODE -- Manually sets the communication mode of the current session
	This commanf sets the encryption mode for cryptographic operations.
	#### DF_ENCMODE -- Manually sets the communication mode of the current session
	This command sets the encryption mode for cryptographic operations.

[MaryBak]

The relevant typo to be fixed and probably the mentioned typo in title is relevant

[Copilot]

This entry appears to have broken character encoding (e.g., Soci?t? / Fr?res). If this file is intended to be human-readable, please ensure it’s stored as UTF-8 and replace the ? placeholders with the correct accented characters so names aren’t corrupted.

Suggested change

	A000000280; Soci?t? d'Automatisation des Fr?res Bouadou - SATIM -; Algeria
	A000000280; Société d'Automatisation des Frères Bouadou - SATIM -; Algeria

[Copilot]

The troubleshooting tip says “Re-insert the card and re-run with -fresh to skip ahead”, but -fresh forces a fresh measurement (i.e., it prevents continuing from the *_already_measured.list file). To continue from the last measured algorithm, users should not use -fresh (and answer “y” when prompted to continue).

Suggested change

	System.out.println(" Re-insert the card and re-run with -fresh to skip ahead.");
	System.out.println(" Results incomplete -- Re-run with -fresh to discard partial results and start over.");
	System.out.println(" Re-insert the card and re-run without -fresh, then answer 'y' when prompted to continue from the last measurement.");
	System.out.println(" Results incomplete -- Re-run with -fresh to discard partial results and start over from the beginning.");

[MaryBak]

Overall, the introduced in the PR changes are nicely addressing the found usability issues. Upon addressing those Copilot's suggestions, could be merged

[xhanulik]

LGTM, but some of the changes proposed by Copilot look reasonable - @petrs do you wanna to keep going with this or should I take over and fix it?