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/Dimillian/IceCubesApp 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 2w ago
• 14 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{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 Dimillian/IceCubesApp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Dimillian/IceCubesApp.

What it runs against: a local clone of Dimillian/IceCubesApp — 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 Dimillian/IceCubesApp | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | 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 ≤ 43 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 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 "IceCubesApp/App/Main/IceCubesApp.swift" \\
  && ok "IceCubesApp/App/Main/IceCubesApp.swift" \\
  || miss "missing critical file: IceCubesApp/App/Main/IceCubesApp.swift"
test -f "IceCubesApp/App/Router/AppRegistry.swift" \\
  && ok "IceCubesApp/App/Router/AppRegistry.swift" \\
  || miss "missing critical file: IceCubesApp/App/Router/AppRegistry.swift"
test -f "IceCubesApp/App/Tabs/NavigationTab.swift" \\
  && ok "IceCubesApp/App/Tabs/NavigationTab.swift" \\
  || miss "missing critical file: IceCubesApp/App/Tabs/NavigationTab.swift"
test -f "IceCubesActionExtension/ActionRequestHandler.swift" \\
  && ok "IceCubesActionExtension/ActionRequestHandler.swift" \\
  || miss "missing critical file: IceCubesActionExtension/ActionRequestHandler.swift"
test -f "IceCubesApp.xcodeproj/project.pbxproj" \\
  && ok "IceCubesApp.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: IceCubesApp.xcodeproj/project.pbxproj"

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

IceCubesApp is a native SwiftUI-based Mastodon client for iOS, macOS, iPadOS, and visionOS that lets users connect to any Mastodon instance to browse timelines, interact with posts, and manage accounts. It uniquely implements features like tag groups (custom timelines from multiple tags), remote local timelines, quote posts, and semi-automatic timeline sync via Mastodon's marker API and streaming events, with home timeline caching powered by the Bodega SQLite wrapper. Monolithic Xcode project structure: root contains IceCubesApp (main app), IceCubesActionExtension (share/action sheet extension), AlternateIcons/ (app icon variants), and .github/workflows/ for CI. No clear separation into packages, but modularization likely happens via SwiftUI's View composition and ObservableObject state management. Localization is handled conventionally via .lproj directories (en.lproj, ca.lproj, be.lproj, etc.). Assets live in xcassets bundles per target.

iOS/macOS developers building Mastodon clients, ActivityPub enthusiasts wanting a feature-rich decentralized social app, and users who prefer open-source alternatives to Twitter/X that work across Apple platforms. Contributors are SwiftUI specialists interested in multiplatform architecture and real-time streaming.

This is a production-ready, actively maintained project available on the App Store (com.thomasricouard.IceCubesApp). The monolithic 1.29MB Swift codebase, presence of localization across multiple languages (en-GB, be, ca, etc.), CI/CD pipelines (.github/workflows/), and code formatting standards (.swiftformat) indicate a mature, well-organized project. It has substantial real-world usage through its App Store distribution.

Single-maintainer risk is moderate (Dimillian controls the primary repo). The codebase is large (~1.3MB) but lacks visible test infrastructure in the file listing, which is common but concerning for a social app handling authentication and real-time data. Dependency management relies on Swift Package Index (see AGENTS.MD and bash scripts), and AGPL v3 licensing may create friction in some enterprise contexts. The 1:1 Swift-to-JavaScript ratio suggests minimal external build tooling risk.

The repo is actively maintained with recent translation validation workflows (.github/workflows/validate_translations.yml) and Dependabot configuration for dependency updates. Multiple app icon variants suggest ongoing design iteration. The presence of CLAUDE.md and AGENTS.MD indicates recent documentation work. No specific open PRs visible in the file list, but the project maintains consistent code formatting rules and localization efforts across numerous language packs.

Check README for instructions.

Daily commands: No Makefile or npm scripts visible. Run via Xcode: (1) Open IceCubesApp.xcodeproj, (2) Select the IceCubesApp target, (3) Choose a simulator or device, (4) Press Cmd+R to build and run. For macOS, select the macOS build target instead. visionOS requires visionOS Simulator or device running visionOS 1.0+.

• IceCubesApp/App/Main/IceCubesApp.swift — Main app entry point and SceneDelegate; sets up the root view hierarchy and app lifecycle management.
• IceCubesApp/App/Router/AppRegistry.swift — Central routing registry that handles deep linking and navigation between tabs and features; critical for understanding how the app structures its routes.
• IceCubesApp/App/Tabs/NavigationTab.swift — Core navigation controller for the primary tab-based UI; handles state and transitions between major sections.
• IceCubesActionExtension/ActionRequestHandler.swift — Share extension handler that bridges system sharing APIs to the Mastodon client; essential for understanding app extensions.
• IceCubesApp.xcodeproj/project.pbxproj — Xcode project configuration including build targets for main app, widgets, notifications, and action extension; defines all build settings and dependencies.
• .github/workflows/validate_translations.yml — CI/CD pipeline for translation validation; shows how the app manages i18n across multiple languages and locales.

Add a New Tab to Main Navigation

1. Create a new tab view file in IceCubesApp/App/Tabs/ (e.g., NewTab.swift) with @State and navigation logic. (IceCubesApp/App/Tabs/NewTab.swift)
2. Register the tab in NavigationTab.swift's tab enumeration and add a TabView case with the tab icon and label. (IceCubesApp/App/Tabs/NavigationTab.swift)
3. Add a route case to AppRegistry.swift to handle deep links to the new tab. (IceCubesApp/App/Router/AppRegistry.swift)
4. Update AppView.swift to include the new tab in the TabView layout. (IceCubesApp/App/Main/AppView.swift)

Add a New Settings Section

1. Create a new settings view file in IceCubesApp/App/Tabs/Settings/ (e.g., NewSettingView.swift) following the pattern of ContentSettingsView.swift. (IceCubesApp/App/Tabs/Settings/NewSettingView.swift)
2. Add a NavigationLink in the appropriate settings parent view (e.g., AccountSettingView.swift or ContentSettingsView.swift) to navigate to the new settings section. (IceCubesApp/App/Tabs/Settings/AccountSettingView.swift)
3. If settings persist, bind to an @AppStorage or @EnvironmentObject state variable to sync across app lifecycle. (IceCubesApp/App/Main/IceCubesApp.swift)

Add Deep Link Routing

1. Define a new URL pattern enum case in AppRegistry.swift (e.g., case .profile(id: String)). (IceCubesApp/App/Router/AppRegistry.swift)
2. Implement URL parsing logic in AppRegistry.swift's parse function to match incoming URLs against your new pattern. (IceCubesApp/App/Router/AppRegistry.swift)
3. In AppView.swift or NavigationSheet.swift, add a navigationDestination or sheet modifier that responds to the new route case. (IceCubesApp/App/Main/AppView.swift)

Extend the Share Extension with New Action

1. Edit ActionRequestHandler.swift to add new business logic for handling the shared content (e.g., parsing metadata, formatting). (IceCubesActionExtension/ActionRequestHandler.swift)
2. Update Action.js to extract and pass additional data from the web page (e.g., selected text, images, metadata). (IceCubesActionExtension/Action.js)
3. Update IceCubesActionExtension.entitlements if the new action requires additional capabilities (e.g., app groups, pasteboard). (IceCubesActionExtension/IceCubesActionExtension.entitlements)

• SwiftUI — Declarative UI framework native to iOS; enables rapid iteration on the Mastodon client's complex, data-driven interface without Manual UIKit boilerplate.
• Swift Package Manager (SPM) — Modular dependency management for external packages (visible in Package.resolved); decouples Mastodon API client and networking libraries from the main app.
• App Extensions (Action, Notifications, Widgets) — System-level integration allows users to share to Mastodon from any browser/app and receive notifications without launching the full app.
• XCConfig & Entitlements — Separation of build-time configuration (IceCubesApp.xcconfig.template) and runtime capabilities (entitlements) enables secure distribution and environment-specific builds.

• Tab-based navigation (NavigationTab.swift) instead of stack-based

  • Why: Persistent tab state and user expectation for social media apps; Mastodon is primarily a feed-centric experience.
  • Consequence: Harder to maintain deep navigation history within tabs; requires careful state management in NavigationSheet.swift for modal flows.

• Multiple targets (main app, action extension, notifications, widgets) in single Xcode project

  • Why: Shared code, assets, and localization strings reduce duplication and maintenance burden.
  • Consequence: Increased project complexity; care required to avoid circular dependencies and to correctly configure entitlements per target.

• AppRegistry as centralized route resolver

  • Why: Single source of truth for URL parsing prevents navigation bugs and makes deep linking testable.
  • Consequence: AppRegistry becomes a bottleneck if routing logic grows; requires discipline to keep URL patterns documented.

• undefined

  • Why: undefined
  • Consequence: undefined

Mastodon instance URL handling: users must input a valid instance URL (e.g., mastodon.social); misconfigured instances will silently fail API calls. Streaming events are critical for live timeline updates—if WebSocket connection drops, the app may show stale content until manual refresh. AGPL v3 licensing means any modifications to distributed binaries require source disclosure. Localization completeness: adding new UI strings requires translations in all ~10 language packs or validate_translations.yml will fail CI. The app relies on Bodega for cache management; cache corruption can only be recovered by a full app reinstall (likely behavior, not visible in code).

• ActivityPub Protocol — IceCubesApp connects to Mastodon servers which implement ActivityPub; understanding the federation model and object structure (Create, Update, Delete activities) is essential for grasping why remote timelines and federated interactions work
• WebSocket Streaming (Server-Sent Events variant) — The README mentions 'streaming events' for live timeline updates and real-time post editing/deletion; Mastodon uses persistent WebSocket connections to push updates, a key performance optimization over polling
• SwiftUI @ObservableObject and @Published — The entire app's reactivity depends on Observable state patterns; this is the core MVVM mechanism for binding UI to model changes without manual KVO or Combine subscriptions
• OAuth 2.0 Authorization Code Flow — Mastodon authentication requires OAuth 2.0; users must authorize IceCubesApp to access their account, with tokens stored securely in Keychain—essential for multi-account and session management
• SQLite PRAGMA and Transaction Management (via Bodega) — Home timeline caching uses Bodega's SQLite wrapper; understanding cache invalidation, transaction rollback on corruption, and ACID guarantees prevents silent data loss when switching accounts or updating posts
• Multiplatform Conditional Compilation (#if os(...)) — IceCubesApp runs on iOS, macOS, iPadOS, and visionOS with platform-specific UI (sidebar on macOS/iPad); conditional compilation directives segregate layout logic, critical for maintainability across 4 OSes
• App Extensions (Share / Action Extension) — IceCubesActionExtension lets users post from Safari without opening the app; extensions run in separate processes with limited sandbox, requiring careful data passing via shared container and App Groups entitlements

• mastodon/mastodon — The canonical Mastodon server implementation; IceCubesApp is a client consuming this platform's API and streaming protocol
• Alamofire/Alamofire — Likely HTTP networking layer for Mastodon API calls; common dependency in Swift apps for cleaner request/response handling than raw URLSession
• mergesort/Bodega — The SQLite caching wrapper explicitly mentioned in README as powering home timeline cache; critical dependency for offline timeline functionality
• mozilla/firefox-ios — Comparable large-scale SwiftUI + multiplatform iOS/macOS app; offers patterns for conditional UI (sidebar on iPad), localization, and extension architecture
• pixelfed/pixelfed — Sister ActivityPub project (image-sharing); IceCubesApp could extend to support Pixelfed via compatible API; relevant ecosystem exploration for decentralized social networks

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 SwiftFormat CI validation workflow to enforce code style consistency

The repo has a .swiftformat configuration file but no GitHub Actions workflow to validate code formatting in PRs. This is critical for a multi-contributor project to maintain consistent Swift code style. Currently, there's only .github/workflows/validate_translations.yml. Adding a SwiftFormat validation step would prevent merge conflicts caused by formatting disagreements and reduce review friction.

• [ ] Create .github/workflows/validate_swiftformat.yml to run swiftformat --lint on all Swift files
• [ ] Configure the workflow to fail if formatting violations are detected
• [ ] Document the expected format in CONTRIBUTING.md or update README with setup instructions for local swiftformat
• [ ] Test the workflow by verifying it catches formatting issues on a test branch

Create translation contribution guide and fix inconsistent .lproj directory structure validation

The repo has 14+ language localizations across IceCubesActionExtension (with .lproj folders for be, ca, en-GB, en, es, eu, ko, nb, pl, uk, zh-Hans, zh-Hant) but the main app structure isn't shown in the file listing. There's a validate_translations.yml workflow but no documented contributor guide. New contributors don't know which languages need support, how to add new languages, or what strings to translate. Creating a TRANSLATIONS.md guide and potentially enhancing the validation workflow would lower the barrier to translation contributions.

• [ ] Audit all .lproj directories in both main app and IceCubesActionExtension to create a complete language support matrix
• [ ] Create TRANSLATIONS.md documenting: supported languages, how to add a new language, which files require localization, and the translation workflow
• [ ] Enhance .github/workflows/validate_translations.yml to check for missing InfoPlist.strings in new languages and report coverage gaps
• [ ] Add language codes reference and link to crowdsourcing/community translation resources if applicable

Add unit tests for IceCubesActionExtension ActionRequestHandler.swift

The action extension has ActionRequestHandler.swift but there's no evidence of test coverage for this critical component. Action extensions handle share-to-app functionality which is user-facing and error-prone. Adding unit tests would ensure the extension handles various input types, edge cases, and Mastodon URL patterns correctly. This is a concrete, bounded area that would significantly improve reliability.

• [ ] Create IceCubesActionExtensionTests/ directory with test target if it doesn't exist
• [ ] Write unit tests for ActionRequestHandler covering: valid Mastodon URLs, invalid URLs, nil inputs, and edge cases (redirect URLs, URL encoding)
• [ ] Write tests for Action.js JavaScript handler to verify it correctly extracts URLs from web pages
• [ ] Add test coverage reporting to CI workflow and document expected coverage percentage in CONTRIBUTING.md

• Add unit tests for the Mastodon API response parsing layer (currently no test/ directory visible), starting with Models that decode Status and Account JSON—this is foundational for preventing regression bugs in timeline rendering
• Implement dark mode variant icons in AlternateIcons/ (currently only light icon assets visible in .pngs and .svgs)—design 3 additional dark icon sets using the purple_cube style and add to AppIcon.xcassets with darkAqua appearance set
• Add missing localization for German (de.lproj/) and French (fr.lproj/) by copying en.lproj/InfoPlist.strings to new locale folders and translating IceCubesActionExtension strings for the action extension's UI labels

The IceCubesApp codebase shows reasonable security practices with multi-target separation, localized build configurations, and modular architecture. However, there are opportunities for improvement: (1) dependency vulnerability scanning should be enhanced for Swift Package Manager, (2) configuration files need review to ensure no secrets are hardcoded, (3) entitlements should be audited for least-privilege access, and (4) network security practices should be documented and verified. No critical vulnerabilities were identified in the static analysis of the file structure, but actual code review of Swift and JavaScript files would be necessary for a complete assessment. The app follows good iOS development practices with separate targets for extensions and proper entitlements separation.

• Medium · Missing dependency lock file verification — IceCubesApp.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. The Package.resolved file exists but there is no evidence of dependency pinning strategy or security scanning for Swift Package Manager dependencies. The repository lacks visible dependency vulnerability scanning tools like Dependabot configured for Swift packages. Fix: Enable Dependabot for Swift Package Manager dependencies, regularly audit and update dependencies, and implement automated security scanning in CI/CD pipeline
• Medium · Configuration template not secured — IceCubesApp.xcconfig.template. The file 'IceCubesApp.xcconfig.template' is a template configuration file that may contain sensitive examples or structure that could guide attackers. No evidence of secrets management strategy visible. Fix: Ensure no sensitive examples are included in template files, use environment variables for secrets, and document secure configuration practices
• Low · Release configuration file exposure — IceCubesApp-release.xcconfig. The 'IceCubesApp-release.xcconfig' file may contain release-specific configuration that could reveal build strategies or environment details to attackers. Fix: Review the file contents to ensure no sensitive information is hardcoded; use environment-based configuration for production deployments
• Low · Entitlements files require review — IceCubesApp/App/IceCubesApp.entitlements, IceCubesActionExtension/IceCubesActionExtension.entitlements. Multiple .entitlements files exist across different targets (main app, action extension, notifications) that define app capabilities and permissions. Overly broad entitlements could increase attack surface. Fix: Audit all entitlements files to ensure only necessary capabilities are enabled; follow principle of least privilege for app permissions
• Low · JavaScript in Action Extension — IceCubesActionExtension/Action.js. The file 'IceCubesActionExtension/Action.js' contains JavaScript code for share extension. JavaScript execution requires careful validation to prevent injection attacks. Fix: Review the JavaScript code for injection vulnerabilities, sanitize all user inputs, and ensure no dynamic code evaluation is performed
• Low · Missing security headers documentation — IceCubesApp configuration. No visible configuration for security headers (CSP, X-Frame-Options, etc.) in the codebase. As a Mastodon client app, network requests should be properly validated. Fix: Implement certificate pinning, validate all SSL/TLS certificates, and add security headers validation for API communications

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.