You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit eb92f8c
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: AGENTS.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,6 +26,7 @@ This file defines how AI agents work in this solution.
26
26
-`Integraions/ManagedCode.Storage.Server/`
27
27
-`Storages/ManagedCode.Storage.Aws/`
28
28
-`Storages/ManagedCode.Storage.Browser/`
29
+
-`Storages/ManagedCode.Storage.Cartograph/`
29
30
-`Storages/ManagedCode.Storage.Azure/`
30
31
-`Storages/ManagedCode.Storage.Azure.DataLake/`
31
32
-`Storages/ManagedCode.Storage.CloudKit/`
@@ -47,6 +48,13 @@ This file defines how AI agents work in this solution.
47
48
4. Local `AGENTS.md` files may refine or tighten root rules, but they must not silently weaken them.
48
49
5. If a local rule needs an exception, document it explicitly in the nearest local `AGENTS.md`, ADR, or feature doc.
49
50
51
+
## ManagedCode Dependency Ownership And Repair
52
+
53
+
-`ManagedCode.*` projects and packages are maintained by us. Locate a defective dependency's owning repository alongside this checkout, read its `AGENTS.md`, and repair it there instead of replacing it, copying its implementation, or hiding the defect in a consumer workaround.
54
+
- Deliver dependency repairs with focused regression tests, required repository checks, a canonical patch-version increment, a scoped commit, and a push to GitHub. These scoped version, commit, push, and release-trigger actions have standing user authorization; preserve unrelated work and never force-push or bypass protections.
55
+
- Follow the owning repository's GitHub release workflow to success and verify the new version on the intended NuGet feed before updating a consumer reference and running consumer regressions. Diagnose publication failures in the owning repository; a pushed commit or green build alone is not delivery.
56
+
- Do not claim delivery with unpublished local packages or temporary project references. Report the exact source, credentials, permissions, or release-infrastructure blocker when delivery cannot proceed.
57
+
50
58
## Conversations (Self-Learning)
51
59
52
60
Learn the user's stable habits, preferences, and corrections. Record durable rules here instead of relying on chat history.
@@ -291,6 +299,8 @@ Toolchain notes:
291
299
292
300
### Git And PRs
293
301
302
+
- Never run `git stash` or enable automatic stashing; keep working-tree changes visible so concurrent work stays reviewable.
303
+
- When the user requests committing all current changes, commit the full requested working-tree scope on the currently checked-out branch; do not silently omit existing changes or move them to another branch.
294
304
- Write commit subjects in the imperative mood such as `add ftp retry policy` and keep them provider-scoped.
295
305
- Group related edits in one commit and avoid WIP spam.
296
306
- PRs should summarize impact, list touched projects, reference issues, and note new configuration or secrets.
@@ -131,13 +132,46 @@ Cloud storage vendors expose distinct SDKs, option models, and authentication pa
131
132
|[ManagedCode.Storage.Aws](https://www.nuget.org/packages/ManagedCode.Storage.Aws)|[](https://www.nuget.org/packages/ManagedCode.Storage.Aws)| Amazon S3 provider with Object Lock and legal hold operations. |
132
133
|[ManagedCode.Storage.Gcp](https://www.nuget.org/packages/ManagedCode.Storage.Gcp)|[](https://www.nuget.org/packages/ManagedCode.Storage.Gcp)| Google Cloud Storage integration built on official SDKs. |
133
134
|[ManagedCode.Storage.Browser](https://www.nuget.org/packages/ManagedCode.Storage.Browser)|[](https://www.nuget.org/packages/ManagedCode.Storage.Browser)| Browser storage provider with Blazor DI helpers, MVC/static-asset helpers, IndexedDB metadata, and OPFS-backed payload streaming. |
135
+
|[ManagedCode.Storage.Cartograph](https://www.nuget.org/packages/ManagedCode.Storage.Cartograph)|[](https://www.nuget.org/packages/ManagedCode.Storage.Cartograph)| Read-only provider for files inside immutable Cartograph artifacts, with mapped streaming, catalog metadata, and directory listings. |
134
136
|[ManagedCode.Storage.FileSystem](https://www.nuget.org/packages/ManagedCode.Storage.FileSystem)|[](https://www.nuget.org/packages/ManagedCode.Storage.FileSystem)| Local file system implementation for hybrid or on-premises workloads. |
135
137
|[ManagedCode.Storage.Sftp](https://www.nuget.org/packages/ManagedCode.Storage.Sftp)|[](https://www.nuget.org/packages/ManagedCode.Storage.Sftp)| SFTP provider powered by SSH.NET for regulated and air-gapped environments. |
136
138
|[ManagedCode.Storage.OneDrive](https://www.nuget.org/packages/ManagedCode.Storage.OneDrive)|[](https://www.nuget.org/packages/ManagedCode.Storage.OneDrive)| OneDrive provider built on Microsoft Graph. |
137
139
|[ManagedCode.Storage.GoogleDrive](https://www.nuget.org/packages/ManagedCode.Storage.GoogleDrive)|[](https://www.nuget.org/packages/ManagedCode.Storage.GoogleDrive)| Google Drive provider built on the Google Drive API. |
138
140
|[ManagedCode.Storage.Dropbox](https://www.nuget.org/packages/ManagedCode.Storage.Dropbox)|[](https://www.nuget.org/packages/ManagedCode.Storage.Dropbox)| Dropbox provider built on the Dropbox API. |
139
141
|[ManagedCode.Storage.CloudKit](https://www.nuget.org/packages/ManagedCode.Storage.CloudKit)|[](https://www.nuget.org/packages/ManagedCode.Storage.CloudKit)| CloudKit (iCloud app data) provider built on CloudKit Web Services. |
140
142
143
+
### Cartograph artifacts
144
+
145
+
`ManagedCode.Storage.Cartograph` exposes files inside a [Cartograph](https://github.com/angelhernandezm/Cartograph)`.ctg` artifact through `IStorage`. Reads use Cartograph's mapped records and checksums without extracting or buffering the whole file.
Use `AddCartographStorage` for `ICartographStorage`, keyed overloads for multiple artifacts, or `AddStorageFactory` with `CreateCartographStorage` to open artifacts dynamically. Metadata, recursive directory listings, existence checks, and `DownloadAsync` use the same Storage APIs. Returned streams are sequential, read-only, and own their artifact until disposed.
172
+
173
+
The artifact must already contain a Cartograph file catalog. `CreateContainerAsync` validates it; upload, delete, container removal, and legal-hold operations return unsupported results because artifacts are immutable. The module uses the published `Cartograph.Catalog``0.1.0-alpha` package and requires a 64-bit process. Keep artifacts unchanged while their streams are open. See the [Cartograph provider guide](docs/Features/provider-cartograph.md) for catalog requirements and full wiring examples.
174
+
141
175
### Configuring OneDrive, Google Drive, Dropbox, and CloudKit
142
176
143
177
> iCloud Drive does not expose a public server-side file API. `ManagedCode.Storage.CloudKit` targets CloudKit Web Services (iCloud app data), not iCloud Drive.
-`test`: `dotnet test ../../Tests/ManagedCode.Storage.Tests/ManagedCode.Storage.Tests.csproj --configuration Release --filter "FullyQualifiedName~Cartograph"`
32
+
-`format`: `dotnet format ../../ManagedCode.Storage.slnx`
33
+
- Framework and runner: xUnit v2 / VSTest; analyzer policy comes from the root `.editorconfig`.
34
+
35
+
## Applicable Skills
36
+
37
+
-`mcaf-dotnet`
38
+
-`mcaf-testing`
39
+
-`mcaf-dotnet-xunit`
40
+
-`mcaf-architecture-overview`
41
+
-`mcaf-documentation`
42
+
43
+
## Local Rules And Risks
44
+
45
+
- Use the centrally pinned published `Cartograph.Catalog` package and its transitive Format/substrate packages.
46
+
- Returned streams own an independent artifact snapshot and dispose every record lease before its artifact.
47
+
- Never extract whole files to temporary storage or load their payload into `MemoryStream` to implement reads.
48
+
- Keep per-record checksums enabled. Validate catalog entry spans and lengths against record-directory metadata without reading file payloads.
49
+
- Resolve catalog-relative names with ordinal comparison. Ignore `SourceRoot`; catalog paths must never become host filesystem paths.
50
+
- Mutations, legal holds, and container deletion return explicit unsupported results. `CreateContainerAsync` validates an existing artifact without creating one.
51
+
- Downloads stream to a sibling staging file and replace the destination only after successful checksum-verified reading; always clean up staging files and preserve an existing destination on failure.
52
+
- Required documentation: `docs/Architecture.md`, `docs/Features/provider-cartograph.md`, and the README usage section.
53
+
- Inherit root maintainability limits and exception policy.
0 commit comments