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/DaveWoodCom/XCGLogger 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

• 10 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% 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 DaveWoodCom/XCGLogger repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/DaveWoodCom/XCGLogger.

What it runs against: a local clone of DaveWoodCom/XCGLogger — 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 DaveWoodCom/XCGLogger | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 707 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "DaveWoodCom/XCGLogger(\\.git)?\\b" \\
  && ok "origin remote is DaveWoodCom/XCGLogger" \\
  || miss "origin remote is not DaveWoodCom/XCGLogger (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/XCGLogger/XCGLogger.swift" \\
  && ok "Sources/XCGLogger/XCGLogger.swift" \\
  || miss "missing critical file: Sources/XCGLogger/XCGLogger.swift"
test -f "Sources/XCGLogger/Destinations/BaseDestination.swift" \\
  && ok "Sources/XCGLogger/Destinations/BaseDestination.swift" \\
  || miss "missing critical file: Sources/XCGLogger/Destinations/BaseDestination.swift"
test -f "Sources/XCGLogger/Formatters/XCGLogFormatter.swift" \\
  && ok "Sources/XCGLogger/Formatters/XCGLogFormatter.swift" \\
  || miss "missing critical file: Sources/XCGLogger/Formatters/XCGLogFormatter.swift"
test -f "Sources/XCGLogger/LogLevels/XCGLogLevel.swift" \\
  && ok "Sources/XCGLogger/LogLevels/XCGLogLevel.swift" \\
  || miss "missing critical file: Sources/XCGLogger/LogLevels/XCGLogLevel.swift"
test -f "Sources/XCGLogger/Destinations/ConsoleDestination.swift" \\
  && ok "Sources/XCGLogger/Destinations/ConsoleDestination.swift" \\
  || miss "missing critical file: Sources/XCGLogger/Destinations/ConsoleDestination.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 707 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~677d)"
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/DaveWoodCom/XCGLogger"
  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).

XCGLogger is a debug logging framework for Swift that replaces NSLog() and print() with contextual metadata output (timestamp, function name, filename, line number). It writes logs to console and optionally to files or custom destinations, solving the problem that Swift lacks C preprocessor macros for the kind of rich debugging output Objective-C developers took for granted. Modular framework structure: Core logging logic likely in Sources/ (inferred from SPM support), with DemoApps/iOSDemo/ containing a full runnable iOS app with storyboards and ViewController integration, plus watchOSDemo Extension/ for watch support. Subspecs (UserInfoHelpers mentioned in README) suggest optional feature modules.

Swift app developers (iOS, watchOS, macOS) who need structured debugging output during development and testing. Specifically those migrating from Objective-C who miss #define debug macros, and teams that want consistent, parseable log output across multiple app targets.

Mature and production-ready. The repo shows a stable v7.1.5 release, supports installation via CocoaPods/Carthage/SPM, includes demo apps for iOS and watchOS, and maintains a CHANGELOG. However, commit recency and active CI/test presence are not visible in the provided data, so verify GitHub activity directly for current maintenance status.

Low to moderate risk. Single maintainer (DaveWoodCom) is a known limitation. No visible package.json or dependency graph in the file list, suggesting minimal external dependencies. Primary risks are: Swift version compatibility as Apple evolves the language, and whether watchOS/iOS demo apps are tested in current Xcode versions. Check open issues and last commit date on GitHub for abandonment risk.

Unable to determine from the file snapshot provided. Check the GitHub repo directly for recent commits, open pull requests, and milestone activity. The CHANGELOG.md file exists but its contents are not shown.

git clone https://github.com/DaveWoodCom/XCGLogger.git && cd XCGLogger && open DemoApps/iOSDemo/iOSDemo.xcodeproj to build and run the demo app in Xcode.

Daily commands: Open DemoApps/iOSDemo/iOSDemo.xcodeproj in Xcode, select the iOSDemo or watchOSDemo scheme from the xcschemes folder, and press Cmd+R. The demo will log output to console and show how to integrate XCGLogger into your code.

• Sources/XCGLogger/XCGLogger.swift — Core logger class that orchestrates all logging operations, manages destinations, and provides the primary API every developer uses
• Sources/XCGLogger/Destinations/BaseDestination.swift — Abstract base class for all logging destinations; understanding this is essential for extending XCGLogger with custom outputs
• Sources/XCGLogger/Formatters/XCGLogFormatter.swift — Formats log messages with metadata like timestamps, function names, and line numbers; critical to understanding output structure
• Sources/XCGLogger/LogLevels/XCGLogLevel.swift — Defines logging levels and severity filtering; foundational for controlling what gets logged
• Sources/XCGLogger/Destinations/ConsoleDestination.swift — Default console output destination; most common use case and example of destination implementation
• Sources/XCGLogger/Destinations/FileDestination.swift — File-based logging destination with rotation and archival support; shows advanced destination pattern

• XCGLogger (Main) (Swift, DispatchQueue) — Orchestrates all logging operations; manages destination registry, applies level filtering, dispatches messages to all destinations asynchronously
  • Failure mode: If level filtering fails, may spam console/file; if dispatch fails, logs are silently dropped
• BaseDestination (Abstract) — Defines interface for log outputs; handles formatter

Create a Custom Destination

1. Create new file extending BaseDestination in Sources/XCGLogger/Destinations/ (Sources/XCGLogger/Destinations/BaseDestination.swift)
2. Override output(logMessage:) method to implement custom routing (e.g., network, database, cloud service) (Sources/XCGLogger/Destinations/BaseDestination.swift)
3. In your app, instantiate and register: let customDest = YourCustomDestination(); log.add(destination: customDest) (Sources/XCGLogger/XCGLogger.swift)

Customize Log Message Format

1. Create class conforming to XCGLogFormatterProtocol in Sources/XCGLogger/Formatters/ (Sources/XCGLogger/Formatters/XCGLogFormatter.swift)
2. Implement format(logMessage:) to return your custom string format (Sources/XCGLogger/Formatters/XCGLogFormatter.swift)
3. Assign to destination: destination.logFormatter = YourCustomFormatter() (Sources/XCGLogger/Destinations/BaseDestination.swift)

Configure File Logging with Rotation

1. In app initialization, create FileDestination specifying log directory and max file size (Sources/XCGLogger/Destinations/FileDestination.swift)
2. Set properties: destination.maxFileSize = 10485760 (10MB), destination.archiveAfterDays = 7 (Sources/XCGLogger/Destinations/FileDestination.swift)
3. Add to logger: log.add(destination: fileDestination) (Sources/XCGLogger/XCGLogger.swift)

Filter Logs by Level and Add Conditional Logging

1. Set logger level: log.logLevel = .debug (logs verbose, debug, info, warning, error, severe) (Sources/XCGLogger/LogLevels/XCGLogLevel.swift)
2. Per-destination filtering: destination.outputLevel = .warning (only shows warning+) (Sources/XCGLogger/Destinations/BaseDestination.swift)
3. Call conditional methods: log.debug(...), log.error(...) to automatically filter (Sources/XCGLogger/XCGLogger.swift)

• Swift (Language) — Pure Swift logging framework designed to replace NSLog/print in Swift projects; no Objective-C macro support in Swift requires alternative approach
• DispatchQueue (GCD) — Asynchronous, thread-safe log processing prevents blocking the main thread during I/O operations
• FileManager — Core framework for file operations, rotation, and archival management in FileDestination
• os_log (Unified Logging) — Apple's modern logging system for iOS 10.3+ integration; respects system log filtering and console capture

• Asynchronous-only logging via DispatchQueue

  • Why: Prevents main thread blocking during I/O; critical for responsive UI
  • Consequence: Log order may not reflect exact call order under extreme load; file writes are guaranteed but timing is non-deterministic

• Multiple concurrent destinations with independent formatting

  • Why: Flexibility to route to console, file, and cloud simultaneously with different formats per destination
  • Consequence: More complex state management; potential for inconsistent message ordering across destinations

• File rotation by size and age (not time-of-day)

  • Why: Simpler, more predictable behavior; works offline
  • Consequence: Cannot guarantee daily rollover; useful for crash logs but less suitable for strict compliance logging

• Context capture at call-site (file, function, line, thread)

  • Why: Provides rich debugging info without developers manually passing context
  • Consequence: Slight performance overhead from capturing stack frames; larger log file sizes

• Real-time log streaming to remote servers (destinations are local/pluggable, but no built-in cloud sync)
• Structured logging / JSON output format (framework focuses on readable text; custom formatters can add JSON)
• Log aggregation across multiple processes or apps
• Performance metrics or telemetry collection beyond debug logging
• Automatic PII redaction or sanitization
• Cross-platform support outside Apple ecosystems (iOS, macOS, watchOS, tvOS only)

No obvious environment variables or service dependencies visible. However: (1) Carthage users on Swift 5.0+ must manually add ObjcExceptionBridging.framework to build phases per README. (2) watchOS demo is in a nested Extension structure (DemoApps/iOSDemo/watchOSDemo Extension/) which may confuse first-time builders. (3) CocoaPods subspecs (UserInfoHelpers) are mentioned as experimental, so their stability is unclear.

• Debug Macro Replacement — Swift's lack of a C preprocessor is the core problem XCGLogger solves; understanding this gap explains why the library exists and how it differs from Objective-C NSLog patterns
• Log Destination Abstraction — XCGLogger supports multiple outputs (console, file, custom destinations); understanding the destination pattern is essential for extending the framework
• Thread-Safe Logging — Multi-threaded apps require synchronized access to shared log buffers and file handles; this is likely handled internally but crucial to understand for production use
• Compile-Time Metadata Capture — XCGLogger uses Swift's #file, #function, #line, and #column compiler directives to capture call-site information without runtime reflection overhead
• Log Formatting and Parsing — The output format (e.g., '2014-06-09 06:44:43.600 [Debug] [AppDelegate.swift:40]...') is customizable; understanding format strings enables structured logging for log aggregation tools
• Dynamic Dispatch Levels — XCGLogger supports multiple log levels (Debug, Info, Warning, Error); filtering by level at runtime reduces noise and performance impact in production

• SwiftyBeaver/SwiftyBeaver — Direct competitor: another popular Swift logging framework with file/cloud destinations and similar metadata enrichment
• CocoaLumberjack/CocoaLumberjack — Objective-C logging framework that influenced Swift logging libraries; predecessor that XCGLogger aims to replace in Swift projects
• realm/realm-swift — Ecosystem companion: often used alongside XCGLogger for persisting structured log data to a local Realm database
• apple/swift-log — Apple's official unified logging API (Swift 5.1+); modern alternative that may supersede third-party frameworks
• pointfreeco/xctest-dynamic-overlay — Complementary testing tool for validating logging behavior in Swift unit tests

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 iOSDemoTests with XCGLogger integration scenarios

The iOSDemoTests/iOSDemoTests.swift file exists but likely contains minimal tests. XCGLogger is a logging framework, so contributors should add tests covering: log output formatting, file logging functionality, multiple destination handling, log level filtering, and custom destination integration. This ensures the framework works reliably across different usage patterns.

• [ ] Examine existing tests in DemoApps/iOSDemo/iOSDemoTests/iOSDemoTests.swift
• [ ] Add tests for console log output formatting with timestamps, filenames, and line numbers
• [ ] Add tests for file logging destination creation and log persistence
• [ ] Add tests for log level filtering (verbose, debug, info, warning, error, severe)
• [ ] Add tests for multiple simultaneous destinations receiving the same log
• [ ] Add tests for custom destination implementations
• [ ] Ensure tests cover both synchronous and asynchronous logging scenarios

Add GitHub Actions CI/CD workflow for automated testing across iOS, macOS, and watchOS

The repo has demo apps for iOS, macOS, and watchOS (visible in DemoApps structure) but likely lacks automated CI. Add GitHub Actions to build and test all three platforms on each commit. This prevents regressions and ensures the framework works across all supported Apple platforms.

• [ ] Create .github/workflows/swift-build-test.yml workflow file
• [ ] Add job to build and test iOSDemo.xcodeproj on iOS simulator
• [ ] Add job to build and test macOSDemo.xcodeproj on macOS
• [ ] Add job to build watchOSDemo.xcscheme (visible in DemoApps/iOSDemo/iOSDemo.xcodeproj/xcshareddata/xcschemes/watchOSDemo.xcscheme)
• [ ] Configure workflow to run on push to main/develop and on pull requests
• [ ] Add status badge to README.md

Create comprehensive API documentation for XCGLogger destinations and formatters

The README snippet shows XCGLogger provides custom destination support and formatting, but there's no visible detailed documentation in the file structure (no docs/ folder or DESTINATIONS.md). New contributors should create guides explaining how to create custom destinations, use built-in formatters, and configure multi-destination logging setups.

• [ ] Create DESTINATIONS.md documenting all built-in destination types available in the framework
• [ ] Create FORMATTERS.md documenting log message formatting options, date formats, and customization
• [ ] Create CUSTOM_DESTINATIONS.md with code examples showing how to implement a custom destination class
• [ ] Add API documentation examples to README.md linking to these new files
• [ ] Include code examples for common scenarios: file logging, remote logging, filtered logging by level

• Add comprehensive unit tests for the FileDestination class (log file rotation, file I/O edge cases) since iOSDemoTests.swift exists but likely doesn't cover all core functionality
• Document best practices for thread-safe logging in multi-threaded apps, as the logging framework likely has thread-safety considerations not obvious from the demo apps alone
• Add a macOS demo app alongside iOS and watchOS, since the framework presumably supports macOS but no demo is visible in the file list

XCGLogger is a logging framework with a relatively clean security posture. The codebase is primarily a library focused on logging functionality with minimal external dependencies. No critical vulnerabilities were identified in the visible file structure. The main security considerations are: (1) ensuring demo applications don't contain real credentials, (2) implementing a responsible vulnerability disclosure policy, (3) excluding test code from production builds, and (4) properly validating/sanitizing user input in the logging framework. The framework's core responsibility is handling log output safely, which appears to be appropriately designed for a debug logging utility. No exposed secrets, hardcoded credentials, or major infrastructure issues were detected in the provided repository structure.

• Low · Demo Applications May Contain Test/Hardcoded Credentials — DemoApps/iOSDemo/iOSDemo/, DemoApps/macOSDemo/macOSDemo/, DemoApps/tvOSDemo/tvOSDemo/. The repository contains multiple demo applications (iOSDemo, macOSDemo, tvOSDemo) that may include hardcoded test credentials, API keys, or configuration values for demonstration purposes. While acceptable for demo code, if any of these are committed to the public repository, they could be exposed. Fix: Review all demo application code to ensure no real credentials are present. Use placeholder values or environment variables for sensitive configuration. Add demo credentials to .gitignore if they must be excluded.
• Low · Missing Security.md or Vulnerability Disclosure Policy — Repository root. The repository does not appear to have a SECURITY.md or similar file documenting how security vulnerabilities should be reported. This makes it difficult for security researchers to responsibly disclose issues. Fix: Create a SECURITY.md file with instructions for reporting security vulnerabilities responsibly (e.g., private disclosure process, contact information).
• Low · Test Files May Have Insufficient Hardening — DemoApps/iOSDemo/iOSDemoTests/iOSDemoTests.swift, DemoApps/macOSDemo/macOSDemoTests/macOSDemoTests.swift. Test files (iOSDemoTests.swift, macOSDemoTests.swift) may not implement proper security controls and could potentially be exploited to bypass application security measures if test code is shipped with production builds. Fix: Ensure test targets are excluded from production builds. Review test code to ensure it doesn't contain security-sensitive logic or bypass mechanisms. Use build configurations to prevent test code inclusion in release builds.
• Low · Missing Input Validation in Logging Framework — XCGLogger core framework (source files not visible in provided structure). As a logging framework, XCGLogger processes user-supplied data (log messages). Without proper validation and sanitization, it could be vulnerable to injection attacks if log output is subsequently processed or displayed in contexts where injection is possible (e.g., file parsing, log aggregation systems). Fix: Implement proper input validation and output encoding for all log messages. Ensure special characters and control sequences are properly escaped when writing to files or other destinations. Consider using safe string formatting methods.

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.