diff --git a/AGENTS.md b/AGENTS.md index 249630a..c218162 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent Instructions -- Follow repository coding conventions documented in `README.md` and `WHERE-TO-SAVE-FILES.txt`. +- Follow the usage, repository-layout, and data-handling conventions in `README.md`. - Prefer descriptive commit messages summarizing the changes. - Run relevant tests under the `tests/` directory before submitting a change. - Keep documentation clear and updated when behavior changes. diff --git a/README.md b/README.md index 208fa2f..18a7c3d 100644 --- a/README.md +++ b/README.md @@ -201,17 +201,51 @@ Generated diagrams include: ```text PSNetMap/ -├── CHANGELOG.md # Release history -├── LICENSE # MIT license -├── README.md # Main documentation (this file) -├── STRUCTURE.md # Additional notes on the folder layout -├── WHERE-TO-SAVE-FILES.txt # Tips for keeping inventories outside the repo -├── NetDiagram-PS/ # PowerShell module manifest & implementation -├── examples/ # Wizard script plus sample JSON templates -└── tests/ # Pester test suite +├── .github/workflows/ci.yml # Three-OS Pester and analyzer checks +├── .gitignore # Generated files, packages, and editor state +├── AGENTS.md # Local contributor instructions +├── CHANGELOG.md # Release history +├── LICENSE # MIT license +├── PUBLISHING.md # Gallery packaging and release procedure +├── README.md # Main documentation and conventions +├── NetDiagram-PS/ +│ ├── NetDiagram-PS.psd1 # Module manifest +│ └── NetDiagram-PS.psm1 # Module implementation +├── examples/ +│ ├── New-NetworkDiagram.ps1 # Guided discovery wizard +│ ├── credmap.json # SNMP credential-map template +│ └── inventory-template.json # Inventory template +└── tests/ + └── NetDiagram.Tests.ps1 # Pester test suite ``` -The module ships without a separate `docs/` directory. All user-facing documentation currently lives in the files listed above. +This is the single maintained repository-layout reference. Update it when tracked +top-level files or test entry points change. + +### Keep generated network data outside the clone + +Diagrams, inventories, and credential maps can describe private infrastructure. Use a +separate working directory so generated data is not accidentally committed. + +Windows PowerShell: + +```powershell +New-Item -ItemType Directory -Path C:\MyNetworkDocs -Force +Set-Location C:\MyNetworkDocs +Import-Module C:\Path\To\PSNetMap\NetDiagram-PS\NetDiagram-PS.psd1 +``` + +macOS or Linux: + +```powershell +New-Item -ItemType Directory -Path "$HOME/network-docs" -Force +Set-Location "$HOME/network-docs" +Import-Module /path/to/PSNetMap/NetDiagram-PS/NetDiagram-PS.psd1 +``` + +Save files such as `my-inventory.json`, `my-network.drawio`, and local credential maps +in that working directory. Do not put secret values in a credential map; store them with +PowerShell SecretManagement as shown in the SNMP example above. --- @@ -419,4 +453,3 @@ Import-Inventory my-network-inventory.json | Export-DrawIO -OutFile my-network.d 2. Check command help: `Get-Help -Examples` 3. Review example files in `examples/` 4. Report issues with detailed error messages - diff --git a/STRUCTURE.md b/STRUCTURE.md deleted file mode 100644 index 9389169..0000000 --- a/STRUCTURE.md +++ /dev/null @@ -1,88 +0,0 @@ -# PSNetMap - Folder Structure - -This document describes the folder structure following PowerShell module best practices. - -## Directory Layout - -``` -PSNetMap/ -├── .github/ -│ └── workflows/ -│ └── ci.yml # CI: Pester (Win/macOS/Linux) + PSScriptAnalyzer -├── CHANGELOG.md # Release history -├── LICENSE # MIT License -├── PUBLISHING.md # PowerShell Gallery release process -├── README.md # Main documentation & quick start -├── STRUCTURE.md # This file -├── WHERE-TO-SAVE-FILES.txt # Guidance on storing personal data -├── NetDiagram-PS/ # PowerShell module root -│ ├── NetDiagram-PS.psd1 # Module manifest (exports cmdlets) -│ └── NetDiagram-PS.psm1 # Module implementation -├── examples/ # Example files and helper scripts -│ ├── New-NetworkDiagram.ps1 # Quick-start wizard script -│ ├── credmap.json # Credential mapping template -│ └── inventory-template.json # Inventory template -└── tests/ # Pester test suite - └── NetDiagram.Tests.ps1 # Tests for the module functions -``` - -## Continuous Integration - -`.github/workflows/ci.yml` runs on every push/PR to `main`: -- **Pester** test suite on `ubuntu-latest`, `macos-latest`, and `windows-latest`. -- **PSScriptAnalyzer** (fails the build on any Error-severity finding). -- Manifest validation via `Test-ModuleManifest`. - -## Best Practices Implemented - -### ✅ Standard PowerShell Module Layout -- Module files are in `NetDiagram-PS/` folder (matches module name) -- Module manifest (`.psd1`) and script (`.psm1`) are together -- Follows conventions used by PowerShell Gallery modules - -### ✅ Clear Separation of Concerns -- **Module code**: `NetDiagram-PS/` -- **Examples & helpers**: `examples/` -- **Tests**: `tests/` -- **Documentation**: Root directory - -### ✅ Proper Documentation -- `README.md` - Quick start, usage, and repository layout -- `LICENSE` - MIT License -- `CHANGELOG.md` - Version history -- `STRUCTURE.md` - Supplemental structure reference -- `WHERE-TO-SAVE-FILES.txt` - Guidance for keeping generated data outside the repo - -### ✅ Git Configuration -- `.gitignore` excludes: - - User-specific files (my-network-inventory.json) - - Build artifacts (*.nupkg) - - IDE files (.vscode/, .idea/) - - Secrets (*.key, credentials.json) - -## Module Import - -Import the module using: - -```powershell -Import-Module .\NetDiagram-PS\NetDiagram-PS.psd1 -``` - -Or for development, use `-Force` to reload: - -```powershell -Import-Module .\NetDiagram-PS\NetDiagram-PS.psd1 -Force -``` - -## Quick Start - -For the easiest experience, run the wizard: - -```powershell -.\examples\New-NetworkDiagram.ps1 -``` - ---- - -**Last Updated:** 2026-07-30 -**Module Version:** 1.3.0 diff --git a/WHERE-TO-SAVE-FILES.txt b/WHERE-TO-SAVE-FILES.txt deleted file mode 100644 index a01f888..0000000 --- a/WHERE-TO-SAVE-FILES.txt +++ /dev/null @@ -1,23 +0,0 @@ -WHERE TO SAVE YOUR NETWORK DIAGRAMS AND INVENTORIES -==================================================== - -❌ DON'T save your files in this module directory! - -✅ DO create a separate workspace folder: - - # Example: - mkdir C:\MyNetworkDocs - cd C:\MyNetworkDocs - - # Import the module - Import-Module C:\Path\To\PSNetMap\NetDiagram-PS\NetDiagram-PS.psd1 - - # Now create your files here: - # - my-inventory.json - # - my-network.drawio - # - credmap.json - # etc. - -This keeps the module clean and your personal network data separate. - -For more help, see README.md