If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ldqk/Masuit.Tools shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 3 active contributors
• MIT licensed
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ldqk/Masuit.Tools repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ldqk/Masuit.Tools.

What it runs against: a local clone of ldqk/Masuit.Tools — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ldqk/Masuit.Tools | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ldqk/Masuit.Tools. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ldqk/Masuit.Tools.git
#   cd Masuit.Tools
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ldqk/Masuit.Tools and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ldqk/Masuit.Tools(\\.git)?\\b" \\
  && ok "origin remote is ldqk/Masuit.Tools" \\
  || miss "origin remote is not ldqk/Masuit.Tools (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Masuit.Tools.Abstractions/Extensions/BaseType/StringExtensions.cs" \\
  && ok "Masuit.Tools.Abstractions/Extensions/BaseType/StringExtensions.cs" \\
  || miss "missing critical file: Masuit.Tools.Abstractions/Extensions/BaseType/StringExtensions.cs"
test -f "Masuit.Tools.Abstractions/Extensions/BaseType/IEnumerableExtensions.cs" \\
  && ok "Masuit.Tools.Abstractions/Extensions/BaseType/IEnumerableExtensions.cs" \\
  || miss "missing critical file: Masuit.Tools.Abstractions/Extensions/BaseType/IEnumerableExtensions.cs"
test -f "Masuit.Tools.Abstractions/Extensions/Dynamics/Clay.cs" \\
  && ok "Masuit.Tools.Abstractions/Extensions/Dynamics/Clay.cs" \\
  || miss "missing critical file: Masuit.Tools.Abstractions/Extensions/Dynamics/Clay.cs"
test -f "Masuit.Tools.Abstractions/Files/FileDetector/AbstractSignatureDetector.cs" \\
  && ok "Masuit.Tools.Abstractions/Files/FileDetector/AbstractSignatureDetector.cs" \\
  || miss "missing critical file: Masuit.Tools.Abstractions/Files/FileDetector/AbstractSignatureDetector.cs"
test -f "Masuit.Tools.Abstractions/DateTimeExt/DateTimeHelper.cs" \\
  && ok "Masuit.Tools.Abstractions/DateTimeExt/DateTimeHelper.cs" \\
  || miss "missing critical file: Masuit.Tools.Abstractions/DateTimeExt/DateTimeHelper.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ldqk/Masuit.Tools"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Masuit.Tools is a comprehensive C# utility library (~2MB, 2.1M LOC) providing 100+ ready-to-use static helper classes for encryption/decryption, reflection, weighted random selection, distributed short IDs, LINQ extensions, file compression, multi-threaded downloads, image cropping, Chinese lunar calendar, Excel export, and stream operations. It solves the problem of repetitive utility code in .NET projects by consolidating battle-tested implementations into a single, lightweight NuGet package. Split-package architecture: Masuit.Tools.Abstractions/ (interface layer with extension methods in BaseType/, DateTimeExt/, Database/), separate compiled packages per runtime (Net45, Net462, Core, Standard), and BenchmarkTest/ for performance validation. Extensions are organized by type (StringExtensions.cs, StreamExtensions.cs, IEnumerableExtensions.cs, etc.) under Extensions/BaseType/.

C# developers across all skill levels building .NET Framework (≥4.5), .NET Standard (≥2.1), or .NET Core (≥2.1) applications who need production-ready utility functions without writing boilerplate code. ASP.NET Core developers get additional web-specific utilities via the Masuit.Tools.AspNetCore package.

Production-ready and actively maintained. The project has significant adoption (NuGet badge visible), clear versioning strategy with distinct packages for Framework/Standard/Core, comprehensive CI/CD templates (.github and .gitee issue templates), and targets modern .NET versions (VisualStudio 2022 v17.8+). Last activity and JetBrains open-source sponsorship indicate ongoing investment.

Low to moderate risk: single-maintainer project (ldqk) with no visible team structure or backup, but comprehensive test coverage exists (BenchmarkTest/ folder shows active benchmarking). The license includes non-standard clauses (2-5x startup capital penalty for labor law violations), which may create ambiguity in corporate adoption. Large surface area (100+ utilities) means potential maintenance burden as .NET evolves.

Active development visible: Directory.Build.props centralized build config, .vscode/ dev environment setup, and dual-platform issue templates (GitHub + Gitee) suggest ongoing localization for Chinese market. No visible PR/commit data in provided structure, but presence of comprehensive templates indicates mature contribution workflow.

Clone from GitHub (https://github.com/ldqk/Masuit.Tools) or Gitee (https://gitee.com/masuit/Masuit.Tools). Install via NuGet: dotnet add package Masuit.Tools.Core (.NET Core), Install-Package Masuit.Tools.Abstraction (Standard/universal), or Install-Package Masuit.Tools.Net (.NET Framework ≥4.6.2). Open in VisualStudio 2022 and build with .NET SDK 2.1.0+.

Daily commands: This is a library, not an executable. Build with dotnet build Masuit.Tools.sln or dotnet build Masuit.Tools.Abstractions/ to validate abstractions. Run benchmarks: dotnet run --project BenchmarkTest/BenchmarkTest.csproj (ImageHasherTest.cs, StreamTest.cs, TreeTest.cs available).

• Masuit.Tools.Abstractions/Extensions/BaseType/StringExtensions.cs — Core string manipulation utilities used throughout the library; essential for understanding text processing conventions
• Masuit.Tools.Abstractions/Extensions/BaseType/IEnumerableExtensions.cs — LINQ extension methods and weighted random selection algorithms; foundational for collection operations across the codebase
• Masuit.Tools.Abstractions/Extensions/Dynamics/Clay.cs — Dynamic object proxy system enabling flexible object construction; critical for understanding the dynamic extension patterns
• Masuit.Tools.Abstractions/Files/FileDetector/AbstractSignatureDetector.cs — Base class for file type detection via magic bytes; architectural foundation for 100+ file format detectors
• Masuit.Tools.Abstractions/DateTimeExt/DateTimeHelper.cs — DateTime and Chinese calendar operations; essential reference for temporal extensions
• Masuit.Tools.Abstractions/Database/DataTableHelper.cs — DataTable manipulation and Excel export utilities; key for understanding data transformation patterns
• Directory.Build.props — Centralized build configuration; necessary for understanding project structure and NuGet packaging

Add a New File Format Detector

1. Determine the file type category (simple magic bytes, ZIP-based, ISO media, compound, etc.) (Masuit.Tools.Abstractions/Files/FileDetector)
2. Create a new detector class in Detectors/ inheriting from the appropriate Abstract base (e.g., AbstractSignatureDetector for magic bytes) (Masuit.Tools.Abstractions/Files/FileDetector/Detectors/[FormatName]Detector.cs)
3. Override Detection() method with file signatures and implement Type property (Masuit.Tools.Abstractions/Files/FileDetector/Detectors/[FormatName]Detector.cs)
4. Register detector in the detector factory/registry (typically auto-discovered via reflection) (Masuit.Tools.Abstractions/Files/FileDetector)

Add a New Extension Method for a Type

1. Identify target type (String, IEnumerable, DateTime, etc.) and create or open corresponding Extensions file (Masuit.Tools.Abstractions/Extensions/BaseType/[TargetType]Extensions.cs)
2. Write a public static method with 'this' parameter targeting the base type (Masuit.Tools.Abstractions/Extensions/BaseType/[TargetType]Extensions.cs)
3. Document behavior (especially for algorithms like weighted selection or calendar conversion) (Masuit.Tools.Abstractions/Extensions/BaseType/[TargetType]Extensions.cs)

Add a New Dynamic Behavior for Clay Objects

1. Create a new behavior class in Extensions/Dynamics/Behaviors/ inheriting IClayBehavior (Masuit.Tools.Abstractions/Extensions/Dynamics/Behaviors/[BehaviorName]Behavior.cs)
2. Implement Invoke(interceptor, ...) to handle member access, property gets/sets, or method calls (Masuit.Tools.Abstractions/Extensions/Dynamics/Behaviors/[BehaviorName]Behavior.cs)
3. Register in ClayBehaviorCollection during Clay initialization or via provider pattern (Masuit.Tools.Abstractions/Extensions/Dynamics/Clay.cs)

Add a New DateTime/Calendar Utility

1. Determine if it's a helper method (DateTimeHelper), extension method, or lunar calendar logic (Masuit.Tools.Abstractions/DateTimeExt)
2. Add method to DateTimeHelper.cs for static helpers or create extension in Extensions/BaseType/ (Masuit.Tools.Abstractions/DateTimeExt/DateTimeHelper.cs)
3. For lunar calendar, update ChineseCalendar.cs with conversion tables or algorithms (Masuit.Tools.Abstractions/DateTimeExt/ChineseCalendar.cs)

• Static Extension Methods (IEnumerable, String, DateTime, etc.) — Zero overhead, LINQ-native API surface; enables fluent chains without creating wrapper objects
• Magic Byte Detection (File Detectors) — Fast, reliable file type identification without depending on file extension; supports 100+ formats via modular detector architecture
• Clay Dynamic Proxy Pattern — Enables runtime object property/method proxying without reflection overhead on every call; supports fluid API and optional chaining
• Weighted Random Selection Algorithm (IEnumerable) — Efficient O(n) sampling with probability

Configuration coupling: .NET Framework projects require AppSettings in web.config/app.config; .NET Core projects need appsettings.json integration (details in README). Missing external configuration causes silent failures, not exceptions. Package fragmentation: Masuit.Tools.Net45 intentionally lacks Redis, HTML parsing, file compression, ASP.NET extensions—using it in .NET 4.6.2+ projects loses functionality without warnings. Chinese calendar (ChineseCalendar.cs) uses hardcoded solar/lunar term data with no historical accuracy validation exposed in API. No async I/O methods; all file/stream operations are synchronous, causing thread pool starvation in high-concurrency scenarios.

• Weighted Random Selection — Masuit.Tools implements non-uniform probability distribution algorithms (visible in RandomExtensions.cs and referenced in README); critical for load balancing, A/B testing, and game mechanics
• Expression Trees — Library uses .NET expression trees for dynamic code generation and reflection optimization; enables runtime LINQ query building without eval-like security risks
• Distributed Short IDs — Masuit.Tools generates compact, globally unique identifiers (likely Snowflake or similar algorithm) for distributed systems without external services
• Lunisolar Calendar Calculation — ChineseCalendar.cs implements non-Gregorian date arithmetic; essential for Chinese business logic, festival scheduling, and historical date conversions
• Stream-based Compression & Multi-threaded I/O — StreamExtensions.cs handles file compression, chunked downloads, and resumable transfers; core patterns for handling large files without memory exhaustion
• Reflection & Dynamic Dispatch — Library abstracts low-level reflection for type inspection, property mapping, and dynamic method invocation; enables generic utilities that work across user-defined types
• Image Hashing & Content-based Deduplication — BenchmarkTest/ImageHasherTest.cs suggests perceptual image hashing; critical for image deduplication, near-duplicate detection without storing pixel data

• jstedfast/MailKit — Similar all-in-one C# utility focus for email protocols; shows same 'batteries-included' design philosophy
• AutoMapper/AutoMapper — Companion library for object mapping frequently needed alongside Masuit.Tools utilities in enterprise .NET projects
• FluentValidation/FluentValidation — Complementary validation framework that pairs with Masuit.Tools extension methods for complete data processing pipelines
• Humanizr/Humanizer — Overlapping string/datetime formatting utilities; direct competitor for StringExtensions and DateTimeHelper functionality
• dotnet/extensions — Official Microsoft utility library; Masuit.Tools duplicates some functionality (DI, logging helpers) but targets older .NET versions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Masuit.Tools.Abstractions extension methods

The Extensions/BaseType directory contains 13 extension classes (StringExtensions, IEnumerableExtensions, StreamExtensions, etc.) but no visible test project in the file structure. These core extensions are heavily used by consumers and lack test coverage. This is critical for a utility library where correctness directly impacts downstream projects.

• [ ] Create Masuit.Tools.Tests project alongside BenchmarkTest
• [ ] Add unit tests for Masuit.Tools.Abstractions/Extensions/BaseType/StringExtensions.cs covering null handling, edge cases, and performance scenarios
• [ ] Add unit tests for Masuit.Tools.Abstractions/Extensions/BaseType/IEnumerableExtensions.cs testing LINQ extension behavior
• [ ] Add unit tests for Masuit.Tools.Abstractions/Extensions/BaseType/StreamExtensions.cs for file operations
• [ ] Set up test CI workflow in .github/workflows/ to run on PR

Add XML documentation and markdown reference for the dynamic Clay extension system

The Masuit.Tools.Abstractions/Extensions/Dynamics/ directory contains 16 files implementing a sophisticated dynamic proxy system (Clay, ClayBehavior, ClayMetaObject), but there are no examples, documentation, or API references visible. New contributors cannot understand when/how to use this feature.

• [ ] Document the purpose and architecture of Clay.cs, ClayActivator.cs, and ClayBehaviorCollection.cs with XML comments
• [ ] Create docs/DYNAMICS_GUIDE.md with concrete examples of dynamic object creation and behavior customization
• [ ] Add unit tests in BenchmarkTest/DynamicsTest.cs demonstrating Clay usage patterns
• [ ] Update README.md with a 'Features' section that explicitly mentions dynamic object support with a link to DYNAMICS_GUIDE.md

Implement GitHub Actions workflow for multi-target framework validation

The repo targets multiple .NET frameworks (evidenced by Directory.Build.props and BenchmarkTest projects) but the .github/workflows/ directory appears empty. There's no CI to catch breaking changes across framework versions (net462, netstandard2.0, net6.0, etc.). This is critical for a library distributed via NuGet.

• [ ] Create .github/workflows/dotnet-test.yml to run 'dotnet test' across all target frameworks on push/PR
• [ ] Create .github/workflows/nuget-pack.yml to validate 'dotnet pack' succeeds and produces correct multi-target DLL outputs
• [ ] Add .github/workflows/codeql-analysis.yml for security scanning (recommended for popular open-source libraries)
• [ ] Document in CONTRIBUTING.md which workflows must pass before PR merge

• Add unit tests for Masuit.Tools.Abstractions/Extensions/BaseType/RandomExtensions.cs—no test file visible; weighted random selection algorithm needs deterministic test cases with seeded RNG
• Document the expression tree utilities (mentioned in README but no visible ExpressionExtensions.cs file)—add code examples and clarify IL generation safety boundaries for security-sensitive applications
• Add async overloads to StreamExtensions.cs and file copy methods—current synchronous-only implementation blocks modern ASP.NET Core usage patterns where async I/O is required

The Masuit.Tools library is a comprehensive utility library with moderate security posture. The primary concerns are around dynamic reflection capabilities (which could be exploited if user input isn't validated), file handling security boundaries, and incomplete security policy documentation. The codebase lacks visible hardcoded secrets and appears well-structured, but reflection-based features and file detection mechanisms require careful input validation. Dependency management oversight is needed. For production use, conduct a detailed code review of reflection and file handling modules, implement comprehensive input validation, and establish a clear security response process. The library is suitable for internal tools but requires security hardening for untrusted input scenarios.

• Medium · Incomplete Security Policy — SECURITY.md. The SECURITY.md file contains a template structure without concrete vulnerability reporting procedures, contact information, or response timelines. This makes it unclear how security researchers can responsibly disclose vulnerabilities. Fix: Complete the Security Policy with: (1) Clear vulnerability reporting contact (security@example.com), (2) Expected response timeline (e.g., 24-48 hours), (3) Supported versions with clear end-of-life dates, (4) Bug bounty program details if applicable, (5) Commit to patching critical vulnerabilities within 30 days.
• Medium · Potential Reflection-based Vulnerabilities — Masuit.Tools.Abstractions/Extensions/Dynamics/. The codebase includes extensive reflection operations (Extensions/BaseType/, Dynamics/ folders) which could be exploited for arbitrary code execution if user input is not properly validated. Files like ClayActivator.cs, DynamicFactory.cs suggest dynamic object creation and invocation. Fix: Implement strict input validation for any user-supplied data used in reflection operations. Whitelist allowed types and methods. Add code access security checks. Document security boundaries for reflection APIs.
• Medium · File Upload/Detection Security Concerns — Masuit.Tools.Abstractions/Files/FileDetector/. The FileDetector module (AbstractSignatureDetector.cs, ApkDetector.cs, etc.) performs file type detection but the security implications of file handling are unclear. File type detection based on signatures can be bypassed. Fix: Document file handling security guidelines. Implement: (1) File size limits, (2) Filename sanitization, (3) Antivirus scanning integration, (4) Isolated processing environment, (5) Clear warnings about detection limitations.
• Low · Missing Cryptographic Security Documentation — Project root - encryption/decryption features. The description mentions 'encryption/decryption' but no visible cryptographic implementation details in file structure. Security strength, algorithm selection, and key management practices are not evident. Fix: Document all cryptographic implementations: (1) Specify algorithms (AES-256, etc.), (2) Key derivation functions, (3) Random number generation methods, (4) IV/Salt handling, (5) Avoid deprecated algorithms like DES or MD5.
• Low · Dependency Management Visibility — .csproj files / NuGet dependencies. No dependency file content was provided in the security context. NuGet packages should be monitored for known vulnerabilities, and transitive dependencies should be audited. Fix: Implement: (1) Regular dependency scanning with tools like OWASP Dependency-Check or GitHub Dependabot, (2) Lock dependency versions, (3) Audit transitive dependencies, (4) Establish a process for updating vulnerable dependencies within 30 days.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.