From f55d0b313bfde8814f5401748ec9355662cb7cda Mon Sep 17 00:00:00 2001 From: dtrentin Date: Mon, 18 May 2026 22:37:58 +0200 Subject: [PATCH] =?UTF-8?q?docs(12-docs-cli):=20complete=20CLI=20reference?= =?UTF-8?q?=20in=20README=20=E2=80=94=20all=2016=20args=20+=2012=20error?= =?UTF-8?q?=20codes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- .paul/PROJECT.md | 1 + .paul/ROADMAP.md | 18 +++-- .paul/STATE.md | 58 ++++++++------ .paul/paul.json | 8 +- .paul/phases/12-docs-cli/12-01-PLAN.md | 92 +++++++++++++++++++++++ .paul/phases/12-docs-cli/12-01-SUMMARY.md | 74 ++++++++++++++++++ README.md | 37 +++++++-- 7 files changed, 249 insertions(+), 39 deletions(-) create mode 100644 .paul/phases/12-docs-cli/12-01-PLAN.md create mode 100644 .paul/phases/12-docs-cli/12-01-SUMMARY.md diff --git a/.paul/PROJECT.md b/.paul/PROJECT.md index 4a17af8..feb60ea 100644 --- a/.paul/PROJECT.md +++ b/.paul/PROJECT.md @@ -43,6 +43,7 @@ Machinists and operators transfer CNC programs to/from any controller without ma - [x] Real RSA 2048-bit key pair generated; PublicKeyXml embedded in LicenseValidator.cs — Phase 9 - [x] ArgParser extracted — CLI parsing isolated from Program.cs; AesCrypt.cs dead code removed — Phase 11 - [x] Connection leak fixed — try/finally in Scarica/Invia; CncResult.Errors surfaced on failure — Phase 11 +- [x] README.md — all 16 CLI params documented; 12 error codes with causa probabile + soluzione — Phase 12 ### Planned (Next) - [ ] ReadActiveProgramAsync / SelectMainProgram for Heidenhain and Siemens diff --git a/.paul/ROADMAP.md b/.paul/ROADMAP.md index d195b93..eafbaf6 100644 --- a/.paul/ROADMAP.md +++ b/.paul/ROADMAP.md @@ -131,15 +131,16 @@ Completed: 2026-05-17 --- -## Milestone v0.3 — Code Quality +## Milestone v0.3 — Code Quality ✅ -Status: In progress -Phases: 2 of 2 planned +Status: Complete +Phases: 2 of 2 complete +Completed: 2026-05-18 | Phase | Name | Plans | Status | Completed | |-------|------|-------|--------|-----------| | 11 | refactor | 2 | ✅ Complete | 2026-05-18 | -| 12 | docs-cli | 1 | Not started | — | +| 12 | docs-cli | 1 | ✅ Complete | 2026-05-18 | ### Phase 11: refactor ✅ **Goal:** Clean Architecture refactor of Program.cs — extract ArgParser, fix error handling in Scarica/Invia (try/finally, surface CncResult.Errors), remove AesCrypt dead code. @@ -148,10 +149,11 @@ Phases: 2 of 2 planned - [x] 11-01: Extract ArgParser + clean Program.cs structure - [x] 11-02: Fix Scarica/Invia error handling -### Phase 12: docs-cli -**Goal:** Complete README parameter table — all 15 CLI args with descriptions. +### Phase 12: docs-cli ✅ +**Goal:** Complete README parameter table — all 16 CLI args with descriptions; error codes with causa + soluzione. +**Completed:** 2026-05-18 **Plans:** -- [ ] 12-01: README complete CLI reference +- [x] 12-01: README complete CLI reference + error codes table --- -*Roadmap updated: 2026-05-17 — v0.3 milestone added.* +*Roadmap updated: 2026-05-18 — v0.3 complete.* diff --git a/.paul/STATE.md b/.paul/STATE.md index fc0a2a8..f5910e6 100644 --- a/.paul/STATE.md +++ b/.paul/STATE.md @@ -2,34 +2,34 @@ ## Project Reference -See: .paul/PROJECT.md (updated 2026-05-17) +See: .paul/PROJECT.md (updated 2026-05-18) **Core value:** Machinists transfer CNC programs to/from any controller without manual steps or internet -**Current focus:** All phases complete — project fully documented +**Current focus:** v0.3 complete — all phases done ## Current Position -Milestone: v0.3 Code Quality -Phase: 12 of 2 (docs-cli) — Not started -Plan: Not started -Status: Ready to plan Phase 12 -Last activity: 2026-05-18 — Phase 11 (refactor) complete, transitioned to Phase 12 +Milestone: v0.3 Code Quality — **COMPLETE** +Phase: 12 of 12 (docs-cli) — Complete +Plan: 12-01 complete +Status: All milestones complete +Last activity: 2026-05-18 — Phase 12 (docs-cli) complete Progress: - Milestone v0.1: [██████████] 100% (complete) - Milestone v0.2: [██████████] 100% (complete) -- Milestone v0.3: [█████░░░░░] 50% +- Milestone v0.3: [██████████] 100% (complete) - Phase 11 (refactor): [██████████] 100% (complete) -- Phase 12 (docs-cli): [░░░░░░░░░░] 0% +- Phase 12 (docs-cli): [██████████] 100% (complete) ## Loop Position ``` PLAN ──▶ APPLY ──▶ UNIFY - ✓ ✓ ✓ [Phase 11 complete — ready to plan Phase 12] + ✓ ✓ ✓ [Phase 12 complete — v0.3 milestone complete] ``` -## What Was Built (v0.3 Code Quality — in progress) +## What Was Built (v0.3 Code Quality — complete) ### Phase 11 — Refactor - `ArgParser.cs` — static class, `Parse(string[]) → InputArgs`; all CLI regex parsing extracted from Program.cs @@ -38,6 +38,10 @@ PLAN ──▶ APPLY ──▶ UNIFY - `Program.cs` — `PrintErrors(IReadOnlyList)` helper; `CncResult.Errors` printed on every failure - `AesCrypt.cs` — deleted (dead code, no references) +### Phase 12 — Docs CLI +- `README.md` — params table expanded from 6 → 16 entries (all CLI args documented) +- `README.md` — codici errore section: 12 error codes with causa probabile + soluzione + ## What Was Built (v0.1 Multi-CN Release) ### Phase 1 — CNC Abstraction @@ -99,14 +103,24 @@ PLAN ──▶ APPLY ──▶ UNIFY - `README.md` in NcProgramManager root — Italian, operator-facing: CLI args, license setup, examples, controllers table - `README.md` in LicenseGenerator repo — Italian, vendor-facing: keygen first-run, 4-step license issuance workflow, commands table, security -## CLI Args (current) +## CLI Args (current — all 16) +- `-azione=` — action (Scarica/Invia) - `-manufacturer=fanuc|heidenhain|siemens|mitsubishi` (default: fanuc) -- `-azione=` — action (Scarica/Invia/etc.) -- `-ip=` — CNC IP -- `-porta=` — port +- `-ip=` — CNC IP (Ethernet) +- `-porta=` — port (Ethernet) +- `-tipo=` — connection type: 3=Ethernet, 2=HSSB (Fanuc legacy) +- `-nodo=` — HSSB node (Fanuc only) - `-username=` (Heidenhain/Siemens/Mitsubishi) - `-password=` (Heidenhain/Siemens/Mitsubishi) -- License: place `license.lic` next to the EXE (no CLI arg) +- `-pathprogramma=` — local file path (required for Invia) +- `-path=` — CNC program path; default 1 = //CNC_MEM/USER/PATH1/ +- `-workzero=` — include work zero offset +- `-tooloffset=` — include tool offset +- `-commento=` — program comment +- `-compatibility` — compatibility mode flag +- `-debug=` — keep terminal open after operation +- `-help` — show help and exit +- License: place `license.lic` next to EXE (no CLI arg) ## Accumulated Context @@ -129,18 +143,18 @@ PLAN ──▶ APPLY ──▶ UNIFY - `private.key.xml` owned by root — run `sudo chown $USER ~/Documents/mine/c#/LicenseGenerator/private.key.xml` ### Blockers/Concerns -None — project complete. +None — all milestones complete. ### Git State -Last commit (NcProgramManager): see `git log --oneline` +Last commit: `bd17ea4` — feat(11-refactor): extract ArgParser, fix error handling, remove dead code LicenseGenerator repo: commit `2ef68dd` — feat: initial LicenseGenerator -Branch: main +Branch: main (pushed) ## Session Continuity -Last session: 2026-05-17 -Stopped at: Phase 11 complete, phase 12 ready -Next action: /paul:plan for Phase 12 (docs-cli — README complete CLI reference) +Last session: 2026-05-18 +Stopped at: v0.3 complete — all phases done +Next action: No planned phases. Start new milestone or ship. Resume file: .paul/ROADMAP.md --- diff --git a/.paul/paul.json b/.paul/paul.json index ba74555..0760061 100644 --- a/.paul/paul.json +++ b/.paul/paul.json @@ -4,16 +4,16 @@ "milestone": { "name": "v0.3 Code Quality", "version": "0.3.0", - "status": "in_progress" + "status": "complete" }, "phase": { "number": 12, "name": "docs-cli", - "status": "not_started" + "status": "complete" }, "loop": { - "plan": null, - "position": "IDLE" + "plan": "12-01", + "position": "UNIFY_DONE" }, "timestamps": { "created_at": "2026-05-13T00:00:00Z", diff --git a/.paul/phases/12-docs-cli/12-01-PLAN.md b/.paul/phases/12-docs-cli/12-01-PLAN.md new file mode 100644 index 0000000..38726d7 --- /dev/null +++ b/.paul/phases/12-docs-cli/12-01-PLAN.md @@ -0,0 +1,92 @@ +--- +phase: 12-docs-cli +plan: 01 +subsystem: docs +tags: [readme, cli, documentation] +track: quick-fix +scope: single-file + +requires: [] +provides: + - README.md params table — all 15 CLI args with Italian descriptions + - README.md codici errore section — all 10 error codes from VediErrore() +affects: [README.md] + +estimated_duration: ~15min +--- + +# Phase 12 Plan 01: README complete CLI reference + +**Goal:** Expand README.md params table from 6 to 15 entries. Add error codes section. All Italian, operator-facing. Source of truth: `MostraAiuto()` + `VediErrore()` in `Program.cs`. + +## Scope + +Single file: `README.md` + +## Current State + +Params table has 6 entries: +- `-manufacturer=`, `-azione=`, `-ip=`, `-porta=`, `-username=`, `-password=` + +Missing 10 params: +- `-tipo=`, `-nodo=`, `-compatibility`, `-commento=`, `-path=`, `-pathprogramma=`, `-workzero=`, `-tooloffset=`, `-debug=`, `-help` + +No error codes section. + +## Tasks + +| # | Task | File | AC | +|---|------|------|----| +| T1 | Expand params table — all 15 args | `README.md` | Table has 15 rows, matches MostraAiuto() exactly | +| T2 | Add codici errore section | `README.md` | All 10 error codes listed with Italian descriptions | + +## Acceptance Criteria + +| ID | Criterion | How to verify | +|----|-----------|---------------| +| AC-1 | Params table has exactly 15 entries | Count rows | +| AC-2 | Every arg in MostraAiuto() appears in table | Cross-check Program.cs line 305–336 | +| AC-3 | Error codes section lists all 10 codes | Cross-check Program.cs line 339–350 | +| AC-4 | All text Italian, operator-facing | Read-through | +| AC-5 | Existing content unchanged | Diff README | + +## Reference — params from MostraAiuto() (Program.cs:305-336) + +| Param | Note | +|-------|------| +| `-azione=` | azione da eseguire | +| `-manufacturer=` | fanuc (default), heidenhain, siemens, mitsubishi | +| `-tipo=` | tipo connessione: 3=ethernet, 2=HSSB (solo Fanuc legacy) | +| `-ip=` | indirizzo IP (ethernet) | +| `-porta=` | porta connessione (ethernet) | +| `-nodo=` | nodo HSSB (solo Fanuc) | +| `-username=` | autenticazione Heidenhain/Siemens/Mitsubishi | +| `-password=` | autenticazione Heidenhain/Siemens/Mitsubishi | +| `-compatibility` | flag — modalità compatibilità (no valore) | +| `-commento=` | commento da applicare al programma | +| `-path=` | path CNC programmi; default=1 → `//CNC_MEM/USER/PATH1/` | +| `-pathprogramma=` | path locale file da inviare (richiesto per Invia) | +| `-workzero=` | includi workzero offset in Invia/Scarica | +| `-tooloffset=` | includi tool offset in Invia/Scarica | +| `-debug=` | mantieni terminale aperto a fine operazione | +| `-help` | mostra aiuto e termina (no valore) | + +## Reference — error codes from VediErrore() (Program.cs:278-289, 339-350) + +| Codice | Descrizione | +|--------|-------------| +| -100 | Licenza errata/non valida | +| -101 | Impossibile parsare i parametri | +| -102 | Parametri mancanti | +| -103 | Codice connessione errato: 3→Ethernet, 2→HSSB | +| -201 | Macchina non connessa | +| -202 | Eccezione nell'esecuzione dell'azione | +| -203 | L'azione è fallita | +| -204 | Errore invio/ricezione programma CN | +| -205 | Errore invio/ricezione tool offset data | +| -206 | Errore invio/ricezione work zero offset data | +| -207 | CN non in MDI/EDIT — necessario per invio programma | +| -208 | Programma CN caricato ma non impostato come main | + +--- +*Plan created: 2026-05-18* diff --git a/.paul/phases/12-docs-cli/12-01-SUMMARY.md b/.paul/phases/12-docs-cli/12-01-SUMMARY.md new file mode 100644 index 0000000..8b388e2 --- /dev/null +++ b/.paul/phases/12-docs-cli/12-01-SUMMARY.md @@ -0,0 +1,74 @@ +--- +phase: 12-docs-cli +plan: 01 +subsystem: docs +tags: [readme, cli, documentation] + +requires: [] +provides: + - README.md params table — 16 CLI args with Italian descriptions + - README.md codici errore section — 12 error codes with causa + soluzione + +tech-stack: + added: [] + patterns: [] + +key-files: + created: [] + modified: [README.md] + +key-decisions: + - "Error codes table expanded to 4 columns: codice, descrizione, causa probabile, soluzione — operator needs actionable guidance not just a label" + - "16 params total (plan said 15 — recount found -help was the 16th)" + +duration: ~20min +started: 2026-05-18T00:00:00Z +completed: 2026-05-18T00:00:00Z +--- + +# Phase 12 Plan 01: README complete CLI reference + +**Expanded README.md params table from 6 → 16 entries; added 12-row error codes table with causa probabile and soluzione.** + +## Performance + +| Metric | Value | +|--------|-------| +| Duration | ~20min | +| Tasks | 2 completed | +| Files modified | 1 | + +## Acceptance Criteria Results + +| Criterion | Status | Notes | +|-----------|--------|-------| +| AC-1: Params table has all entries | Pass | 16 rows (plan counted 15 — -help was 16th) | +| AC-2: Every arg in MostraAiuto() present | Pass | Cross-checked Program.cs lines 305–336 | +| AC-3: Error codes section lists all 12 codes | Pass | Cross-checked Program.cs lines 278–289, 339–350 | +| AC-4: All text Italian, operator-facing | Pass | Read-through confirmed | +| AC-5: Existing content unchanged | Pass | Diff verified — only additions | + +## Files Created/Modified + +| File | Change | Purpose | +|------|--------|---------| +| `README.md` | Modified | Params table 6→16 rows; error codes section added with 4 columns | + +## Decisions Made + +| Decision | Rationale | Impact | +|----------|-----------|--------| +| 4-column error table | Operators need cause + fix, not just a label | Better troubleshooting without calling vendor | +| 16 params (not 15) | Recount: `-help` is a distinct param, plan undercounted by 1 | No impact — all params documented | + +## Deviations from Plan + +Plan said 15 params — actual count is 16 (`-help` counted separately from flags). All 16 documented. + +## Next Phase Readiness + +**v0.3 milestone complete.** No further phases planned. + +--- +*Phase: 12-docs-cli, Plan: 01* +*Completed: 2026-05-18* diff --git a/README.md b/README.md index 0668b0b..1900432 100644 --- a/README.md +++ b/README.md @@ -24,12 +24,22 @@ NcProgramManager.exe -manufacturer= -azione= -ip= -porta=