BlockAds Dev Skill

Overview

This skill provides expert guidance on the blockads-android project, which combines a Go-based VPN tunnel (tunnel/) with an Android Kotlin application (app/src/main/java/...). It helps handle gomobile interop constraints, architectural patterns for the VPN service, and building/debugging the tunnel.

Development Workflows

1. Modifying the Go Tunnel (gomobile)

When adding a new feature or modifying existing logic in the Go tunnel:

• Edit the relevant .go files in the tunnel/ directory (e.g., tunnel/engine.go).
• Ensure all exported functions, methods, and interfaces in Go use strictly gomobile-compatible types (primitives, []byte, basic interfaces).
• Rebuild the tunnel using ./scripts/build_tunnel.sh or the Gradle task ./gradlew buildGoTunnel.
• For detailed constraints on gomobile bindings, read references/gomobile-interop.md.

2. Updating the Android Kotlin App

When integrating new Go tunnel features into Android:

• Update GoTunnelAdapter.kt or VpnService.kt to call the newly bound Go methods.
• Ensure Kotlin interfaces passed to Go (e.g., LogCallback, DomainChecker) match the updated Go interfaces.
• For a deeper understanding of the VPN architecture and data flow, read references/architecture.md.

3. Debugging

• DNS Tracing: The Go engine logs queries via the LogCallback interface to Kotlin. To debug DNS, check DnsLogDao or add prints in the Kotlin callback.
• Root Mode (iptables): The app uses libsu for a root-based transparent proxy mode as an alternative to VpnService. Check RootProxyService and IptablesManager for related logic. See references/root-proxy.md for architecture details.

References

• Architecture: Deep dive into the Go Tunnel Engine and Kotlin VPN Service architecture.
• Root Proxy Mode: Deep dive into the RootProxyService and iptables transparent proxy architecture.
• Gomobile Interop: Rules, constraints, and patterns for passing data between Go and Kotlin via gomobile bind.

The "Cook" Workflow

This skill transforms a high-level feature request into a production-ready implementation through a structured "kitchen" process.

Phase 1: Preparation (Research & Scan)

• Scan: Use grep_search and glob to find existing patterns, related components, and architectural precedents.
• Analyze: Understand how data flows and how existing features are structured in this specific codebase.
• Ingredients: Identify the "ingredients" needed (new classes, UI components, API endpoints, or database changes).

Phase 2: The Recipe (Clear Spec)

• Draft Spec: Create a concise technical plan.
• Check-in: Present the plan to the user.
• Clarify: If anything is ambiguous (UI details, edge cases), ASK for confirmation before touching the stove.

Phase 3: Cooking (Implementation)

• Atomic Commits: (Mental or actual if requested) Build the feature in logical, self-contained steps.
• Idiomatic Code: Follow the project's established style (naming, patterns, libraries).
• Clean Code: Prioritize readability, DRY principles, and proper error handling.

Phase 4: Taste Test (Verification)

• Verify: Run the build (./gradlew assembleDebug) and relevant tests.
• Cleanup: Remove any temporary debug logs, comments, or unused imports.

Phase 5: Serving (Final Review)

• Report: Summarize what was built and how to test it.

Guardrails

• Don't Over-Season: Stay within the scope of the requested feature.
• Fresh Ingredients: Always use the latest project conventions found in GEMINI.md.
• Safety First: Never proceed with high-impact architectural changes without an approved "Recipe".

CSV Translator Workflow

This skill provides a robust way to translate CSV files while managing context window limits by splitting large files into smaller chunks.

Workflow Steps

0. Discovery & Extraction (Optional)

Before translating, you may need to identify what needs translation:

• Find Untranslated Strings: Use node scripts/export_untranslated.cjs <res_dir> [ref_res_dir] to export missing translations to untranslated_strings.csv.
• Find Hardcoded Strings: Use node scripts/extract_hardcoded_strings.cjs <src_dir> to find UI text in code that should be moved to strings.xml.
• Find Unused Strings: Use node scripts/find_unused_strings.cjs <module_name> to clean up resources before exporting.

1. Planning & Analysis

• Identify Target: Determine the CSV file to be translated and the target language(s).
• Count Lines: Use `run_shell_command` with `wc -l` to determine the size of the file.
• Set Chunk Size: Based on the file size and complexity, decide on a target number of lines per chunk (default recommendation: 100-200 lines).

2. Splitting (If Large)

• If the file exceeds the manageable limit, split it into smaller files.
• Use a script (e.g., `scripts/split_csv.cjs`) to ensure data integrity (keeping headers in each chunk or handling them correctly).
• Recursive Check: If a split file is still considered too large for a single translation turn, split it further.

3. Translation

• Translate each chunk individually.
• Maintain the CSV structure and ensure that keys/IDs (if any) are preserved.
• Use a consistent tone and terminology across all chunks.
• DO NOT manually escape special characters (like `'` or `"`) in the CSV; the import script handles this automatically.

4. Merging

• Once all chunks are translated, merge them back into a single final CSV file.
• Use a script (e.g., `scripts/merge_csv.cjs`) to combine the files, ensuring only one header row exists.

5. Importing (Android Specific)

• Use `scripts/import_translations.cjs` to automatically take the merged translations and update the project's `strings.xml` files.
• Command: `node scripts/import_translations.cjs <merged_csv_path> <res_directory>`

6. Validation

• Verify the final CSV file structure and line count matches the original.
• Run a build check (e.g., `./gradlew assembleDebug`) to ensure the imported strings don't break the build.

Guardrails

• Preserve Structure: Never change the number of columns or the meaning of specific fields (like IDs).
• Header Integrity: Ensure the header row is handled correctly during splitting and merging.
• Encoding: Maintain UTF-8 encoding throughout the process.
• Double-Escaping Prevention: Always provide raw text in the CSV. The import script will convert raw quotes into Android-compatible escapes (e.g., `can't` -> `can\'t`).

7. Cleanup & Git

• Ensure you do NOT commit intermediate CSV files (e.g., untranslated strings, chunks, merged files, formatted files) to the repository.
• Delete these temporary files once the import is successfully validated, or ensure they are excluded via `.gitignore`.

GitHub Issue Manager

Overview

This skill automates the lifecycle of GitHub issues within the current repository. It leverages the gh CLI to fetch data, generates structured reports using AI-driven comment analysis, and provides a workflow for implementing and validating fixes.

Core Workflow

1. Ingestion & Analysis

Use scripts/fetch_issue_data.cjs to get the latest activity.

• Trigger: "Show me latest issues", "Give me a daily report", "What happened on GitHub today?"
• Action:
  1. Run the fetch script.
  2. Provide a concise summary of the identified issues.
  3. Mandatory: Use the ask_user tool to ask the user which issue they would like to fix or if they want to proceed with a full report.

2. Issue Resolution

Once an issue is selected:

• Research: Deep dive into the selected issue's description and comments.
• Reproduce: Attempt to reproduce the issue locally (e.g., via unit tests or UI inspection).
• Fix: Implement the fix following project conventions.
• Validate: Run ./gradlew assembleDebug and relevant tests.

3. Pull Request Creation

Use scripts/create_pull_request.cjs to automate the final step.

• Trigger: "Create a PR for this fix", "Wrap up issue #123".
• Action: Create a branch, commit changes, push, and create a PR referencing the issue.

Bundled Resources

scripts/

• fetch_issue_data.cjs: Fetches issues and comments updated within a specific timeframe.
• create_pull_request.cjs: Automates branch creation, commit, push, and PR submission.

references/

• report_template.md: A structured Markdown template for daily status reports.

Usage Examples

"Get latest issues from the last 24h"

1. Run node .gemini/skills/github-issue-manager/scripts/fetch_issue_data.cjs 1
2. Summarize each issue and its comments.
3. Identify which issues need immediate attention.

"Fix issue #45"

1. Read the issue description and comments carefully.
2. Search the codebase for related symbols or UI components.
3. Implement the fix.
4. Run node .gemini/skills/github-issue-manager/scripts/create_pull_request.cjs 45 fix/issue-45 "Fix crash in UI" "This PR addresses the crash reported in #45..."

Upgrade App Workflow

This skill automates the end-to-end process of releasing a new version of the application.

Workflow Steps

1. Preparation

• Ensure the git working tree is clean (git status).
• Check gh auth status to ensure GitHub CLI is authenticated.

2. Research & Versioning

• Read app/build.gradle.kts to find the current versionCode and versionName.
• Suggest a new versionName (e.g., if current is 1.7.1, suggest 1.7.2).
• Increment versionCode by 1.

3. Update Files

• Update app/build.gradle.kts with the new version info.
• Fetch commits since the last tag:

  LAST_TAG=$(git describe --tags --abbrev=0)
  git log $LAST_TAG..HEAD --oneline
  

• Generate a concise changelog and write it to fastlane/metadata/android/en-US/changelogs/<new-versionCode>.txt.
• MANDATORY: Check the character count of the changelog. It MUST NOT exceed 500 characters (Google Play Store limit). Use wc -c <file_path> to verify. If it exceeds the limit, shorten it before proceeding.

4. User Confirmation

• MANDATORY: Present the generated changelog to the user.
• WAIT for the user to confirm or edit the changelog before proceeding.

5. Build Verification

• Run ./gradlew assembleDebug to verify the build.
• If it fails, stop and report errors.

6. Git & GitHub Operations (MUST BE SEQUENTIAL)

• To avoid race conditions and tagging the wrong commit, execute the commit and tagging sequentially in a single command block:

  git add app/build.gradle.kts fastlane/metadata/android/en-US/changelogs/<new-versionCode>.txt && \
  git commit -m "chore: bump version to <versionName> (<versionCode>)" && \
  git tag v<versionName> && \
  git push origin main && \
  git push origin v<versionName> && \
  gh release create v<versionName> --title "v<versionName>" --notes-file fastlane/metadata/android/en-US/changelogs/<new-versionCode>.txt
  

Guardrails

• Race Condition Prevention: Never separate git commit and git tag into different tool calls in the same turn without wait_for_previous: true.
• Validation: Always verify the build with ./gradlew assembleDebug before pushing.
• Confirmation: Always wait for user confirmation on the changelog.
• Format: Ensure the tag matches the vX.Y.Z format.
• Changelog Limit: The changelog file MUST be under 500 characters to avoid Google Play API rejection. Always verify with wc -c.