diff --git a/.paul/ROADMAP.md b/.paul/ROADMAP.md index 2784f30..0dd3a91 100644 --- a/.paul/ROADMAP.md +++ b/.paul/ROADMAP.md @@ -117,4 +117,17 @@ Completed: 2026-05-17 **Plans:** [x] 09-01: LicenseGenerator standalone tool + real public key embedded --- -*Roadmap updated: 2026-05-17 — v0.2 NcProgramManager complete (all 4 phases)* + +## Standalone Phases (post-v0.2) + +| Phase | Name | Plans | Status | +|-------|------|-------|--------| +| 10 | readme-docs | 1 | ✅ Complete | 2026-05-17 | + +### Phase 10: readme-docs ✅ +**Goal:** Write Italian README for NcProgramManager and LicenseGenerator repos — describe what each does, prerequisites, setup, CLI usage, license workflow. +**Depends on:** Phase 09 (license workflow complete) +**Plans:** [x] 10-01: Italian READMEs for both repos + +--- +*Roadmap updated: 2026-05-17 — Phase 10 readme-docs complete. Project fully documented.* diff --git a/.paul/STATE.md b/.paul/STATE.md index 9b1a789..e28bb7d 100644 --- a/.paul/STATE.md +++ b/.paul/STATE.md @@ -5,25 +5,26 @@ See: .paul/PROJECT.md (updated 2026-05-17) **Core value:** Machinists transfer CNC programs to/from any controller without manual steps or internet -**Current focus:** v0.2 complete — offline license system fully shipped +**Current focus:** All phases complete — project fully documented ## Current Position Milestone: v0.2 NcProgramManager — COMPLETE -Phase: 4 of 4 (09-license-generator) — Complete -Plan: 09-01 complete -Status: Milestone v0.2 complete. Ready to plan next milestone or ship. -Last activity: 2026-05-17 — Phase 09 license-generator complete (UNIFY done) +Phase: 10 (readme-docs) — Complete +Plan: 10-01 complete +Status: All phases done. Project complete. +Last activity: 2026-05-17 — Italian READMEs written for both repos Progress: - Milestone v0.1: [██████████] 100% (complete) - Milestone v0.2: [██████████] 100% (complete) +- Phase 10 (readme-docs): [██████████] 100% (complete) ## Loop Position ``` PLAN ──▶ APPLY ──▶ UNIFY - ✓ ✓ ✓ [Loop complete — milestone v0.2 done] + ✓ ✓ ✓ [Loop complete — project fully documented] ``` ## What Was Built (v0.1 Multi-CN Release) @@ -83,6 +84,10 @@ PLAN ──▶ APPLY ──▶ UNIFY - Real public key embedded in `Licensing/LicenseValidator.cs` (PLACEHOLDER removed) - `private.key.xml` at `~/Documents/mine/c#/LicenseGenerator/` (gitignored — keep secure) +### Phase 10 — README Docs +- `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) - `-manufacturer=fanuc|heidenhain|siemens|mitsubishi` (default: fanuc) - `-azione=` — action (Scarica/Invia/etc.) @@ -114,7 +119,7 @@ PLAN ──▶ APPLY ──▶ UNIFY - `private.key.xml` owned by root — run `sudo chown $USER ~/Documents/mine/c#/LicenseGenerator/private.key.xml` ### Blockers/Concerns -None — v0.2 milestone complete. +None — project complete. ### Git State Last commit (NcProgramManager): see `git log --oneline` @@ -124,9 +129,9 @@ Branch: main ## Session Continuity Last session: 2026-05-17 -Stopped at: v0.2 milestone complete (Phase 09 UNIFY done) -Next action: Plan next milestone or ship v0.2 -Resume file: .paul/ROADMAP.md +Stopped at: Phase 10 complete — all phases done +Next action: git commit docs(10-readme-docs), then project is fully shipped +Resume file: .paul/phases/10-readme-docs/10-01-SUMMARY.md --- *STATE.md — Updated after every significant action* diff --git a/.paul/paul.json b/.paul/paul.json index 03f49de..37019ce 100644 --- a/.paul/paul.json +++ b/.paul/paul.json @@ -7,8 +7,8 @@ "status": "complete" }, "phase": { - "number": 9, - "name": "license-generator", + "number": 10, + "name": "readme-docs", "status": "complete" }, "loop": { @@ -17,7 +17,7 @@ }, "timestamps": { "created_at": "2026-05-13T00:00:00Z", - "updated_at": "2026-05-17T23:45:00Z" + "updated_at": "2026-05-17T00:00:00Z" }, "satellite": { "groom": true diff --git a/.paul/phases/10-readme-docs/10-01-PLAN.md b/.paul/phases/10-readme-docs/10-01-PLAN.md new file mode 100644 index 0000000..cc8afe9 --- /dev/null +++ b/.paul/phases/10-readme-docs/10-01-PLAN.md @@ -0,0 +1,194 @@ +--- +phase: 10-readme-docs +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - README.md + - ~/Documents/mine/c#/LicenseGenerator/README.md +autonomous: true +--- + + +## Goal +Write Italian-language README for both repos: NcProgramManager (operator-facing — what it does, CLI args, license setup) and LicenseGenerator (vendor-facing — key pair generation, license issuance workflow). + +## Purpose +Operators and integrators need setup and usage docs in Italian. The license workflow spans both tools, so each README must describe its role in the full chain. + +## Output +- `README.md` in NcProgramManager repo root +- `README.md` in LicenseGenerator repo root (`~/Documents/mine/c#/LicenseGenerator/`) + + + +## Project Context +@.paul/PROJECT.md +@.paul/STATE.md + +## Source Files +@Licensing/LicenseValidator.cs +@Program.cs +@InputArgs.cs + + + + +## AC-1: NcProgramManager README covers all CLI args and license setup +```gherkin +Given an operator reading NcProgramManager/README.md +When they follow the instructions +Then they can place license.lic next to the EXE and run the tool with correct args for their CNC manufacturer +``` + +## AC-2: LicenseGenerator README covers full vendor license issuance workflow +```gherkin +Given a vendor reading LicenseGenerator/README.md +When they follow the instructions +Then they can run keygen once, get fingerprint from customer machine, sign and deliver license.lic +``` + +## AC-3: Both READMEs written in Italian +```gherkin +Given either README +When read by an Italian-speaking user +Then all prose, section headers, and instructions are in Italian (technical terms and CLI args remain in English) +``` + + + + + + + Task 1: Write NcProgramManager README in Italian + README.md + + Create `README.md` at NcProgramManager repo root. Italian prose throughout. Keep CLI args, file names, and code blocks in English. + + **Sections:** + + **# NcProgramManager** + One-paragraph description: software per trasferire programmi CNC da/verso controller (Fanuc FOCAS, Heidenhain LSV2, Siemens Sinumerik, Mitsubishi FTP). Console EXE Windows, funziona offline. + + **## Requisiti** + - Windows (qualsiasi versione che supporti .NET 4.7.2) + - .NET Framework 4.7.2 installato + - File `license.lic` valido (rilasciato dal fornitore) + + **## Licenza** + Explain: place `license.lic` in same folder as `NcProgramManager.exe`. Without it, software refuses to start. To obtain license: contact vendor with machine fingerprint (obtained via LicenseGenerator fingerprint command). + + **## Utilizzo** + Show CLI arg table: + | Parametro | Valori | Descrizione | + | `-manufacturer=` | `fanuc` / `heidenhain` / `siemens` / `mitsubishi` | Tipo di controller (default: fanuc) | + | `-azione=` | `Scarica` / `Invia` / ... | Azione da eseguire | + | `-ip=` | indirizzo IP | IP del controller CNC | + | `-porta=` | numero porta | Porta di connessione | + | `-username=` | nome utente | Solo per Heidenhain/Siemens/Mitsubishi | + | `-password=` | password | Solo per Heidenhain/Siemens/Mitsubishi | + + **## Esempi** + Show 2-3 concrete examples with real-looking args for Fanuc and Heidenhain. + + **## Controller supportati** + Brief table: Fanuc (FOCAS, 32-bit DLL), Heidenhain (LSV2, porta 19000), Siemens Sinumerik (FTP, `/_N_MPF_DIR/`), Mitsubishi (FTP, porta 21, `/PRG/`). + + **## Validazione programma NC** + One paragraph: before upload, NcProgramManager validates the NC program. Errors block the transfer. Warnings are logged but don't block. + + Avoid: mentioning internal class names, test infrastructure, or implementation details. + + + `cat README.md` — file exists, has all sections, Italian prose, CLI table present. + `grep "\-manufacturer" README.md` → match found. + + AC-1 and AC-3 satisfied: README covers CLI args, license setup, all in Italian. + + + + Task 2: Write LicenseGenerator README in Italian + ~/Documents/mine/c#/LicenseGenerator/README.md + + Create `README.md` at LicenseGenerator repo root. Vendor-facing — assumes technical user. Italian prose. Keep commands and file names in English. + + **Sections:** + + **# LicenseGenerator** + One-paragraph description: strumento per il fornitore per generare coppie di chiavi RSA e firmare le licenze per NcProgramManager. Non va distribuito ai clienti. + + **## Requisiti** + - `keygen` e `sign`: .NET 4.7.2 (Windows) o Mono 6+ (Linux/Mac) + - `fingerprint`: Windows obbligatorio (usa WMI) + + **## Primo avvio — Generazione della coppia di chiavi** + Step-by-step: + 1. Run `LicenseGenerator.exe keygen` + 2. Saves `private.key.xml` in current dir — **mantenere segreto, non condividere mai** + 3. Prints public key XML to stdout — copy and paste into `LicenseValidator.cs` (field `PublicKeyXml`) and recompile NcProgramManager + + Warn clearly: if private.key.xml is lost, must generate a new key pair and re-ship NcProgramManager with new public key. + + **## Workflow per emettere una licenza** + Numbered steps: + 1. Il cliente esegue `LicenseGenerator.exe fingerprint` sulla macchina di destinazione (Windows) e invia il testo stampato al fornitore + 2. Il fornitore esegue: `LicenseGenerator.exe sign -key=private.key.xml -fingerprint= -out=license.lic` + 3. Il fornitore invia `license.lic` al cliente + 4. Il cliente copia `license.lic` nella stessa cartella di `NcProgramManager.exe` + + **## Comandi** + Table: + | Comando | Descrizione | + | `LicenseGenerator.exe keygen` | Genera coppia RSA 2048-bit. Salva `private.key.xml`, stampa chiave pubblica XML | + | `LicenseGenerator.exe fingerprint` | Legge l'impronta hardware della macchina (solo Windows) | + | `LicenseGenerator.exe sign -key= -fingerprint= [-out=]` | Firma l'impronta e scrive il file licenza | + + **## Sicurezza** + Short section: `private.key.xml` must never be committed to git (already in .gitignore), never shared with customers, stored securely. Anyone with the private key can forge licenses. + + Avoid: mentioning internal C# class names, RSA algorithm details, or test setup. + + + `cat ~/Documents/mine/c#/LicenseGenerator/README.md` — exists, has all sections. + `grep "fingerprint" ~/Documents/mine/c#/LicenseGenerator/README.md` → match found. + + AC-2 and AC-3 satisfied: README covers keygen, fingerprint, sign workflow, all in Italian. + + + + + + +## DO NOT CHANGE +- Any `.cs` source files in either repo +- `.paul/` directory contents (except this plan's phase files) +- `NcProgramManager.sln`, `LicenseGenerator.sln`, any `.csproj` + +## SCOPE LIMITS +- Italian prose only — no English prose outside of technical terms, CLI args, code blocks +- No code changes in either repo +- Do not add build instructions (not relevant for end users — binary is distributed) + + + + +Before declaring plan complete: +- [ ] `README.md` exists at NcProgramManager repo root +- [ ] `~/Documents/mine/c#/LicenseGenerator/README.md` exists +- [ ] Both files contain Italian prose +- [ ] NcProgramManager README has CLI arg table with all 6 args +- [ ] LicenseGenerator README has numbered license issuance workflow +- [ ] Both READMEs mention `license.lic` + + + +- Both READMEs written and saved +- Italian throughout (technical terms/commands in English) +- Operator can follow NcProgramManager README to set up and run the tool +- Vendor can follow LicenseGenerator README to issue a license + + + +After completion, create `.paul/phases/10-readme-docs/10-01-SUMMARY.md` + diff --git a/.paul/phases/10-readme-docs/10-01-SUMMARY.md b/.paul/phases/10-readme-docs/10-01-SUMMARY.md new file mode 100644 index 0000000..74a5024 --- /dev/null +++ b/.paul/phases/10-readme-docs/10-01-SUMMARY.md @@ -0,0 +1,93 @@ +--- +phase: 10-readme-docs +plan: 01 +subsystem: docs +tags: [readme, italian, license, cli] + +requires: + - phase: 09-license-generator + provides: keygen/fingerprint/sign commands and full license workflow + +provides: + - Italian README for NcProgramManager (operator-facing) + - Italian README for LicenseGenerator (vendor-facing) + +affects: [] + +tech-stack: + added: [] + patterns: [] + +key-files: + created: + - README.md + - ~/Documents/mine/c#/LicenseGenerator/README.md + modified: [] + +key-decisions: + - "Italian prose throughout; technical terms, CLI args, file names, code blocks in English" + +patterns-established: [] + +duration: ~5min +started: 2026-05-17T00:00:00Z +completed: 2026-05-17T00:00:00Z +--- + +# Phase 10 Plan 01: readme-docs Summary + +**Italian README written for both repos: NcProgramManager (operator — CLI args, license setup) and LicenseGenerator (vendor — keygen, fingerprint, sign workflow).** + +## Performance + +| Metric | Value | +|--------|-------| +| Duration | ~5 min | +| Started | 2026-05-17 | +| Completed | 2026-05-17 | +| Tasks | 2 completed | +| Files modified | 2 | + +## Acceptance Criteria Results + +| Criterion | Status | Notes | +|-----------|--------|-------| +| AC-1: NcProgramManager README covers all CLI args and license setup | Pass | All 6 args in table; license.lic placement explained | +| AC-2: LicenseGenerator README covers full vendor license issuance workflow | Pass | 4-step numbered workflow; keygen/fingerprint/sign commands documented | +| AC-3: Both READMEs written in Italian | Pass | Italian prose throughout; technical terms/commands in English | + +## Accomplishments + +- NcProgramManager README: description, requirements, license setup, 6-arg CLI table, 3 examples (Fanuc/Heidenhain/Siemens), supported controllers table, NC validation note +- LicenseGenerator README: vendor-only framing, keygen first-run steps, 4-step license issuance workflow, commands table, security section + +## Files Created/Modified + +| File | Change | Purpose | +|------|--------|---------| +| `README.md` | Created | Operator-facing Italian docs for NcProgramManager | +| `~/Documents/mine/c#/LicenseGenerator/README.md` | Created | Vendor-facing Italian docs for LicenseGenerator | + +## Decisions Made + +None — followed plan as specified. + +## Deviations from Plan + +None — plan executed exactly as written. + +## Issues Encountered + +None. + +## Next Phase Readiness + +**Ready:** Both repos fully documented. Project complete. + +**Concerns:** None. + +**Blockers:** None. + +--- +*Phase: 10-readme-docs, Plan: 01* +*Completed: 2026-05-17* diff --git a/README.md b/README.md new file mode 100644 index 0000000..0668b0b --- /dev/null +++ b/README.md @@ -0,0 +1,67 @@ +# NcProgramManager + +Software per il trasferimento di programmi CNC da e verso controller di macchine utensili. Supporta Fanuc (FOCAS), Heidenhain (LSV2), Siemens Sinumerik (FTP) e Mitsubishi (FTP). Funziona completamente offline come applicazione console per Windows. + +## Requisiti + +- Windows (qualsiasi versione compatibile con .NET Framework 4.7.2) +- .NET Framework 4.7.2 installato +- File `license.lic` valido (rilasciato dal fornitore) + +## Licenza + +Copiare il file `license.lic` nella stessa cartella dell'eseguibile `NcProgramManager.exe`. Senza licenza valida il programma si chiude all'avvio. + +Per ottenere una licenza contattare il fornitore fornendo l'impronta hardware della macchina. L'impronta si ottiene eseguendo il comando `fingerprint` dello strumento `LicenseGenerator.exe` sulla macchina di destinazione. + +## Utilizzo + +``` +NcProgramManager.exe -manufacturer= -azione= -ip= -porta= [opzioni] +``` + +### Parametri + +| Parametro | Valori | Descrizione | +|-----------|--------|-------------| +| `-manufacturer=` | `fanuc` / `heidenhain` / `siemens` / `mitsubishi` | Tipo di controller CNC (predefinito: `fanuc`) | +| `-azione=` | `Scarica` / `Invia` / ... | Azione da eseguire | +| `-ip=` | indirizzo IP | Indirizzo IP del controller CNC | +| `-porta=` | numero porta | Porta di connessione | +| `-username=` | nome utente | Solo per Heidenhain, Siemens, Mitsubishi | +| `-password=` | password | Solo per Heidenhain, Siemens, Mitsubishi | + +La licenza viene letta automaticamente dal file `license.lic` nella cartella dell'eseguibile — nessun parametro aggiuntivo richiesto. + +## Esempi + +Scarica programma da controller Fanuc: + +``` +NcProgramManager.exe -manufacturer=fanuc -azione=Scarica -ip=192.168.1.100 -porta=8193 +``` + +Invia programma a controller Heidenhain: + +``` +NcProgramManager.exe -manufacturer=heidenhain -azione=Invia -ip=192.168.1.50 -porta=19000 -username=operator -password=secret +``` + +Scarica programma da Siemens Sinumerik: + +``` +NcProgramManager.exe -manufacturer=siemens -azione=Scarica -ip=192.168.1.200 -porta=21 -username=admin -password=secret +``` + +## Controller supportati + +| Produttore | Protocollo | Porta predefinita | Note | +|------------|------------|-------------------|------| +| Fanuc | FOCAS (DLL 32-bit) | 8193 | Richiede `fwlib32.dll` nella stessa cartella | +| Heidenhain | LSV2 (TCP) | 19000 | Testato su TNC series | +| Siemens | FTP | 21 | Directory programmi: `/_N_MPF_DIR/` — richiede opzione FTP abilitata sul Sinumerik | +| Mitsubishi | FTP | 21 | Directory programmi: `/PRG/` | + +## Validazione del programma NC + +Prima di inviare un programma al controller, NcProgramManager esegue una validazione automatica del codice NC. Gli errori bloccano il trasferimento. Gli avvisi vengono registrati ma non interrompono l'operazione.