diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md new file mode 100644 index 0000000..67a592e --- /dev/null +++ b/.memory-bank/activeContext.md @@ -0,0 +1,30 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: current task evidence +--- + +# Active context + +## Current focus + +Documentation aligned with the cmdlets at HEAD (branch `ai/docs-alignment`). +Next candidates: ship generated MAML help, re-point the docs build, and fix +the code defects the documentation work surfaced. + +## Evidence + +- All 36 cmdlet pages filled from the C# source; 142 examples; no `{{` + placeholders; examples checked against live parameter metadata. +- `Update-MarkdownHelp` against release 4.2.6 leaves 35 of 36 pages + byte-identical; `Remove-Item2` differs only by `-PassThru` (HEAD) versus + `-PassThur` (4.2.6). +- `New-ExternalHelp` builds `NTFSSecurity.dll-Help.xml` (36 commands); + `Get-Help` renders it when placed in `en-US` of a module copy. +- Read the Docs project `ntfssecurity` and the AppVeyor project build the + fork `Sup3rlativ3/NTFSSecurity`; the last RTD build is about 5.75 years old. + +## Next step + +Await the next task. Open follow-ups are listed in `progress.md`. diff --git a/.memory-bank/index.md b/.memory-bank/index.md new file mode 100644 index 0000000..8b8ddb1 --- /dev/null +++ b/.memory-bank/index.md @@ -0,0 +1,46 @@ +--- +schema-version: 1 +loading-mode: routed +status: accepted +owner: shared +last-verified: 2026-10-02 +source: repository evidence +--- + +# Memory Bank index + +Read this file first. It routes tasks to the smallest relevant set of Memory +Bank files. + +## Full-read fallback + +Set `loading-mode` to `full` to restore complete-base loading. Also fail open +when this index is missing or invalid, the task is ambiguous, routes conflict, +a listed file is missing, or a critical fact cannot be found. Full mode also +reads every existing `decisions/*.md` record. + +## Routing table + +Combine routes when a task spans topics. For durable repository writes, also +read `activeContext.md` before editing. + +| Route | Task signals | Read | +|---|---|---| +| `general` | General Q&A with no project decision | Index only | +| `continuation` | Resume, current focus, next step | `activeContext.md`, `progress.md` | +| `scope` | Purpose, scope, requirements, Acceptance criteria | `projectbrief.md` | +| `product` | Users, problem, workflow, experience goal | `productContext.md` | +| `implementation` | Code, configuration, build, test, dependency, deployment | `techContext.md`, `activeContext.md` | +| `architecture` | Design, pattern, decision, migration, integration | `systemPatterns.md`, relevant `decisions/*.md` | +| `status` | Progress, recent change, open work | `progress.md`, `activeContext.md` | +| `language` | Canonical terms in authored artifacts | `glossary.md` | +| `interaction-history` | Session analysis, prompt trends, Memory Bank evals | `promptHistory.md`, `progress.md` | +| `role` | Active Custom agent domain workflow | Only that agent's declared role files | + +## Authority order + +1. The user's current request controls task constraints. +2. Repository source, configuration, tests, and evidence control facts. +3. Accepted decision records control durable architectural choices. +4. Core Memory Bank files control only their assigned topic. +5. Historical logs never override current source. diff --git a/.memory-bank/productContext.md b/.memory-bank/productContext.md new file mode 100644 index 0000000..b350f72 --- /dev/null +++ b/.memory-bank/productContext.md @@ -0,0 +1,42 @@ +--- +status: current +last-verified: 2026-10-02 +owner: shared +source: repository evidence +--- + +# Product context + +## Problem + +PowerShell ships only `Get-Acl` and `Set-Acl`; everything between reading +and writing an ACL (permission reports, adding or removing one entry, +inheritance, ownership, orphaned SIDs) needs custom .NET code. The module +provides task-level cmdlets for these jobs (`README.md` summary). + +## Users + +- People who manage NTFS file and folder permissions with PowerShell + (README summary). Specific personas: To confirm. + +## Core workflows + +1. Report permissions: `Get-NTFSAccess`, `Get-NTFSSimpleAccess`, + `Get-NTFSEffectiveAccess`. +2. Change permissions: `Add-NTFSAccess`, `Remove-NTFSAccess`, + `Clear-NTFSAccess`; the audit equivalents manage the SACL. +3. Back up and restore explicit permissions through CSV + (`Get-NTFSAccess | Export-Csv`, `Import-Csv | Add-NTFSAccess`). +4. Find and remove orphaned entries: `Get-NTFSOrphanedAccess`. +5. Repair inheritance and ownership: `*-NTFSAccessInheritance`, + `Set-NTFSInheritance`, `Set-NTFSOwner`, using backup/restore privileges. +6. Work with paths longer than 260 characters: `Get-ChildItem2` and the other + `*-Item2` cmdlets. + +## Experience goals + +- Pipeline first: item cmdlets emit objects whose `FullName` binds to `-Path`. +- Accept account names and SIDs; output shows both when resolvable. +- Output formatted like `Get-ChildItem` (`NTFSSecurity.format.ps1xml`). +- Work on files the caller cannot normally open by enabling the Backup, + Restore, TakeOwnership, and Security privileges automatically. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md new file mode 100644 index 0000000..5bbb0c4 --- /dev/null +++ b/.memory-bank/progress.md @@ -0,0 +1,51 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: repository evidence +--- + +# Progress + +## 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`. + +## 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. + +## Stable capabilities + +- 36 cmdlets: access (7), audit (5), inheritance (6), owner and security + descriptor (4), privileges (3), long-path items (6), links, hash, and + disk space (5). +- Works in Windows PowerShell 5.1 and PowerShell 7 (smoke-tested), except + `Get-FileHash2`, which fails in PowerShell 7 (missing `RIPEMD160` type). + +## 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 and AppVeyor from the fork + `Sup3rlativ3/NTFSSecurity`; `appveyor.yml` checks docs against the Gallery + module instead of the source. +- 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. diff --git a/.memory-bank/projectbrief.md b/.memory-bank/projectbrief.md new file mode 100644 index 0000000..98aa2d7 --- /dev/null +++ b/.memory-bank/projectbrief.md @@ -0,0 +1,42 @@ +--- +status: current +last-verified: 2026-10-02 +owner: shared +source: repository evidence +--- + +# Project brief + +## Purpose + +NTFSSecurity is a binary (C#) PowerShell module that fills the gap between +`Get-Acl` and `Set-Acl`: cmdlets to read, add, remove, and clear NTFS +permissions (DACL) and audit rules (SACL), manage inheritance and ownership, +copy security descriptors, control process privileges, and work with long +paths (`*-Item2` cmdlets via AlphaFS), hard links, and symbolic links. +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`. +- Out of scope: registry security. `Security2/Registry/RegistrySecurity.cs` + exists, but no registry cmdlet is exported. +- Distribution: PowerShell Gallery package `NTFSSecurity` and GitHub releases. + +## 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. +- End users: To confirm beyond the README summary. + +## Acceptance criteria + +1. Every exported cmdlet has an accurate platyPS page in `Docs/Cmdlets`. +2. `Update-MarkdownHelp` against the module produces no parameter drift + (the check in `appveyor.yml`). +3. The module imports in Windows PowerShell 5.1 and PowerShell 7 + (`CompatiblePSEditions = 'Core', 'Desktop'`). +4. Further release criteria: To confirm. diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md new file mode 100644 index 0000000..1fa620b --- /dev/null +++ b/.memory-bank/systemPatterns.md @@ -0,0 +1,86 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: repository evidence +--- + +# System patterns + +## Architecture + +```text +NTFSSecurity.psd1 ─┬─ ScriptsToProcess: NTFSSecurity.Init.ps1 + │ Add-Type: Security2.dll, PrivilegeControl.dll, + │ ProcessPrivileges.dll, inline NTFS.DriveInfoExt; + │ Update-FormatData -PrependPath format.ps1xml + ├─ TypesToProcess: NTFSSecurity.types.ps1xml + │ (Owner, IsInheritanceBlocked, LengthOnDisk on + │ FileInfo/DirectoryInfo; AccountType on ACEs) + ├─ ModuleToProcess: NTFSSecurity.psm1 (aliases) + └─ NestedModules: NTFSSecurity.dll (36 cmdlets) +NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2, + FileSystemAuditRule2, IdentityReference2, + FileSystemInheritanceInfo, EffectiveAccess) + ── long paths ──> AlphaFS + ── privileges ──> PrivilegeControl / ProcessPrivileges +``` + +- `BaseCmdlet` resolves relative paths against `$PWD`. +- `BaseCmdletWithPrivControl` (access, audit, inheritance, owner, security + descriptor, and privilege cmdlets) enables Backup, Restore, TakeOwnership, + and Security in `BeginProcessing` when `PrivateData.EnablePrivileges` is + `$true`, and disables the ones it enabled in `EndProcessing`. +- `PrivateData` switches: `EnablePrivileges` (base cmdlet), + `GetInheritedFrom` (`Get-NTFSAccess`, `Get-NTFSAudit`), + `GetFileSystemModeProperty` and `IdentifyHardLinks` (`Get-ChildItem2`), + `ShowAccountSid` (format file). +- Cmdlets accept either `-Path` (alias `FullName`) or `-SecurityDescriptor` + (from `Get-NTFSSecurityDescriptor`); SD sets change the in-memory object + until `Set-NTFSSecurityDescriptor` writes it back. + +## Decisions + +### Decision 1: Use the canonical Memory Bank base + +- Choice: Keep durable project context in .memory-bank. +- Rationale: Preserve evidence-backed context across sessions. + +### 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. + +### 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. + +### Pattern: 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. +- platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages + ASCII-only. +- Verify examples in a `$env:TEMP` sandbox, never on real data; parse every + example and check its parameters against `Get-Command` metadata. diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md new file mode 100644 index 0000000..001235d --- /dev/null +++ b/.memory-bank/techContext.md @@ -0,0 +1,62 @@ +--- +status: current +last-verified: 2026-10-02 +owner: active-agent +source: repository evidence +--- + +# Tech context + +## Stack + +- C# class libraries, old-style `.csproj`, .NET Framework 4.5.2, + solution `NTFSSecurity.sln` (Visual Studio 2017 format). +- Projects: `NTFSSecurity` (cmdlets), `Security2` (ACL object model, Win32 + interop), `PrivilegeControl` and `ProcessPrivileges` (token privileges), + `Log`, `TestClient`, `NTFSSecurityTest` (MSTest, minimal coverage). +- NuGet (`packages.config`): AlphaFS 2.2.x for long paths; + `System.Management.Automation.dll` 10.0.10586.0. +- 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 + 0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`. + +## Environment + +- Windows only (NTFS, Win32 security APIs). +- The Debug build writes straight into + `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity\`. +- No MSBuild or .NET Framework targeting pack on the 2026-10-02 workstation; + the released module 4.2.6 and platyPS 0.14.2 were installed. + +## Constraints + +- `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. +- `CmdletsToExport` lists `Show-NTFSSimpleAccess`, which no longer exists + (WinForms code removed in `d3063de`), and repeats the inheritance cmdlets. +- `NTFSSecurity/NTFSSecurity-Help.xml` is a stale pre-4.x MAML file for old + command names; binary-module help must be named `NTFSSecurity.dll-Help.xml`. +- Read the Docs (`ntfssecurity`) and AppVeyor are attached to the fork + `Sup3rlativ3/NTFSSecurity`, not to this repository. +- `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke + test in PowerShell 7.6. + +## Validation + +- Docs drift check (mirrors `appveyor.yml`), run in Windows PowerShell 5.1 + to avoid PowerShell 7.4+ `-ProgressAction` noise: copy `Docs/Cmdlets`, run + `Update-MarkdownHelp` on the copy against the module, and diff. +- Placeholder check: no `{{` left in `Docs/Cmdlets/*.md`. +- Help build check: `New-ExternalHelp -Path ./Docs/Cmdlets` to a temp folder. +- 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` and + `.readthedocs.yml`; every `nav` target must exist. +- Link check in CI: `Get-MarkdownLink -Path .\Docs\ -BrokenOnly`. +- MkDocs needs Python, which this workstation does not have; `mkdocs build + --strict` was not run.