diff --git a/.gitignore b/.gitignore index 3a2238d..261a1bd 100644 --- a/.gitignore +++ b/.gitignore @@ -242,4 +242,7 @@ ModelManifest.xml .paket/paket.exe # FAKE - F# Make -.fake/ \ No newline at end of file +.fake/ + +# Memory Bank: local prompt history, not version-controlled +/.memory-bank/promptHistory.md diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 0cef07c..5aa1f75 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -9,22 +9,23 @@ source: current task evidence ## Current focus -PR #91 (`ai/docs-alignment`): CI fixed by building the module from source -in `appveyor.yml` and checking the docs against that build. +Work package 1 (housekeeping) on branch `ai/housekeeping`; the five work +packages and their order are in `progress.md`. ## Evidence -- AppVeyor build 54825990 failed in step 01: `Update-MarkdownHelp` against - the Gallery module 4.2.6 rewrote `Remove-Item2 -PassThru` to `-PassThur`. -- Against a Release build of the source, `Update-MarkdownHelp` changes none - of the 36 pages; a simulation of all `appveyor.yml` steps in a fresh clone - passed, and a page with stale syntax made it fail as intended. -- The link check (`Get-MarkdownLink -BrokenOnly`) finds 308 links, none - broken. +- PR #91 is merged into `master` as `690d8dd` (squash merge). The local + branch `ai/docs-alignment` had the same tree as `690d8dd` and is deleted; + GitHub had already deleted the remote branch. +- `.memory-bank/promptHistory.md` is ignored by git (`.gitignore`) and stays + a local file. +- The changelog policy is Decision 7. The inline Decisions moved to + `decisions/` records because `systemPatterns.md` was near its 110-line + budget. - Read the Docs project `ntfssecurity` still builds the fork `Sup3rlativ3/NTFSSecurity`. ## Next step -PR #91 is green (AppVeyor 54828078 branch and 54828080 pull request, both -on `dbd8d16`). Await review and merge; open follow-ups are in `progress.md`. +The maintainer pushes `ai/housekeeping` and opens the PR. After the +go-ahead, start work package 2 (ship the generated help). diff --git a/.memory-bank/decisions/0001-canonical-memory-bank.md b/.memory-bank/decisions/0001-canonical-memory-bank.md new file mode 100644 index 0000000..3cd354e --- /dev/null +++ b/.memory-bank/decisions/0001-canonical-memory-bank.md @@ -0,0 +1,12 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: PR #91 (moved from systemPatterns.md) +--- + +# Decision 1: Use the canonical Memory Bank base + +- Choice: Keep durable project context in .memory-bank. +- Rationale: Preserve evidence-backed context across sessions. diff --git a/.memory-bank/decisions/0002-platyps-cmdlet-reference.md b/.memory-bank/decisions/0002-platyps-cmdlet-reference.md new file mode 100644 index 0000000..47d9d4e --- /dev/null +++ b/.memory-bank/decisions/0002-platyps-cmdlet-reference.md @@ -0,0 +1,15 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: PR #91 (moved from systemPatterns.md) +--- + +# Decision 2: Cmdlet reference stays platyPS markdown + +- Choice: `Docs/Cmdlets/*.md` keep the platyPS 0.14 schema 2.0.0 layout + (upper-case section headings, YAML parameter blocks, one paragraph per + line) so `Update-MarkdownHelp` and `New-ExternalHelp` round-trip. +- Rationale: `appveyor.yml` checks the pages with `Update-MarkdownHelp`; + the same files can generate MAML help. diff --git a/.memory-bank/decisions/0003-document-source-at-head.md b/.memory-bank/decisions/0003-document-source-at-head.md new file mode 100644 index 0000000..1a07e51 --- /dev/null +++ b/.memory-bank/decisions/0003-document-source-at-head.md @@ -0,0 +1,14 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: PR #91 (moved from systemPatterns.md) +--- + +# Decision 3: Document the source at HEAD + +- Choice: Docs describe the code on `master`. Where HEAD differs from the + latest Gallery release, the page says which version changed. +- Rationale: The user asked to align docs with the actual code; the only + current difference is `Remove-Item2 -PassThru` (4.2.6 spells `-PassThur`). diff --git a/.memory-bank/decisions/0004-online-help-on-github.md b/.memory-bank/decisions/0004-online-help-on-github.md new file mode 100644 index 0000000..1d4673c --- /dev/null +++ b/.memory-bank/decisions/0004-online-help-on-github.md @@ -0,0 +1,14 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: PR #91 (moved from systemPatterns.md) +--- + +# Decision 4: Online help points to GitHub + +- 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`. diff --git a/.memory-bank/decisions/0005-document-defects-separately.md b/.memory-bank/decisions/0005-document-defects-separately.md new file mode 100644 index 0000000..a04fc86 --- /dev/null +++ b/.memory-bank/decisions/0005-document-defects-separately.md @@ -0,0 +1,15 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: PR #91 (moved from systemPatterns.md) +--- + +# Decision 5: Document defects, don't fix them in docs work + +- Choice: Code defects found while documenting are described on the affected + page (workaround or limitation) and listed in `progress.md`; source code is + changed only in separate, tested work. +- Rationale: No build toolchain was available to verify code changes, and + the docs must describe current behavior. diff --git a/.memory-bank/decisions/0006-ci-checks-docs-against-build.md b/.memory-bank/decisions/0006-ci-checks-docs-against-build.md new file mode 100644 index 0000000..3451b82 --- /dev/null +++ b/.memory-bank/decisions/0006-ci-checks-docs-against-build.md @@ -0,0 +1,16 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: PR #91 (moved from systemPatterns.md) +--- + +# Decision 6: CI checks the docs against a build of the source + +- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs + `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the + module from the PowerShell Gallery. +- Rationale: Checking against the last release fails for every unreleased + parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never + compiled the code. diff --git a/.memory-bank/decisions/0007-changelog-user-visible-only.md b/.memory-bank/decisions/0007-changelog-user-visible-only.md new file mode 100644 index 0000000..1bd4710 --- /dev/null +++ b/.memory-bank/decisions/0007-changelog-user-visible-only.md @@ -0,0 +1,17 @@ +--- +status: accepted +date: 2026-10-02 +last-verified: 2026-10-02 +owner: shared +source: maintainer decision after PR #91 +--- + +# Decision 7: CHANGELOG lists user-visible changes only + +- Choice: `CHANGELOG.md` lists only changes that module users or + documentation readers can notice. CI and build-only changes, such as + `appveyor.yml` or local build tooling, get no entry. +- Rationale: Agreed with the maintainer. It follows Keep a Changelog: the + file tells users what changed, and git history covers CI and build work. +- Example: PR #91 lists the documentation rewrite but not the switch of + `appveyor.yml` to building the module from source. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 449bbfa..4cf9146 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -9,9 +9,9 @@ source: repository evidence ## Current status -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`. +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`. ## Recent milestones @@ -24,6 +24,16 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and - 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 closes it by hand. ## Stable capabilities @@ -35,19 +45,104 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and ## Open work -- Ship help: add the generated `en-US\NTFSSecurity.dll-Help.xml` to the - build and drop the stale `NTFSSecurity-Help.xml`. -- Publishing: re-point Read the Docs from the fork `Sup3rlativ3/NTFSSecurity` - to this repository (or create a new Read the Docs project). -- Manifest: remove `Show-NTFSSimpleAccess` and duplicates from - `CmdletsToExport`; bump `ModuleVersion` (4.2.5 in source, 4.2.6 released). -- Code defects found while documenting (each documented on its page): - `Add-NTFSAudit` duplicate position 2; SD parameter sets of - `Add/Remove-NTFSAccess/Audit` need `-AppliesTo`; `Set-NTFSInheritance` - nullable crash and hard-coded removal; inheritance cmdlets ignore - `EnablePrivileges = $false`; `Get-NTFSEffectiveAccess` - `-ExcludeNoneAccessEntries` and SD set ineffective; `-Account`/SD ignored by - `Get-NTFSOrphanedAccess/Audit` and `Get-NTFSSimpleAccess`; `Copy-Item2` - fails on folders with files; `Get-ChildItem2` throws on a file path; - `return` instead of `continue` in several `ProcessRecord` loops; wrong - `OutputType` on several cmdlets; `Get-FileHash2` in PowerShell 7. +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: committed on `ai/housekeeping`; awaiting push and PR. +2. Ship help: generate `en-US\NTFSSecurity.dll-Help.xml` from `Docs/Cmdlets` + with `New-ExternalHelp` and ship it (csproj `Content`, manifest + `FileList`); remove the stale `NTFSSecurity-Help.xml` and, if unused, + `NTFSSecurity\Help\NTFSSecurity.Help.pshproj`. Ask the maintainer: + commit the file plus a CI currency check, or generate it in the build. +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`. +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. +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`. + +### Code defects (work package 5) + +Numbered as agreed with the maintainer; each is documented on its page. + +#### A: Crashes and wrong results + +- (1) `Set-NTFSInheritance` reads an unset `Nullable` when + `-AccessInheritanceEnabled` is omitted; omitted should mean unchanged. +- (2) `Get-ChildItem2` casts a file `-Path` to `DirectoryInfo` + (`InvalidCastException`). +- (3) `Get-FileHash2` returns at a folder in `-Path` and skips the rest. +- (4) `Get-NTFSAudit` re-emits the previous item's entries after a failed + path, and returns nothing without the Security privilege instead of an + error. +- (5) `Add-NTFSAudit`: `-Account` and `-AccessRights` share position 2; + use 2 and 3 like `Remove-NTFSAudit`. +- (6) `-PassThru` returns access entries in `Add-NTFSAudit` SD sets and + `Remove-NTFSAudit` Path sets. +- (7) `FileSystemAuditRule2.GetFileSystemAuditRules` takes + `InheritanceEnabled` from `AreAccessRulesProtected`. +- (8) `Get-NTFSInheritance -SecurityDescriptor` reports + `AuditInheritanceEnabled = $true` without a SACL (Path set: `$null`). +- (9) `Get-NTFSOwner`: the access-denied retry repeats the failing call, + and the catch-all turns `PipelineStoppedException` into + `ReadSecurityError`. +- (10) `Copy-Item2` fails on a folder with files + (`DirectoryNotFoundException`). +- (11) `Disable-Privileges` hits a null `privileges` field when + `EnablePrivileges = $false`. +- (12) The six inheritance cmdlets enable privileges unconditionally in + `BeginProcessing` and leave them enabled. +- (13) Format view `Children2`: the `Inherits` column uses + `IsInheritanceBlocked`, so it always shows `True` for `Get-ChildItem2`. + +#### B: Ignored parameters and parameter sets + +- (14) SD sets of `Add-/Remove-NTFSAccess` and `Add-/Remove-NTFSAudit` + cannot resolve without `-AppliesTo` or the flag parameters. +- (15) `Get-NTFSEffectiveAccess`: `-ExcludeNoneAccessEntries` has no + effect, there is no output without `-Path`, and the SD set returns + nothing. +- (16) `Get-NTFSOrphanedAccess`, `Get-NTFSOrphanedAudit`, and + `Get-NTFSSimpleAccess` ignore `-Account` and `-SecurityDescriptor`; + `Get-NTFSOrphanedAudit` writes collections; `SimpleFileSystemAccessRule` + has no format view. +- (17) `removeSpecific` in `Remove-NTFSAccess/Audit` is never bound; + `Remove-NTFSAudit` leaves `appliesTo` uninitialized. + +#### C: Error handling + +- (18) `Copy-Item2`, `Move-Item2`, `Remove-Item2`: one failing path skips + the rest of `-Path` (`return` instead of `continue`). +- (19) `Remove-NTFSAccess` continues after a failed read and writes a + second, misleading `RemoveAceError`. +- (20) The inheritance cmdlets write `-PassThru` output in `finally`, even + after a failure. +- (21) `New-NTFSHardLink` says the target path exists when it doesn't. + +#### D: Metadata and cosmetics + +- (22) Wrong or missing `[OutputType]` (`Test-Path2`, `Get-FileHash2`, + `Add-NTFSAudit`, `*-Item2`, inheritance cmdlets); + `Enable-/Disable-Privileges -PassThru` writes one collection; + `New-NTFSSymbolicLink -PassThru` returns `FileInfo` for folder links. +- (23) Typos: "Privliege" in the `Get-NTFSEffectiveAccess` warning; "are + now enabled" in the `Disable-Privileges` verbose message. +- (24) Dead code in `RemoveItem2.cs` and `OtherCmdlets.cs`. + +#### E: Maintainer decisions before changing behavior + +- `Clear-NTFSAccess -DisableInheritance` discards inherited entries: keep + that, or copy them? +- `Set-NTFSInheritance` defaults are the opposite of the dedicated + inheritance cmdlets: align? +- The audit inheritance switches are named `*AccessRules`: add + `*AuditRules` aliases? +- `Get-FileHash2` fails in PowerShell 7 (`RIPEMD160`): drop the algorithm + there, load it lazily, or deprecate the cmdlet? diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index 19319cc..eb0e35c 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -41,51 +41,21 @@ NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2, ## Decisions -### Decision 1: Use the canonical Memory Bank base +Each Decision record is a file in `decisions/`; read only the relevant ones. -- Choice: Keep durable project context in .memory-bank. -- Rationale: Preserve evidence-backed context across sessions. +| # | Decision | +| --- | --- | +| 1 | [Use the canonical Memory Bank base](decisions/0001-canonical-memory-bank.md) | +| 2 | [Cmdlet reference stays platyPS markdown](decisions/0002-platyps-cmdlet-reference.md) | +| 3 | [Document the source at HEAD](decisions/0003-document-source-at-head.md) | +| 4 | [Online help points to GitHub](decisions/0004-online-help-on-github.md) | +| 5 | [Document defects, don't fix them in docs work](decisions/0005-document-defects-separately.md) | +| 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) | -### Decision 2: Cmdlet reference stays platyPS markdown +## Patterns -- Choice: `Docs/Cmdlets/*.md` keep the platyPS 0.14 schema 2.0.0 layout - (upper-case section headings, YAML parameter blocks, one paragraph per - line) so `Update-MarkdownHelp` and `New-ExternalHelp` round-trip. -- Rationale: `appveyor.yml` checks the pages with `Update-MarkdownHelp`; - the same files can generate MAML help. - -### Decision 3: Document the source at HEAD - -- Choice: Docs describe the code on `master`. Where HEAD differs from the - latest Gallery release, the page says which version changed. -- Rationale: The user asked to align docs with the actual code; the only - current difference is `Remove-Item2 -PassThru` (4.2.6 spells `-PassThur`). - -### Decision 4: Online help points to GitHub - -- 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`. - -### Decision 5: Document defects, don't fix them in docs work - -- Choice: Code defects found while documenting are described on the affected - page (workaround or limitation) and listed in `progress.md`; source code is - changed only in separate, tested work. -- Rationale: No build toolchain was available to verify code changes, and - the docs must describe current behavior. - -### Decision 6: CI checks the docs against a build of the source - -- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs - `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the - module from the PowerShell Gallery. -- Rationale: Checking against the last release fails for every unreleased - parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never - compiled the code. - -### Pattern: verifying documentation +### Verifying documentation - Run platyPS in Windows PowerShell 5.1 against a module build; a copy of `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged. diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index 290a78f..c426e25 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -50,6 +50,9 @@ source: repository evidence attached to the fork `Sup3rlativ3/NTFSSecurity`. - `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 + get no entry + ([Decision 7](decisions/0007-changelog-user-visible-only.md)). ## Validation