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/PerfectlySoft/Perfect 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 — Stale — last commit 2y ago

• 22+ active contributors
• Distributed ownership (top contributor 43% of recent commits)
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ 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 PerfectlySoft/Perfect repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/PerfectlySoft/Perfect.

What it runs against: a local clone of PerfectlySoft/Perfect — 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 PerfectlySoft/Perfect | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 857 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of PerfectlySoft/Perfect. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/PerfectlySoft/Perfect.git
#   cd Perfect
#
# 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 PerfectlySoft/Perfect and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "Sources/PerfectLib/PerfectServer.swift" \\
  && ok "Sources/PerfectLib/PerfectServer.swift" \\
  || miss "missing critical file: Sources/PerfectLib/PerfectServer.swift"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Sources/PerfectLib/File.swift" \\
  && ok "Sources/PerfectLib/File.swift" \\
  || miss "missing critical file: Sources/PerfectLib/File.swift"
test -f "Sources/PerfectLib/Utilities.swift" \\
  && ok "Sources/PerfectLib/Utilities.swift" \\
  || miss "missing critical file: Sources/PerfectLib/Utilities.swift"
test -f "Sources/PerfectLib/JSONConvertible.swift" \\
  && ok "Sources/PerfectLib/JSONConvertible.swift" \\
  || miss "missing critical file: Sources/PerfectLib/JSONConvertible.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 857 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~827d)"
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/PerfectlySoft/Perfect"
  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).

Perfect is a server-side Swift framework that enables developers to build REST APIs, web applications, and backend services entirely in Swift. It provides a complete toolbox including an HTTP server, routing, request/response handling, file I/O, logging, and JSON serialization—all compiled and running natively on macOS and Linux without the JVM or Node runtime. Monolithic single-package structure: Sources/PerfectLib/ contains all core modules (File.swift, Dir.swift, PerfectServer.swift, Bytes.swift, Log.swift, JSONConvertible.swift) with a single Package.swift defining dependencies. Tests/ mirrors the source structure with PerfectLibTests/ containing unit tests. No multi-package workspace; all core server functionality lives in one compiled Swift module.

Swift developers who want to build backend services, REST APIs, and web applications without switching languages. Specifically targets engineers building iOS/macOS backend infrastructure, microservices, or full-stack Swift applications who prefer compile-time safety over dynamic languages like Python or JavaScript.

Production-ready and actively maintained. The project uses Swift 5.2+ with Xcode 11+ compatibility, includes test suites in Tests/PerfectLibTests/, and demonstrates stability through Apache 2.0 licensing and community adoption. However, commit recency and open issue backlog are not visible in the provided data—examine GitHub to confirm ongoing maintenance.

Primary risks are ecosystem lock-in to Swift backend development (smaller ecosystem than Node/Python alternatives) and potential single-point-of-failure if PerfectlySoft team's maintenance slows. The monolithic structure in Sources/PerfectLib/ (103k lines of Swift) means changes ripple across core functionality. Verify current maintainer activity and issue response times before production adoption.

Unable to determine from file listing alone. Check GitHub's commit history and open PRs for recent activity. The presence of Swift 5.2 badge and Xcode 11 support suggests maintenance within last 2–3 years, but recency requires verification.

Clone and build using Swift Package Manager: git clone https://github.com/PerfectlySoft/Perfect.git && cd Perfect && swift build. Run tests with swift test. For guided setup, follow the tutorial at https://github.com/PerfectlySoft/PerfectDocs/blob/master/guide/gettingStarted.md.

Daily commands: swift build compiles the framework. To use it in an application, add Perfect to Package.swift dependencies and import PerfectLib. The framework itself doesn't run standalone; it's embedded in server applications. See PerfectDocs for sample server applications.

• Sources/PerfectLib/PerfectServer.swift — Core server initialization and request handling logic—all contributors must understand the primary entry point for Perfect's framework.
• Package.swift — Swift Package Manager configuration defining all dependencies and module structure—essential for build setup and dependency management.
• Sources/PerfectLib/File.swift — File I/O abstraction layer providing core filesystem operations used throughout the framework.
• Sources/PerfectLib/Utilities.swift — Common utility functions and helper methods relied upon by other core modules.
• Sources/PerfectLib/JSONConvertible.swift — Protocol and implementation for JSON serialization/deserialization—critical for API request/response handling.
• Sources/PerfectLib/Log.swift — Logging infrastructure used across the framework for debugging and monitoring server operations.

• PerfectServer (Swift, Foundation networking) — Central orchestrator managing HTTP request/response lifecycle, route dispatch, and server lifecycle events.
  • Failure mode: Unhandled route requests result in 404; malformed requests may cause parsing errors; server crashes if fatal errors occur in handlers.
• File & Dir (POSIX file I/O, Foundation FileManager) — Abstracts filesystem operations with safe path handling and error reporting for read/write/enumeration operations.
  • Failure mode: File not found, permission denied, or disk full errors propagate to caller; symbolic link loops risk infinite recursion in Dir enumeration.
• JSONConvertible (Swift protocols, manual JSON construction) — Protocol-based serialization contract allowing custom JSON encoding/decoding for request/response payloads.
  • Failure mode: Malformed JSON input causes parsing exceptions; missing required fields risk null pointer dereferences if not checked.
• SysProcess (POSIX fork/exec, process pipes) — Spawns and manages external processes, capturing output and exit codes for subprocess integration.
  • Failure mode: Process spawn failure if system limits exceeded; deadlock risk if buffers fill; zombie processes if exits not properly waited.
• Log (Swift print/file I/O, timestamp formatting) — Centralized logging for server events, request/response tracking, and debugging information.
  • Failure mode: Log file I/O errors silently fail or log to stderr; unbounded log growth can exhaust disk space.

• HTTP Client → PerfectServer — Raw HTTP request with headers and body arrives over network socket.
• PerfectServer → Route Handler — Parsed request metadata and body routed to matching handler function based on path and method.
• Route Handler → File — Handler may read/write files or directories for data persistence or serving static assets.
• Route Handler → SysProcess — Handler spawns external processes (scripts, binaries) and captures output for integration.
• Route Handler → JSONConvertible — Handler serializes response objects to JSON format for transmission.
• PerfectServer → Log — Server logs all major events (startup, request arrival, response sent, errors) for observability.
• JSONConvertible → HTTP Client — Serialized JSON payload sent as HTTP response body with appropriate headers.

Add a new server route or endpoint handler

1. Define your request handler function following Swift closure patterns in PerfectServer.swift (Sources/PerfectLib/PerfectServer.swift)
2. Register the handler with the route mapping system inside the server initialization code (Sources/PerfectLib/PerfectServer.swift)
3. Use JSONConvertible protocol to serialize response objects to JSON payloads (Sources/PerfectLib/JSONConvertible.swift)

Add a new utility function or helper method

1. Implement the utility function in the Utilities module (Sources/PerfectLib/Utilities.swift)
2. Export it as part of the PerfectLib public API by ensuring appropriate access modifiers (Sources/PerfectLib/Utilities.swift)
3. Add corresponding test case to verify behavior (Tests/PerfectLibTests/PerfectLibTests.swift)

Add file or directory operation capability

1. Extend File or Dir classes with new methods for filesystem operations (Sources/PerfectLib/File.swift)
2. Ensure error handling using PerfectError conventions (Sources/PerfectLib/PerfectError.swift)
3. Add logging statements via Log module for debugging filesystem operations (Sources/PerfectLib/Log.swift)
4. Write tests covering success and failure paths (Tests/PerfectLibTests/PerfectLibTests.swift)

• Swift 5.2+ — Type-safe, compiled language enabling high-performance server code with modern syntax and memory safety guarantees.
• Swift Package Manager — Native Swift dependency management and build system ensuring consistency across macOS, Linux, and iOS platforms.
• Foundation framework (implicit) — Cross-platform system APIs for file I/O, process management, and networking primitives.

• Lightweight core library without built-in ORM or database drivers

  • Why: Keeps the framework minimal and modular, allowing projects to choose their own data persistence solutions.
  • Consequence: Developers must integrate third-party database libraries separately, but gain flexibility in technology choices.

• Synchronous file and process operations

  • Why: Simpler, more predictable code patterns familiar to Swift developers; matches Swift concurrency model before async/await era.
  • Consequence: Can block threads on I/O; projects requiring high concurrency need external async wrappers or load balancing.

• Protocol-based JSON conversion (JSONConvertible) rather than automatic codable derivation

  • Why: Explicit control over serialization logic and backward compatibility with pre-Codable Swift versions.
  • Consequence: Requires manual implementation; more boilerplate than modern Codable but offers fine-grained control.

• Does not provide built-in ORM or database abstraction—projects must use external database drivers.
• Does not include authentication/authorization middleware out-of-the-box—security layer responsibility falls to applications.
• Does not provide real-time WebSocket support in core library—projects must extend for bidirectional messaging.
• Not a web framework with templating engine—focused on API/backend infrastructure rather than HTML rendering.

• Synchronous blocking I/O in request handlers: undefined

Swift version coupling: requires Swift 5.2+, so older Xcode or Ubuntu Swift toolchains will fail compilation. Platform-specific code in File.swift and Dir.swift may behave differently on macOS vs. Linux (path separators, permissions). The monolithic PerfectLib module means no granular dependency control—importing PerfectLib brings in all functionality. No visible CI configuration in file list; confirm GitHub Actions or other CI is running before merging. JSON serialization in JSONConvertible may require manual conformance—no reflection-based auto-generation visible.

• JSONConvertible Protocol — Core pattern in Perfect for automatic serialization of Swift types to/from JSON; understanding this is essential for building REST APIs
• Bytes Abstraction — Perfect uses Bytes.swift for low-level binary data handling in file I/O and network operations; essential for understanding data flow
• Process Management (SysProcess) — SysProcess.swift enables spawning and managing child processes; critical for tasks like invoking shell commands or external services from Swift backend code
• File Descriptor-based I/O — Perfect's File.swift wraps POSIX file descriptors for cross-platform file operations; understanding this is key to debugging I/O performance issues
• Server-Sent Events (SSE) — Perfect's logging and request/response streaming rely on SSE patterns; enables real-time server-to-client updates without WebSocket overhead

• vapor/vapor — Leading Swift web framework with similar goals (server-side Swift HTTP) but more modular ecosystem and larger community
• apple/swift-nio — Apple's async I/O and networking library; Perfect could benefit from NIO for modern async/await patterns
• PerfectlySoft/PerfectDocs — Official documentation and tutorials for Perfect; essential companion for understanding framework usage patterns
• PerfectlySoft/Perfect-PostgreSQL — Official database connector package extending Perfect for PostgreSQL backend integration
• PerfectlySoft/Perfect-HTTPServer — Standalone HTTP server implementation built on Perfect core, demonstrating production-ready usage pattern

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 Sources/PerfectLib/File.swift

The File.swift module handles critical file I/O operations but Tests/PerfectLibTests/PerfectLibTests.swift appears minimal. File operations need rigorous testing for edge cases (permissions, symlinks, concurrent access, large files). This is a foundation module that other parts depend on.

• [ ] Create Tests/PerfectLibTests/FileTests.swift with test cases for: file creation, deletion, reading, writing, appending
• [ ] Add tests for edge cases: non-existent paths, permission errors, empty files, special characters in filenames
• [ ] Test concurrent file access scenarios to ensure thread-safety
• [ ] Add tests for symlink handling and directory traversal
• [ ] Run tests on both macOS and Linux (per .jazzy.yaml platform support)

Add unit tests for Sources/PerfectLib/SysProcess.swift

System process execution is a powerful but risky feature. The SysProcess.swift module has no dedicated tests visible in the test structure. Process spawning, signal handling, and stream management need comprehensive coverage to prevent security and stability issues.

• [ ] Create Tests/PerfectLibTests/SysProcessTests.swift
• [ ] Add tests for: launching processes, capturing stdout/stderr, setting working directory, environment variables
• [ ] Test process termination scenarios (normal exit, timeout, signal handling)
• [ ] Test error cases: invalid executable paths, permission denied, resource exhaustion
• [ ] Verify platform compatibility differences between macOS and Linux process APIs

Add unit tests for Sources/PerfectLib/Dir.swift directory operations

Directory manipulation (traversal, listing, creation) is fundamental infrastructure. Dir.swift lacks dedicated test coverage. Proper testing prevents bugs in path handling, recursion, and permission issues that affect the entire framework.

• [ ] Create Tests/PerfectLibTests/DirTests.swift
• [ ] Add tests for: directory creation, deletion, listing contents, recursive operations
• [ ] Test edge cases: empty directories, deeply nested paths, special characters, symlinks to directories
• [ ] Test error handling: non-existent parent paths, permission denied, disk full scenarios
• [ ] Ensure cross-platform compatibility with both macOS and Linux path semantics

• Add unit tests for Dir.swift directory traversal and permission edge cases (recursive deletion, symlinks) in Tests/PerfectLibTests/PerfectLibTests.swift—currently underrepresented
• Write integration examples in a new Examples/ directory showing how to combine PerfectServer + File.swift + JSONConvertible for a basic CRUD API, referenced in README.md
• Implement missing SysProcess.swift tests covering process lifecycle (spawn, wait, signal handling) and error cases in the test suite

The Perfect framework codebase cannot be fully assessed without actual source code content. Based on the file structure alone, several high-risk areas are identifiable: SysProcess.swift (potential command injection), File.swift (potential path traversal), and PerfectServer.swift (TLS/security configuration). The lack of visible code significantly limits security analysis. The framework targets server-side deployment, making it critical to audit core security components. Recommend providing complete source code for comprehensive vulnerability assessment.

• Medium · Incomplete Static Analysis - Limited Code Visibility — Sources/PerfectLib/* (all files). The provided file structure shows only filenames without actual code content. Critical files like SysProcess.swift, File.swift, and PerfectServer.swift are referenced but not analyzed. Full vulnerability assessment requires examination of actual code implementation, especially for file operations, process handling, and network operations. Fix: Provide actual source code content for comprehensive static analysis. Focus on reviewing: 1) SysProcess.swift for command injection risks, 2) File.swift for path traversal vulnerabilities, 3) PerfectServer.swift for security headers and protocol handling
• Medium · Potential Command Injection in SysProcess.swift — Sources/PerfectLib/SysProcess.swift. Based on filename, SysProcess.swift likely handles system process execution. Without code visibility, this is a high-risk area for command injection vulnerabilities if user input is passed to shell commands without proper sanitization or escaping. Fix: Review SysProcess.swift to ensure: 1) Use of ProcessInfo or equivalent safe APIs instead of shell execution, 2) Proper input validation and escaping if shell commands are necessary, 3) Avoid using user-controlled data in system calls
• Medium · Potential Path Traversal in File.swift — Sources/PerfectLib/File.swift. File.swift likely contains file I/O operations. Without code review, cannot confirm if path traversal protections exist when handling user-supplied file paths, which could allow unauthorized access to sensitive files. Fix: Review File.swift to implement: 1) Canonicalization of file paths, 2) Whitelist validation of allowed directories, 3) Prevention of '../' and similar escape sequences, 4) Use of secure APIs that prevent directory traversal
• Low · Missing HTTPS/TLS Configuration Details — Sources/PerfectLib/PerfectServer.swift. PerfectServer.swift is referenced but content unavailable. Cannot verify if the server properly enforces HTTPS, implements security headers (HSTS, CSP, X-Frame-Options), or handles SSL/TLS configuration securely. Fix: Ensure the server implementation includes: 1) HTTPS enforcement, 2) Secure cipher suite configuration, 3) TLS 1.2+ only, 4) Security headers (HSTS, CSP, X-Content-Type-Options, X-Frame-Options)
• Low · No Visible Dependency Lock File or Version Pinning — Package.swift. Package.swift is present but content not provided. Cannot verify if dependencies are properly pinned to specific versions or if security updates are tracked. This could lead to supply chain risks through transitive dependency vulnerabilities. Fix: Ensure: 1) Package.swift pins dependency versions, 2) Regular dependency audits are performed, 3) Use Swift Package Manager security scanning tools, 4) Consider using a Package.resolved file for consistent builds
• Low · Logging Implementation Security — Sources/PerfectLib/Log.swift. Log.swift exists but code is not visible. Cannot verify if sensitive information (passwords, tokens, PII) is being logged, which could expose confidential data in log files. Fix: Implement: 1) Log level configuration to prevent debug logs in production, 2) Sanitization of sensitive data before logging, 3) Secure log file storage with appropriate permissions, 4) Log rotation and retention policies

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.