From 023506c9b3966743d37568e20f377c6a9f5d5dd5 Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 12:05:29 +0200 Subject: [PATCH 1/4] chore(memory-bank): record that the maintainer opens PRs The remote-mutation hook blocked creating the pull requests even after the maintainer's explicit request: its override is read from the environment that VS Code starts the hook with, so the agent can't set it for a single command. The hook also matches text inside commit messages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .memory-bank/activeContext.md | 18 +++++++++--------- .memory-bank/techContext.md | 9 +++++++++ 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 760b817..1252429 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -9,9 +9,10 @@ source: current task evidence ## Current focus -Work packages 1 and 2 are pushed; the maintainer opens their PRs: -`ai/housekeeping` into `master`, and `ai/ship-help` into -`ai/housekeeping`. The work packages and their order are in `progress.md`. +Work packages 1 and 2 are pushed and green; the maintainer opens their +PRs: `ai/housekeeping` into `master`, and `ai/ship-help` into +`ai/housekeeping`. The agent can't open them (see `techContext.md`, +Constraints). The work packages and their order are in `progress.md`. ## Evidence @@ -22,9 +23,9 @@ Work packages 1 and 2 are pushed; the maintainer opens their PRs: - The same build listed 870 tests on the Tests tab: the NUnit import files each Pester 5 test under every enclosing block (Pester, file, Describe, Context), so 216 tests appear four times and 2 three times. The - follow-up commit on `ai/ship-help` reports the results through the build - worker API instead (`POST api/tests/batch`), one entry per test; a local - run of step 04 against a sample test file sent 11 entries for 11 tests. + follow-up commit `c9fbaf5` reports the results through the build worker + API instead (`POST api/tests/batch`); AppVeyor 54834216 of `c9fbaf5` + passed and lists 218 tests, one entry each. - The AppVeyor job log API returns `application/octet-stream`; decode the bytes as UTF-8 before searching it. - Merging work package 1 with a merge commit keeps `ai/ship-help` valid; @@ -35,6 +36,5 @@ Work packages 1 and 2 are pushed; the maintainer opens their PRs: ## Next step -The maintainer pushes the follow-up commit on `ai/ship-help`, opens both -PRs, and checks that AppVeyor lists 218 tests; then work package 3 (Read -the Docs). +The maintainer opens both PRs with the prepared `gh pr create` commands; +then work package 3 (Read the Docs) after the go-ahead. diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index 8acbb66..812f6a3 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -70,6 +70,15 @@ source: repository evidence - `CHANGELOG.md` lists user-visible changes only; CI and build-only changes get no entry ([Decision 7](decisions/0007-changelog-user-visible-only.md)). +- Remote mutations are the maintainer's: the user-level preToolUse hook + `Block-RemoteMutation.ps1` denies `git push` and mutating `gh` commands + (`pr create`, `pr close`, and others) from the agent session, even after + an explicit request. Its override, `COPILOT_ATELIER_ALLOW_REMOTE=1`, is + read from the environment that VS Code starts the hook with; setting it + inside an agent command has no effect (verified 2026-10-04). The hook + matches the whole command text, so a commit message that quotes such a + command is blocked too. Prepare the commands and descriptions; the + maintainer runs them. ## Validation From 04ef9724305449925b590b9db27c1d0ae2c46f23 Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 12:55:26 +0200 Subject: [PATCH 2/4] chore(memory-bank): record the merge of #92 and #93 Work packages 1 and 2 are merged and master is green on AppVeyor (218 of 218 Pester tests). Mark them done, condense the older milestones, and spell out work packages 3 and 4 so a new chat can continue from the Memory Bank alone, including cleaning the installed module folder before the next release. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .memory-bank/activeContext.md | 40 +++++------- .memory-bank/progress.md | 120 ++++++++++++++++++---------------- .memory-bank/techContext.md | 5 +- 3 files changed, 84 insertions(+), 81 deletions(-) diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 1252429..6ac2f8d 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -9,32 +9,26 @@ source: current task evidence ## Current focus -Work packages 1 and 2 are pushed and green; the maintainer opens their -PRs: `ai/housekeeping` into `master`, and `ai/ship-help` into -`ai/housekeeping`. The agent can't open them (see `techContext.md`, -Constraints). The work packages and their order are in `progress.md`. +Work packages 1 (#92) and 2 (#93) are merged. Next is work package 3 (Read +the Docs), after the maintainer's go-ahead, on the local branch +`ai/read-the-docs`, which so far carries Memory Bank notes only. The +remaining packages and their details are in `progress.md`. ## Evidence -- AppVeyor 54834155 (`ai/housekeeping`, `74abb0b`) passed. AppVeyor - 54834154 (`ai/ship-help`, `fba3a7d`) passed all four `test_script` - steps; Pester passed 218 of 218 tests in Windows PowerShell 5.1, - including the `Get-Help -Online` tests. -- The same build listed 870 tests on the Tests tab: the NUnit import files - each Pester 5 test under every enclosing block (Pester, file, Describe, - Context), so 216 tests appear four times and 2 three times. The - follow-up commit `c9fbaf5` reports the results through the build worker - API instead (`POST api/tests/batch`); AppVeyor 54834216 of `c9fbaf5` - passed and lists 218 tests, one entry each. -- The AppVeyor job log API returns `application/octet-stream`; decode the - bytes as UTF-8 before searching it. -- Merging work package 1 with a merge commit keeps `ai/ship-help` valid; - after a squash merge it needs - `git rebase --onto origin/master ai/housekeeping ai/ship-help`. -- PR descriptions for both work packages are in the session folder - (`files/pr`), outside the repository. +- #92 was merged with a merge commit (`d917832`) and #93 squash-merged + (`14799fb`); the tree of `master` equals the tested `c9fbaf5`. +- AppVeyor: the PR build of #93 (54834295) and the `master` build of + `14799fb` (54834350) each passed 218 of 218 Pester tests, listed once + each on the Tests tab; the `master` build of `d917832` passed too. +- The remote branches `ai/housekeeping` and `ai/ship-help` are deleted, and + so are the local ones. The only unmerged commit, the remote-mutation note + (`9dc2022`), is now `023506c` on `ai/read-the-docs`. +- The agent can't push or open PRs (`techContext.md`, Constraints): it + prepares the commands and PR descriptions, and the maintainer runs them. ## Next step -The maintainer opens both PRs with the prepared `gh pr create` commands; -then work package 3 (Read the Docs) after the go-ahead. +Wait for the maintainer's go-ahead for work package 3. Nothing on +`ai/read-the-docs` needs pushing before then; its Memory Bank commits go +into the work package 3 PR. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 53dcd2d..59e0d3b 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -9,44 +9,31 @@ source: repository evidence ## Current status -PR #91 is merged: documentation matches the cmdlets at HEAD. The module -source is unchanged since the 4.2.6 release except the -`Remove-Item2 -PassThru` rename and `CompatiblePSEditions`. +PRs #91, #92, and #93 are merged. The documentation matches the cmdlets at +`master`, and the module ships the help file generated from it +(`en-US\NTFSSecurity.dll-Help.xml`). Otherwise the module source differs +from the 4.2.6 release only by the `Remove-Item2 -PassThru` rename and +`CompatiblePSEditions`. ## Recent milestones -- 2026-10-02: Memory Bank initialized. -- 2026-10-02: Documentation aligned with the code: 36 cmdlet pages filled - from the C# source and checked at runtime in a sandbox; Concepts, Examples, - home page, contributor guide, README rewritten; `mkdocs.yml` nav, - `edit_uri`, and `.readthedocs.yml` (`build.os`) fixed; `CHANGELOG.md` - created. -- 2026-10-02: PR #91 build fixed: `appveyor.yml` builds the module from - source and checks the docs against that build instead of the Gallery - release (root cause of the `Remove-Item2 -PassThru` drift failure). -- 2026-10-02: PR #91 merged into `master` as `690d8dd` (squash merge); - branch `ai/docs-alignment` deleted locally and on GitHub. -- 2026-10-02: Work package 1 (housekeeping, `ai/housekeeping`): local - `promptHistory.md` ignored by git; changelog policy recorded as - Decision 7; Decisions moved from `systemPatterns.md` to `decisions/`. -- 2026-10-02: PR #83 (TechNet tutorial links) reviewed and found - superseded: #91 ships the same two `learn.microsoft.com` links in - `Docs/index.md` and `README.md`. The maintainer decided to close it; - the remote-mutation hook denied the agent's `gh pr close`, so the - maintainer closed it by hand (2026-10-02 21:18 UTC). -- 2026-10-02: Work package 2 (ship help, `ai/ship-help`, stacked on - `ai/housekeeping`): `en-US\NTFSSecurity.dll-Help.xml` generated from - `Docs/Cmdlets`, committed, copied by the csproj, and listed in a complete - `FileList` (Decision 8); stale `NTFSSecurity-Help.xml` and the unused - `NTFSSecurity.Help.pshproj` removed; `Tests\Help.Tests.ps1` (Pester 5) - and two CI steps added; six inline links in five cmdlet pages reworded - because platyPS drops the space after a link in the help text. Tests: 218 - of 218 pass in Windows PowerShell 5.1; without the help file 180 of 182 - failed. -- 2026-10-04: Work packages 1 and 2 pushed; AppVeyor 54834155 - (`74abb0b`) and 54834154 (`fba3a7d`, 218 of 218 Pester tests) passed. A - follow-up commit reports each test once on the AppVeyor Tests tab - (the NUnit upload listed 870 entries). +- 2026-10-02: Memory Bank initialized. PR #91 aligned the documentation + with the code (36 cmdlet pages, conceptual pages, README, `mkdocs.yml`, + `.readthedocs.yml`, `CHANGELOG.md`) and made `appveyor.yml` build the + module and check the docs against that build (Decision 6); squash-merged + as `690d8dd`. +- 2026-10-02: PR #83 (TechNet links) closed by the maintainer as superseded + by #91. +- 2026-10-04: Work package 1 merged as PR #92 with a merge commit + (`d917832`): `promptHistory.md` ignored, Decision 7, Decisions moved to + `decisions/`. +- 2026-10-04: Work package 2 squash-merged as PR #93 (`14799fb`): generated + help file shipped (Decision 8), stale help files removed, `FileList` + complete, `Tests\Help.Tests.ps1` (218 Pester tests), CI steps 03 (help + file current) and 04 (Pester, one Tests-tab entry per test; the NUnit + upload had listed 870), six cmdlet-page links reworded for the help + text. AppVeyor passed 218 of 218 on the PR (54834295) and on `master` + (54834350). ## Stable capabilities @@ -59,30 +46,51 @@ source is unchanged since the 4.2.6 release except the ## Open work Work packages in the order agreed with the maintainer. Each gets one -`ai/` branch and PR, committed locally; the maintainer pushes, and -the next package starts only after the maintainer's go-ahead. - -1. Housekeeping: `ai/housekeeping` pushed at `74abb0b`, AppVeyor green; - PR into `master` to open. -2. Ship help: `ai/ship-help` pushed at `fba3a7d`, AppVeyor green; the - follow-up commit for the Tests tab awaits push. PR into - `ai/housekeeping` to open. -3. Read the Docs: project `ntfssecurity` (maintainer `Sup3rlativ3`) builds - the fork; switch it to this repository or import a new project. Ask - before installing Python for `mkdocs build --strict`. +`ai/` branch and PR, committed locally. The maintainer pushes and +opens the PR (the agent can't; see `techContext.md`, Constraints), and the +next package starts only after the maintainer's go-ahead. + +1. Housekeeping: done (#92). +2. Ship help: done (#93). +3. Read the Docs, next. The local branch `ai/read-the-docs` exists and so + far carries Memory Bank notes only. The project `ntfssecurity` + (`https://app.readthedocs.org/projects/ntfssecurity/`) is maintained by + GitHub user `Sup3rlativ3` and builds the fork `Sup3rlativ3/NTFSSecurity` + (last build about 2021); the repository side is ready + (`.readthedocs.yml`, `Docs/requirements.txt`). The switch happens in the + Read the Docs dashboard. Give the maintainer exact steps for both + options: (a) `Sup3rlativ3` adds him as maintainer and changes the + repository URL, or (b) he imports `raandree/NTFSSecurity` as a new + project (the slug `ntfssecurity` is taken). Ask before installing Python + for `mkdocs build --strict`. After the switch, confirm a build of + `master`, propose whether the `online version` links move to Read the + Docs (Decision 4), and add a documentation link to `README.md`. Done + when Read the Docs builds `master` of this repository and shows the + current pages. 4. Manifest and version: remove `Show-NTFSSimpleAccess` and the duplicate - inheritance entries from `CmdletsToExport` (36 cmdlets remain); ask - about the next version (with or without a `PassThur` alias), - `PowerShellVersion`, and `DotNetFrameworkVersion`; align `AssemblyInfo`. - No tag or publish. Inputs found in work package 2: `Test-ModuleManifest` - already fails on `PowerShellVersion = '2.0'` with `CompatiblePSEditions`; - releases ship Debug builds plus `.pdb`, `.xml`, and - `System.Management.Automation.dll` (`Private=True` reference), which - `FileList` doesn't list. + inheritance entries from `CmdletsToExport` (exactly 36 cmdlets + exported). Versions disagree: manifest 4.2.5, tag and Gallery 4.2.6, + `AssemblyVersion` 4.2.1.0. Propose the next SemVer version with and + without `[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the rename in + #64 is breaking), plus `PowerShellVersion` and `DotNetFrameworkVersion` + (manifest 2.0 and 3.5; the assemblies target .NET Framework 4.5.2), and + ask. Move the `[Unreleased]` entries into the new version section (ask + whether the build-only "Read the Docs build configuration" entry stays, + Decision 7) and align `AssemblyInfo`. No tag or publish. Done when + `Test-ModuleManifest` passes, 36 cmdlets are exported, and CI is green. + Inputs: `Test-ModuleManifest` already fails on + `PowerShellVersion = '2.0'` with `CompatiblePSEditions`; releases are + Debug builds published with the whole output folder (`.pdb`, `.xml`, + `System.Management.Automation.dll`), which `FileList` doesn't list. + Before the next build and `Publish-Module`, clean + `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the removed + `NTFSSecurity-Help.xml` ships again. 5. Code defects, listed below: `review: on`, one PR per group, regression test first. Pester 5 tests import `NTFSSecurity\bin\Release`, run in a - `$env:TEMP` sandbox and in `appveyor.yml`, and skip elevated cases when - not elevated. Each fix updates its cmdlet page and `CHANGELOG.md`. + `$env:TEMP` sandbox and in `appveyor.yml` (pattern: + `Tests\Help.Tests.ps1`), and skip elevated cases when not elevated; + check whether AppVeyor runs elevated. Each fix updates its cmdlet page + and `CHANGELOG.md`. ### Code defects (work package 5) diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index 812f6a3..cb82cac 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -49,8 +49,9 @@ source: repository evidence - `ModuleVersion` in the source manifest is `4.2.5`; the latest tag and Gallery release is `4.2.6`. -- HEAD differs from tag `4.2.6` only by the `Remove-Item2 -PassThur` to - `-PassThru` rename and `CompatiblePSEditions` in the manifest. +- Besides the shipped help file and its tests (#93), the module source at + `master` differs from tag `4.2.6` only by the `Remove-Item2 -PassThur` + to `-PassThru` rename and `CompatiblePSEditions` in the manifest. - `CmdletsToExport` lists `Show-NTFSSimpleAccess`, which no longer exists (WinForms code removed in `d3063de`), and repeats the inheritance cmdlets. - `Test-ModuleManifest` fails in Windows PowerShell 5.1: From 84328dc5c69c10a43390b9f64afd2d5951eca52c Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 14:11:59 +0200 Subject: [PATCH 3/4] docs: keep the documentation on GitHub and retire the wiki - Remove the Read the Docs and MkDocs configuration (.readthedocs.yml, mkdocs.yml, Docs/requirements.txt). The Read the Docs project belongs to a third party and points to a fork that no longer exists. - Rename Docs/index.md to Docs/README.md, so that GitHub shows the overview when you open the Docs folder, and link the changelog and the license relatively. - Move the version history and the installation steps from the wiki into Docs/Version-History.md and Docs/README.md. Add the notes for 4.2.5 and 4.2.6, which the wiki never had, from the commit history. - Describe previews and section anchors on GitHub in the contributor guide, and drop the changelog entry about the documentation site. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .readthedocs.yml | 21 --- CHANGELOG.md | 8 +- Docs/Contributing/02-Writing.md | 37 ++--- Docs/Contributing/04-Markdown-Specifics.md | 12 +- Docs/{index.md => README.md} | 33 +++-- Docs/Version-History.md | 152 +++++++++++++++++++++ Docs/requirements.txt | 1 - README.md | 11 +- mkdocs.yml | 57 -------- 9 files changed, 202 insertions(+), 130 deletions(-) delete mode 100644 .readthedocs.yml rename Docs/{index.md => README.md} (86%) create mode 100644 Docs/Version-History.md delete mode 100644 Docs/requirements.txt delete mode 100644 mkdocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index be2da6e..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,21 +0,0 @@ -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required -version: 2 - -# Required: the build image and the Python version -build: - os: ubuntu-24.04 - tools: - python: "3.12" - -# Build documentation with MkDocs -mkdocs: - configuration: mkdocs.yml - -# Install the MkDocs version that the site is built with -python: - install: - - requirements: Docs/requirements.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index f48741d..22a1a5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,7 @@ All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Releases up to -4.2.6 are described in the -[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) -in the wiki. +4.2.6 are described in the [version history](Docs/Version-History.md). ## [Unreleased] @@ -20,6 +18,8 @@ in the wiki. inputs, outputs, and notes, checked against the source code - Rewrite the home, concepts, examples, and contributor pages to match the current cmdlets, including module settings, privileges, and long paths +- Move the version history and the installation instructions from the wiki + into the documentation, and add the missing notes for 4.2.5 and 4.2.6 ### Fixed @@ -29,7 +29,5 @@ in the wiki. `NTFSSecurity-Help.xml` - Fix documentation examples that did not work, such as restoring permissions from a CSV file and filtering entries by account -- Fix the documentation site navigation, the "Edit on GitHub" links, and the - Read the Docs build configuration [Unreleased]: https://github.com/raandree/NTFSSecurity/compare/4.2.6...HEAD diff --git a/Docs/Contributing/02-Writing.md b/Docs/Contributing/02-Writing.md index be6b2b7..872f263 100644 --- a/Docs/Contributing/02-Writing.md +++ b/Docs/Contributing/02-Writing.md @@ -1,24 +1,25 @@ # Write documentation -The NTFSSecurity documentation is written in Markdown and built into a -website with [MkDocs][mkdocs]. This page explains how the documentation is -organized and how to change it. +The NTFSSecurity documentation is written in Markdown and lives in the +`Docs` folder of the repository, where GitHub renders it. This page explains +how the documentation is organized and how to change it. ## Documentation structure | Path | Content | | --- | --- | -| `Docs/index.md` | Home page with features, requirements, and the cmdlet list | +| `Docs/README.md` | Home page with features, requirements, installation, and the cmdlet list; GitHub shows it when you open the `Docs` folder | | `Docs/Concepts.md` | Background on security descriptors, rights, inheritance, and privileges | | `Docs/Examples.md` | Task-oriented examples | +| `Docs/Version-History.md` | Changes in 4.2.6 and earlier | | `Docs/Cmdlets/*.md` | One reference page per cmdlet, in platyPS format | | `NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml` | Help file that `Get-Help` shows, generated from `Docs/Cmdlets` | | `Docs/Contributing.md`, `Docs/Contributing/*.md` | This contributor guide | -| `mkdocs.yml` | Site settings and navigation | -| `.readthedocs.yml` | Build settings for Read the Docs | | `README.md` | Front page of the GitHub repository | +| `CHANGELOG.md` | Changes since 4.2.6 | -When you add a page, add it to the `nav` section of `mkdocs.yml`. +When you add a page, link to it from `Docs/README.md` or from a related page, +so that readers can find it. ## Markdown editors @@ -59,8 +60,8 @@ Use Windows PowerShell 5.1 for platyPS. In PowerShell 7.4 and later, platyPS 0.14.2 adds the `-ProgressAction` common parameter to every page. For a new cmdlet, create the page, replace every placeholder in it, and add -the page to `mkdocs.yml`. Replace `Get-NTFSExample` with the name of the new -cmdlet: +the cmdlet to the cmdlet list in `Docs/README.md`. Replace `Get-NTFSExample` +with the name of the new cmdlet: ```powershell New-MarkdownHelp -Command Get-NTFSExample -OutputFolder .\Docs\Cmdlets @@ -75,19 +76,12 @@ again and commit it together with the page: New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force ``` -## Preview the website +## Preview your change -MkDocs needs Python. Install the MkDocs version that the site is built with -and start the preview server: - -```powershell -pip install -r Docs/requirements.txt -mkdocs serve -``` - -Open `http://127.0.0.1:8000` in a browser. The preview reloads when you save -a file. Run `mkdocs build --strict` to find broken links and pages that are -missing from the navigation. +GitHub renders the pages with GitHub Flavored Markdown. To preview a page +before you push it, open it in Visual Studio Code and press **Ctrl+Shift+V**. +In a pull request, the **Files changed** tab shows a changed page rendered +when you open its menu (**...**) and select **View file**. ## Check your change @@ -132,7 +126,6 @@ workflow for larger changes in [Get started](01-Getting-Started.md). Read the [Style guide](03-Style-Guide.md). -[mkdocs]: https://www.mkdocs.org/user-guide/writing-your-docs/ [platyps]: https://github.com/PowerShell/platyPS [label-documentation]: https://github.com/raandree/NTFSSecurity/labels/Documentation [label-help-wanted]: https://github.com/raandree/NTFSSecurity/labels/Help%20Wanted diff --git a/Docs/Contributing/04-Markdown-Specifics.md b/Docs/Contributing/04-Markdown-Specifics.md index d0104cc..e99b2d3 100644 --- a/Docs/Contributing/04-Markdown-Specifics.md +++ b/Docs/Contributing/04-Markdown-Specifics.md @@ -13,7 +13,10 @@ the additional rules for the cmdlet reference pages, which platyPS processes. - Don't use hard tabs or trailing spaces. - Link to other pages with relative links to the `.md` file, for example `[Concepts](Concepts.md)` or `[Get-NTFSAccess](Cmdlets/Get-NTFSAccess.md)`. - MkDocs converts them to links to the generated pages. + GitHub renders them as links to the pages. +- Link to a section with the anchor that GitHub generates from its heading: + lowercase, with spaces replaced by hyphens and punctuation removed, for + example `[Privileges](Concepts.md#privileges)`. - End every file with a single newline. ## Cmdlet reference pages @@ -42,10 +45,3 @@ expects: add a sentence below each one. - In RELATED LINKS, write each link on its own line and separate the links with blank lines. - -## MkDocs - -- The site uses the built-in `readthedocs` theme. -- Every page must be listed in the `nav` section of `mkdocs.yml`. -- Files in `Docs` that aren't Markdown are copied to the website. Exclude - files that don't belong there with `exclude_docs` in `mkdocs.yml`. diff --git a/Docs/index.md b/Docs/README.md similarity index 86% rename from Docs/index.md rename to Docs/README.md index b1f4531..f392f97 100644 --- a/Docs/index.md +++ b/Docs/README.md @@ -38,10 +38,26 @@ Install the module from the Install-Module -Name NTFSSecurity ``` -You can also download a release from the -[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub. -If you have trouble, see -[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install). +You can also install a release without the PowerShell Gallery. Download +`NTFSSecurity.zip` from the +[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub +and extract it into a module folder. In an elevated session, these commands +install the module for all users of Windows PowerShell 5.1 and PowerShell 7: + +```powershell +Unblock-File -Path .\NTFSSecurity.zip +Expand-Archive -Path .\NTFSSecurity.zip -DestinationPath "$env:ProgramFiles\WindowsPowerShell\Modules" +``` + +`Unblock-File` removes the mark that Windows adds to downloaded files. If you +extract a marked zip file with File Explorer, the extracted files keep the +mark, and the execution policy `RemoteSigned` stops the module from loading. + +The zip file contains the folder `NTFSSecurity`. Remove an older copy of that +folder first. To install the module only for yourself, extract it into a +folder of `$env:PSModulePath` in your profile instead, for example +`Documents\WindowsPowerShell\Modules` for Windows PowerShell 5.1 or +`Documents\PowerShell\Modules` for PowerShell 7. ## Getting started @@ -138,10 +154,8 @@ them have changed since; use the cmdlet reference for the current names. ## Version history -See the [changelog](https://github.com/raandree/NTFSSecurity/blob/master/CHANGELOG.md) -and the -[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) -in the wiki. +See the [changelog](../CHANGELOG.md) for the changes since 4.2.6 and the +[version history](Version-History.md) for 4.2.6 and earlier. ## Contributing @@ -149,5 +163,4 @@ Contributions are welcome. See the [contributor guide](Contributing.md). ## License -NTFSSecurity is licensed under the -[MIT license](https://github.com/raandree/NTFSSecurity/blob/master/LICENSE). +NTFSSecurity is licensed under the [MIT license](../LICENSE). diff --git a/Docs/Version-History.md b/Docs/Version-History.md new file mode 100644 index 0000000..ad11586 --- /dev/null +++ b/Docs/Version-History.md @@ -0,0 +1,152 @@ +# Version history + +This page lists the changes in NTFSSecurity 4.2.6 and earlier. It replaces +the version history in the former GitHub wiki. For the changes since 4.2.6, +see the [changelog](../CHANGELOG.md). + +## 4.2.5 and 4.2.6 + +The PowerShell Gallery published 4.2.5 on 2019-07-11 and 4.2.6 on +2019-07-12. The wiki listed no changes for these versions, so this list is +reconstructed from the commit history. + +- Removed `Show-NTFSSimpleAccess`, which used Windows Forms, for + compatibility with PowerShell Core. +- Fixed parameter alias definitions that made importing the module fail, + for example in Service Management Automation + ([#18](https://github.com/raandree/NTFSSecurity/issues/18), + [#36](https://github.com/raandree/NTFSSecurity/issues/36)). +- Fixed the `ToSimpleFileSystemAccessRule2` method of the access entries + that `Get-NTFSAccess` returns + ([#48](https://github.com/raandree/NTFSSecurity/issues/48)). +- Fixed the `ApplyTo` column in the output of `Get-NTFSAccess`. +- Added the MIT license. + +## 4.2.4 + +- Bug fixes. + +## 4.2.3 + +- Added the cmdlet `Get-FileHash2`. +- Bug fixes. + +## 4.2.1 + +- Added the cmdlets `Get-NTFSHardLink`, `New-NTFSHardLink`, and + `New-NTFSSymbolicLink`. + +## 4.2 + +- Added the cmdlets `Move-Item2` and `Copy-Item2`. +- `Remove-Item2`, `Move-Item2`, and `Copy-Item2` now support `-WhatIf` and + `-Confirm`. + +## 4.1 + +- The `-Attributes` parameter of `Get-ChildItem2` works like the one of the + standard cmdlet `Get-ChildItem`, as requested. +- `Remove-NTFSAccess` can now remove access from existing access control + entries. The old behavior is still available with the `-RemoveSpecific` + switch parameter. + +## 4.0 + +- The `*-NTFSAccess` cmdlets can now work on security descriptors to allow + bulk processes. +- Code cleanup for better performance and maintainability. +- Bug fixes. + +## 3.2.3 + +- Fixed a bug in `GetInheritedFrom` that resulted in "Invalid Path" or "Path + not found" errors. + +## 3.2 + +- Bug fixes for managing auditing. +- Fixed various bugs reported on CodePlex. + +## 3.1 + +- All cmdlets have the prefix `NTFS` now. There are aliases for backward + compatibility. +- The new version of `Get-NTFSEffectivePermission` uses `AuthzAccessCheck` + instead of `GetEffectiveRightsFromAcl`. +- The previous `Get-NTFSEffectivePermission` cmdlet has been renamed to + `Get-NTFSEffectivePermissionOld`. +- Added `FileSystemAuditRule2` to the PowerShell formatters. +- Added the `InheritedFrom` information to `FileSystemAuditRule2`. + +## 3.0 + +- This version uses [AlphaFS](https://github.com/alphaleonis/AlphaFS) to + work around the `MAX_PATH` limit of 260 characters. +- New `*-Item2` cmdlets discover items with a long path: + - `Get-ChildItem2` (`dir2`) + - `Get-Item2` (`gi2`) + - `Remove-Item2` (`del2`, `rm2`) +- For inherited access control entries, `InheritedFrom` is displayed. +- Generic access rights are supported. +- Performance improvements. +- Bug fixes. + +## 2.4 + +- `Remove-Access` did not remove deny entries when using the pipeline, for + example `Import-Csv .\access.txt | Remove-Access`. +- `Add-Access` did not remove deny entries when using the pipeline, for + example `Import-Csv .\access.txt | Add-Access`. +- The parameter `-Account` was undiscoverable when using the pipeline. + +## 2.3 + +- The module now makes full use of the Backup, Restore, and Take Ownership + privileges, so as an administrator you can edit permissions on objects + that you don't have explicit access to. Privileges are enabled by default + if the value `EnablePrivileges` is `$true` in `NTFSSecurity.psd1`. The new + cmdlets `Get-Privileges`, `Disable-Privileges`, and `Enable-Privileges` + are for manual control. +- The `-Path` parameter now works consistently. + +## 2.1 + +- Fixed bugs with `Set-Owner`. +- Added support for managing auditing (SACL). + +## 2.0 (beta) + +- New commands: `Get-SimpleAccess`, `Get-SimpleEffectiveAccess`, + `Show-SimpleAccess`, `Show-SimpleEffectiveAccess`, and `Copy-Access`. +- All cmdlets are now written in C#. +- Fixed a number of bugs. + +## 1.3 + +- Fixed an issue with parameter handling. +- Now works with PowerShell 3.0. + +## 1.2 + +- Fixed some issues with path validation. +- Fixed documentation bugs. + +## 1.1 + +- Fixed the issue with square brackets in paths. +- Performance improvements. + +## 1.0 + +- The last tests didn't reveal any issue. PowerShell has a problem handling + files that have square brackets in the file name, and this module inherits + the issue. + +## 0.9 (beta) + +- Fixed some bugs. +- Updated documentation. + +## 0.8 (beta) + +- Initial release. diff --git a/Docs/requirements.txt b/Docs/requirements.txt deleted file mode 100644 index f2caded..0000000 --- a/Docs/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mkdocs==1.6.1 diff --git a/README.md b/README.md index b2c0960..42ee37f 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ Install-Module -Name NTFSSecurity ``` You can also download a release from the -[releases page](https://github.com/raandree/NTFSSecurity/releases). If you -have trouble, see -[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install). +[releases page](https://github.com/raandree/NTFSSecurity/releases) and +install it without the PowerShell Gallery; see +[Installation](Docs/README.md#installation). The module runs on Windows in Windows PowerShell 5.1 and PowerShell 7. @@ -43,7 +43,7 @@ Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited ## Documentation -- [Overview](Docs/index.md): features, requirements, and the list of cmdlets +- [Overview](Docs/README.md): features, requirements, and the list of cmdlets - [Concepts](Docs/Concepts.md): security descriptors, access rights, inheritance, privileges, long paths, and module settings - [Examples](Docs/Examples.md): common tasks @@ -59,8 +59,7 @@ although some cmdlet names have changed since: ## Version history See [CHANGELOG.md](CHANGELOG.md) for changes since version 4.2.6 and the -[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) -in the wiki for earlier releases. +[version history](Docs/Version-History.md) for 4.2.6 and earlier releases. ## License diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index c4f3155..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,57 +0,0 @@ -copyright: "The NTFSSecurity module is licensed under the MIT license." -repo_url: https://github.com/raandree/NTFSSecurity -edit_uri: edit/master/Docs/ -nav: -- Home: ./index.md -- Concepts: ./Concepts.md -- Examples: ./Examples.md -- Cmdlets: - - Add-NTFSAccess: Cmdlets/Add-NTFSAccess.md - - Add-NTFSAudit: Cmdlets/Add-NTFSAudit.md - - Clear-NTFSAccess: Cmdlets/Clear-NTFSAccess.md - - Clear-NTFSAudit: Cmdlets/Clear-NTFSAudit.md - - Copy-Item2: Cmdlets/Copy-Item2.md - - Disable-NTFSAccessInheritance: Cmdlets/Disable-NTFSAccessInheritance.md - - Disable-NTFSAuditInheritance: Cmdlets/Disable-NTFSAuditInheritance.md - - Disable-Privileges: Cmdlets/Disable-Privileges.md - - Enable-NTFSAccessInheritance: Cmdlets/Enable-NTFSAccessInheritance.md - - Enable-NTFSAuditInheritance: Cmdlets/Enable-NTFSAuditInheritance.md - - Enable-Privileges: Cmdlets/Enable-Privileges.md - - Get-ChildItem2: Cmdlets/Get-ChildItem2.md - - Get-DiskSpace: Cmdlets/Get-DiskSpace.md - - Get-FileHash2: Cmdlets/Get-FileHash2.md - - Get-Item2: Cmdlets/Get-Item2.md - - Get-NTFSAccess: Cmdlets/Get-NTFSAccess.md - - Get-NTFSAudit: Cmdlets/Get-NTFSAudit.md - - Get-NTFSEffectiveAccess: Cmdlets/Get-NTFSEffectiveAccess.md - - Get-NTFSHardLink: Cmdlets/Get-NTFSHardLink.md - - Get-NTFSInheritance: Cmdlets/Get-NTFSInheritance.md - - Get-NTFSOrphanedAccess: Cmdlets/Get-NTFSOrphanedAccess.md - - Get-NTFSOrphanedAudit: Cmdlets/Get-NTFSOrphanedAudit.md - - Get-NTFSOwner: Cmdlets/Get-NTFSOwner.md - - Get-NTFSSecurityDescriptor: Cmdlets/Get-NTFSSecurityDescriptor.md - - Get-NTFSSimpleAccess: Cmdlets/Get-NTFSSimpleAccess.md - - Get-Privileges: Cmdlets/Get-Privileges.md - - Move-Item2: Cmdlets/Move-Item2.md - - New-NTFSHardLink: Cmdlets/New-NTFSHardLink.md - - New-NTFSSymbolicLink: Cmdlets/New-NTFSSymbolicLink.md - - Remove-Item2: Cmdlets/Remove-Item2.md - - Remove-NTFSAccess: Cmdlets/Remove-NTFSAccess.md - - Remove-NTFSAudit: Cmdlets/Remove-NTFSAudit.md - - Set-NTFSInheritance: Cmdlets/Set-NTFSInheritance.md - - Set-NTFSOwner: Cmdlets/Set-NTFSOwner.md - - Set-NTFSSecurityDescriptor: Cmdlets/Set-NTFSSecurityDescriptor.md - - Test-Path2: Cmdlets/Test-Path2.md -- Contributing: - - Overview: Contributing.md - - Getting Started: Contributing/01-Getting-Started.md - - Writing: Contributing/02-Writing.md - - Style Guide: Contributing/03-Style-Guide.md - - Markdown Specifics: Contributing/04-Markdown-Specifics.md -site_name: NTFSSecurity -site_description: PowerShell module for managing NTFS permissions, auditing, inheritance, and ownership -theme: readthedocs -site_author: Raimund Andrée, James Smith -docs_dir: ./Docs -exclude_docs: | - /requirements.txt From 1d370d96db550b8b4fe6aa4ee0cc0ba9c88a19fc Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 14:14:49 +0200 Subject: [PATCH 4/4] chore(memory-bank): record the docs on GitHub and the version decisions - Decision 9: keep the documentation on GitHub; no Read the Docs site, and the wiki is retired. Decision 4 now rests on it. - Work package 3 redefined and PR-ready; work package 4 decisions: PowerShellVersion 5.1, DotNetFrameworkVersion 4.5.2, RootModule, and 5.0.0 with the PassThur alias. - Correct the Windows PowerShell 5.1 recipe (don't clear PSModulePath), and record the local build from the NuGet cache, the link-check limits, and the deleted fork behind the Read the Docs project. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .memory-bank/activeContext.md | 39 ++++++----- .../decisions/0004-online-help-on-github.md | 7 +- .memory-bank/decisions/0009-docs-on-github.md | 25 +++++++ .memory-bank/progress.md | 68 +++++++++---------- .memory-bank/projectbrief.md | 10 +-- .memory-bank/systemPatterns.md | 7 +- .memory-bank/techContext.md | 48 +++++++++---- 7 files changed, 130 insertions(+), 74 deletions(-) create mode 100644 .memory-bank/decisions/0009-docs-on-github.md diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 6ac2f8d..ed1ff73 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: current task evidence --- @@ -9,26 +9,29 @@ source: current task evidence ## Current focus -Work packages 1 (#92) and 2 (#93) are merged. Next is work package 3 (Read -the Docs), after the maintainer's go-ahead, on the local branch -`ai/read-the-docs`, which so far carries Memory Bank notes only. The -remaining packages and their details are in `progress.md`. +Work package 3 was redefined by the maintainer: no Read the Docs, the docs +stay on GitHub, and the wiki is retired (Decision 9). It is PR-ready on the +local branch `ai/docs-on-github` (`84328dc` plus Memory Bank notes). Work +package 4 (manifest and version) continues next, stacked on it, with the +maintainer's decisions recorded in `progress.md`. ## Evidence -- #92 was merged with a merge commit (`d917832`) and #93 squash-merged - (`14799fb`); the tree of `master` equals the tested `c9fbaf5`. -- AppVeyor: the PR build of #93 (54834295) and the `master` build of - `14799fb` (54834350) each passed 218 of 218 Pester tests, listed once - each on the Tests tab; the `master` build of `d917832` passed too. -- The remote branches `ai/housekeeping` and `ai/ship-help` are deleted, and - so are the local ones. The only unmerged commit, the remote-mutation note - (`9dc2022`), is now `023506c` on `ai/read-the-docs`. -- The agent can't push or open PRs (`techContext.md`, Constraints): it - prepares the commands and PR descriptions, and the maintainer runs them. +- All 256 relative links in `Docs`, `README.md`, and `CHANGELOG.md` resolve, + including 5 anchors checked against GitHub's slug rules; MarkdownLinkCheck + 0.2.0 (CI step 02) finds 0 broken links in `Docs` in Windows PowerShell + 5.1; markdownlint reports 0 issues in the changed pages. +- The documented manual install (`Unblock-File`, `Expand-Archive` into + `$env:ProgramFiles\WindowsPowerShell\Modules`) was tested with the 4.2.6 + zip in a `$env:TEMP` sandbox: the module imports under `RemoteSigned`. + `Expand-Archive` doesn't pass the download mark on; File Explorer's zip + handler does, and the import then fails. +- The wiki stopped at 4.2.4; the Gallery has 4.2.5 (2019-07-11) and 4.2.6 + (2019-07-12), whose notes were reconstructed from `4.2.4..4.2.6`. +- The local branch `ai/read-the-docs` keeps the dropped strict-build work + (`886c874`, `325ec76`); delete it once it is no longer wanted. ## Next step -Wait for the maintainer's go-ahead for work package 3. Nothing on -`ai/read-the-docs` needs pushing before then; its Memory Bank commits go -into the work package 3 PR. +Ask which assemblies follow the module version, then implement work +package 4 test-first on a branch stacked on `ai/docs-on-github`. diff --git a/.memory-bank/decisions/0004-online-help-on-github.md b/.memory-bank/decisions/0004-online-help-on-github.md index 1d4673c..d3f2ecc 100644 --- a/.memory-bank/decisions/0004-online-help-on-github.md +++ b/.memory-bank/decisions/0004-online-help-on-github.md @@ -1,7 +1,7 @@ --- status: accepted date: 2026-10-02 -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: shared source: PR #91 (moved from systemPatterns.md) --- @@ -10,5 +10,6 @@ source: PR #91 (moved from systemPatterns.md) - Choice: `online version` of every cmdlet page is `https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/.md`. -- Rationale: The Read the Docs project builds a stale fork, so its URLs show - outdated pages; GitHub always shows `master`. +- Rationale: GitHub renders the docs of `master`, and there is no other + documentation site (Decision 9). Originally chosen because the Read the + Docs project built a stale fork. diff --git a/.memory-bank/decisions/0009-docs-on-github.md b/.memory-bank/decisions/0009-docs-on-github.md new file mode 100644 index 0000000..58c2477 --- /dev/null +++ b/.memory-bank/decisions/0009-docs-on-github.md @@ -0,0 +1,25 @@ +--- +status: accepted +date: 2026-10-04 +last-verified: 2026-10-04 +owner: shared +source: maintainer decision in work package 3 +--- + +# Decision 9: Keep the documentation on GitHub + +- Choice: The documentation lives in `Docs` and `README.md`, and GitHub + renders it. There is no documentation site: the Read the Docs and MkDocs + configuration is removed. The GitHub wiki is retired: its version history + and installation steps moved to `Docs/Version-History.md` and + `Docs/README.md`, and the maintainer turns the wiki off. +- Rationale: One source of truth that is versioned with the code, reviewed + in pull requests, and checked by AppVeyor. The Read the Docs project + `ntfssecurity` belongs to `Sup3rlativ3` and points to a fork that no + longer exists; a wiki is edited outside pull requests and CI. +- Consequences: `online version` links stay on GitHub (Decision 4). Section + anchors follow GitHub's rules. `Docs/index.md` became `Docs/README.md`, so + that GitHub shows it when you open the `Docs` folder. +- Rejected: taking over or re-importing the Read the Docs project with a + strict MkDocs build (prepared on the local branch `ai/read-the-docs`, not + merged), and publishing `Docs` to the wiki. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 59e0d3b..fee48d5 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: repository evidence --- @@ -34,6 +34,10 @@ from the 4.2.6 release only by the `Remove-Item2 -PassThru` rename and upload had listed 870), six cmdlet-page links reworded for the help text. AppVeyor passed 218 of 218 on the PR (54834295) and on `master` (54834350). +- 2026-10-04: The maintainer dropped Read the Docs: the docs stay on GitHub + and the wiki is retired (Decision 9). Work package 3 committed locally on + `ai/docs-on-github` (`84328dc`). The strict Read the Docs build prepared + before stays unmerged on the local branch `ai/read-the-docs`. ## Stable capabilities @@ -52,39 +56,35 @@ next package starts only after the maintainer's go-ahead. 1. Housekeeping: done (#92). 2. Ship help: done (#93). -3. Read the Docs, next. The local branch `ai/read-the-docs` exists and so - far carries Memory Bank notes only. The project `ntfssecurity` - (`https://app.readthedocs.org/projects/ntfssecurity/`) is maintained by - GitHub user `Sup3rlativ3` and builds the fork `Sup3rlativ3/NTFSSecurity` - (last build about 2021); the repository side is ready - (`.readthedocs.yml`, `Docs/requirements.txt`). The switch happens in the - Read the Docs dashboard. Give the maintainer exact steps for both - options: (a) `Sup3rlativ3` adds him as maintainer and changes the - repository URL, or (b) he imports `raandree/NTFSSecurity` as a new - project (the slug `ntfssecurity` is taken). Ask before installing Python - for `mkdocs build --strict`. After the switch, confirm a build of - `master`, propose whether the `online version` links move to Read the - Docs (Decision 4), and add a documentation link to `README.md`. Done - when Read the Docs builds `master` of this repository and shows the - current pages. -4. Manifest and version: remove `Show-NTFSSimpleAccess` and the duplicate - inheritance entries from `CmdletsToExport` (exactly 36 cmdlets - exported). Versions disagree: manifest 4.2.5, tag and Gallery 4.2.6, - `AssemblyVersion` 4.2.1.0. Propose the next SemVer version with and - without `[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the rename in - #64 is breaking), plus `PowerShellVersion` and `DotNetFrameworkVersion` - (manifest 2.0 and 3.5; the assemblies target .NET Framework 4.5.2), and - ask. Move the `[Unreleased]` entries into the new version section (ask - whether the build-only "Read the Docs build configuration" entry stays, - Decision 7) and align `AssemblyInfo`. No tag or publish. Done when - `Test-ModuleManifest` passes, 36 cmdlets are exported, and CI is green. - Inputs: `Test-ModuleManifest` already fails on - `PowerShellVersion = '2.0'` with `CompatiblePSEditions`; releases are - Debug builds published with the whole output folder (`.pdb`, `.xml`, - `System.Management.Automation.dll`), which `FileList` doesn't list. - Before the next build and `Publish-Module`, clean - `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the removed - `NTFSSecurity-Help.xml` ships again. +3. Docs on GitHub (was: Read the Docs), PR-ready on `ai/docs-on-github`: + Read the Docs and MkDocs configuration removed, `Docs/index.md` renamed + to `Docs/README.md`, the wiki's version history and install steps moved + into `Docs` (with reconstructed notes for 4.2.5 and 4.2.6), contributor + guide updated. After the merge, the maintainer turns the wiki off, points + the notes of releases 4.2.4 and 4.2.6 to `Docs/Version-History.md`, and + may ask `Sup3rlativ3` to delete the Read the Docs project. +4. Manifest and version, in progress, stacked on `ai/docs-on-github`. + Maintainer decisions: `PowerShellVersion` 5.1, `DotNetFrameworkVersion` + 4.5.2, `RootModule` instead of `ModuleToProcess`; version 5.0.0 with + `[Alias('PassThur')]` on `Remove-Item2 -PassThru` (the changelog lists + `-PassThur` under Deprecated); the changelog entry about the + documentation site is gone (work package 3). Open: which assemblies + follow the module version. Remove `Show-NTFSSimpleAccess` and the + duplicate inheritance entries from `CmdletsToExport` (exactly 36 + cmdlets exported), move the `[Unreleased]` entries into the 5.0.0 + section, and align `AssemblyInfo`. No tag or publish. Done when + `Test-ModuleManifest` passes in Windows PowerShell 5.1 and PowerShell 7, + 36 cmdlets are exported, the versions agree, and CI is green. + Baseline: `Test-ModuleManifest` fails in both editions + (`CompatiblePSEditions` needs `PowerShellVersion` 5.1) and warns about + `ModuleToProcess`; 41 `CmdletsToExport` entries, 37 unique; versions: + manifest 4.2.5, `NTFSSecurity` 4.2.1.0, `Security2` 3.2.3.0, + `PrivilegeControl` 1.0.0.0, `ProcessPrivileges` 1.5.7.0 (vendored); + `Log` isn't shipped. Releases are Debug builds published with the whole + output folder (`.pdb`, `.xml`, `System.Management.Automation.dll`), which + `FileList` doesn't list. Before the next build and `Publish-Module`, + clean `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity`, or the + removed `NTFSSecurity-Help.xml` ships again. 5. Code defects, listed below: `review: on`, one PR per group, regression test first. Pester 5 tests import `NTFSSecurity\bin\Release`, run in a `$env:TEMP` sandbox and in `appveyor.yml` (pattern: diff --git a/.memory-bank/projectbrief.md b/.memory-bank/projectbrief.md index 98aa2d7..e349e2b 100644 --- a/.memory-bank/projectbrief.md +++ b/.memory-bank/projectbrief.md @@ -19,8 +19,9 @@ Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`. ## Scope - In scope: module source (`NTFSSecurity`, `Security2`, `PrivilegeControl`, - `ProcessPrivileges`), module manifest and type/format data, the MkDocs - documentation site in `Docs/`, and `README.md`. + `ProcessPrivileges`), module manifest and type/format data, the + documentation in `Docs/` (rendered by GitHub, Decision 9), and + `README.md`. - Out of scope: registry security. `Security2/Registry/RegistrySecurity.cs` exists, but no registry cmdlet is exported. - Distribution: PowerShell Gallery package `NTFSSecurity` and GitHub releases. @@ -28,8 +29,9 @@ Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`. ## Stakeholders - Maintainer and author: Raimund Andree (`raandree`), per the manifest. -- Documentation contributors: James Smith (`mkdocs.yml` `site_author`); - the AppVeyor documentation build runs under the `Sup3rlativ3` account. +- Documentation contributors: James Smith (`site_author` in the former + `mkdocs.yml`) and `Sup3rlativ3` (#62), who owns the Read the Docs project + `ntfssecurity` and a second AppVeyor project. - End users: To confirm beyond the README summary. ## Acceptance criteria diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index e377dbd..a8bd76d 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: repository evidence --- @@ -55,6 +55,7 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. | 6 | [CI checks the docs against a build of the source](decisions/0006-ci-checks-docs-against-build.md) | | 7 | [CHANGELOG lists user-visible changes only](decisions/0007-changelog-user-visible-only.md) | | 8 | [Commit the generated help file and check it in CI](decisions/0008-commit-generated-help.md) | +| 9 | [Keep the documentation on GitHub](decisions/0009-docs-on-github.md) | ## Patterns @@ -62,6 +63,10 @@ Each Decision record is a file in `decisions/`; read only the relevant ones. - Run platyPS in Windows PowerShell 5.1 against a module build; a copy of `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged. +- GitHub renders the docs (Decision 9). AppVeyor's link check covers only + relative links in `Docs` and ignores anchors, so check anchors against + GitHub's slug rules (lowercase, punctuation removed, spaces to hyphens) + and the links in `README.md` and `CHANGELOG.md` separately. - platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages ASCII-only. - In cmdlet pages, end a sentence with a link: platyPS renders a link as diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index cb82cac..53b981c 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -1,6 +1,6 @@ --- status: current -last-verified: 2026-10-02 +last-verified: 2026-10-04 owner: active-agent source: repository evidence --- @@ -19,8 +19,8 @@ source: repository evidence - Module: `NTFSSecurity.psd1` loads `NTFSSecurity.psm1` (aliases `dir2`, `gi2`, `rm2`, `del2`), `NTFSSecurity.Init.ps1` (Add-Type of the helper assemblies, prepends `NTFSSecurity.format.ps1xml`), and `NTFSSecurity.dll`. -- Documentation: MkDocs (`mkdocs.yml`, theme `readthedocs`, `docs_dir: ./Docs`) - built by Read the Docs (`.readthedocs.yml` v2); cmdlet pages are platyPS +- Documentation: Markdown in `Docs` and `README.md`, rendered by GitHub; no + documentation site and no wiki (Decision 9). Cmdlet pages are platyPS 0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`. - Help: `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml`, generated from `Docs/Cmdlets` and committed (Decision 8). @@ -39,11 +39,25 @@ source: repository evidence package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild` fails on the binary resources in `Resources.resx` (MSB3822, MSB3823). - platyPS 0.14.2, Pester 5.7.1, PSScriptAnalyzer, and powershell-yaml are - installed only for PowerShell 7. Windows PowerShell 5.1 imports platyPS - and Pester by full path + installed only for PowerShell 7. Windows PowerShell 5.1, started from + PowerShell 7, imports platyPS and Pester by full path (`~\OneDrive\Documents\PowerShell\Modules\platyPS\0.14.2`, - `C:\Program Files\PowerShell\Modules\Pester\5.7.1`) with - `$env:PSModulePath` cleared. MarkdownLinkCheck is not installed. + `C:\Program Files\PowerShell\Modules\Pester\5.7.1`). Leave + `$env:PSModulePath` alone: PowerShell 7 hands the child the Windows + PowerShell default path, and clearing it leaves Windows PowerShell without + its core modules (Pester fails: `Add-Member` not found). +- MarkdownLinkCheck is not installed, and `Save-Module` crashed (FailFast) + in PowerShell 7.6 on 2026-10-04. Download the 0.2.0 package from + `https://www.powershellgallery.com/api/v2/package/MarkdownLinkCheck/0.2.0` + into `$env:TEMP`, extract it, and import it by path. +- The workstation is ARM64; PowerShell 7 runs as x64 under emulation. + Python 3.12.10 (ARM64) is installed per user with winget, the + maintainer's choice for an MkDocs check that Decision 9 made unnecessary. +- The NuGet cache (`~\.nuget\packages`) holds every build dependency: copy + `alphafs\2.2.1`, `system.management.automation.dll\10.0.10586`, and + `microsoft.netframework.referenceassemblies.net452\1.0.3` into + `packages\.`, and point `CscToolPath` at + `microsoft.net.compilers\4.2.0\tools`. ## Constraints @@ -64,8 +78,11 @@ source: repository evidence published manifest differs from the tag only by `ModuleVersion` (tags carry the previous version). GitHub releases attach `NTFSSecurity.zip`. - CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull - requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are - attached to the fork `Sup3rlativ3/NTFSSecurity`. + requests. The Read the Docs project `ntfssecurity` (maintainer + `Sup3rlativ3`) and a second AppVeyor project are attached to the fork + `Sup3rlativ3/NTFSSecurity`, which no longer exists (GitHub 404, + 2026-10-04). That site still serves pages from 2020 and isn't used + (Decision 9). - `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke test in PowerShell 7.6. - `CHANGELOG.md` lists user-visible changes only; CI and build-only changes @@ -103,10 +120,13 @@ source: repository evidence - Help file: `New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force` must leave `git status` unchanged. - Pester: run detached (`Start-DetachedPowerShell.ps1`) in Windows - PowerShell 5.1; a run without `bin\Release\en-US` must fail. + PowerShell 5.1: the launcher starts `pwsh`, and its payload runs + `powershell.exe -NoProfile -EncodedCommand` with Pester imported by full + path. A run without `bin\Release\en-US` must fail. - Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose (tables, code, and headings excluded) on the conceptual pages. -- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`, - `.readthedocs.yml`, and `appveyor.yml`; every `nav` target must exist. -- MkDocs needs Python, which this workstation does not have; `mkdocs build - --strict` was not run. +- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `appveyor.yml`. +- Links: AppVeyor step 02 (MarkdownLinkCheck 0.2.0) checks only relative + links in `Docs`; it strips anchors and skips absolute URLs. Check anchors + against GitHub's heading slugs, and the links in `README.md` and + `CHANGELOG.md`, with a script.