ADFA-5067: Support deep links to open projects and files

.well-known/README.md

@@ -0,0 +1,20 @@
+# `.well-known` (ADFA-5067)
+
+`assetlinks.json` in this directory is the [RFC 5785](https://www.rfc-editor.org/rfc/rfc5785) /
+[Digital Asset Links](https://developers.google.com/digital-asset-links) file required for Android
+App Links to `https://www.appdevforall.org/device/open/project/...` to auto-verify.
+
+This directory lives in the repo only until the actual website exists. To activate it:
+
+1. Copy this directory verbatim to the web server root, so it serves at
+   `https://www.appdevforall.org/.well-known/assetlinks.json` with `Content-Type: application/json`.
+2. Replace the `TODO_REPLACE_WITH_RELEASE_SIGNING_SHA256_FINGERPRINT` placeholder with the SHA-256
+   fingerprint of the certificate that actually signs the released APK/AAB — get it via
+   `keytool -list -v -keystore <release.jks>` (whoever holds the release keystore), or from the Play
+   Console under **App integrity > App signing key certificate** if Play App Signing is used. This
+   cannot be filled in from source; it's a secret held by release engineering, not derivable from this
+   repository.
+
+Until both steps are done, `android:autoVerify="true"` on `DeepLinkActivity`'s intent-filter will fail
+Digital Asset Links verification, and Android may show a disambiguation chooser instead of opening the
+app directly when a link is tapped. This is expected for now.

.well-known/assetlinks.json

@@ -0,0 +1,12 @@
+[
+  {
+    "relation": ["delegate_permission/common.handle_all_urls"],
+    "target": {
+      "namespace": "android_app",
+      "package_name": "com.itsaky.androidide",
+      "sha256_cert_fingerprints": [
+        "TODO_REPLACE_WITH_RELEASE_SIGNING_SHA256_FINGERPRINT"
+      ]
+    }
+  }
+]

ARCHITECTURE.md

@@ -51,6 +51,14 @@ Feature code layers as **UI → ViewModel → Repository → data source**, with
 
 **EventBus is a deliberate side-channel.** Long-running, cross-module signals (build/install lifecycle, editor events) are broadcast via GreenRobot EventBus (`@Subscribe(threadMode = ThreadMode.MAIN)`) and the `eventbus-events` module's shared event types. Treat it as the integration bus *between* subsystems; don't use it to replace a ViewModel's own state inside a single screen.
 
+**App Links enter through a UI-less trampoline, not `MainActivity` directly.** `DeepLinkActivity` (`app/src/main/java/com/itsaky/androidide/activities/DeepLinkActivity.kt`) is the sole `<intent-filter>` holder for `https://www.appdevforall.org/device/open/project/...`. It never renders anything — it parses the URI into a `DeepLinkRequest` (project name plus an optional file/line/column), checks whether an editor is already on screen (`ActionContextProvider.getActivity()`, the live `EditorHandlerActivity` tracker -- not `IProjectManager`'s `workspace`, which stays null for the whole duration of a Gradle sync even while the editor is already open), and routes to `MainActivity` (nothing open) or the live, `singleTask` `EditorActivityKt`/`EditorHandlerActivity` (a project is open — reused via `onNewIntent`), then finishes itself. This avoids a visible flash of `MainActivity`'s real UI when the actual destination is the already-running editor.
+
+`EditorHandlerActivity.onNewIntent` then branches on `projectDirPath` (set as soon as a project starts opening) rather than `workspace` so the mid-sync case still matches correctly: **same project already open** — no project-wise work, just navigate to the requested file (`applyDeepLinkFileRequest`); **a different project is open** — the existing, unmodified `confirmProjectClose()` dialog runs (it also guards against a second confirm-close request overlapping a manual close or an in-flight save, and a *third* overlapping request supersedes the second's pending callback rather than being dropped), and only once the user actually confirms does an `onDestroy()`-triggered hand-off (`PendingDeepLinkOpen`, Koin-provided) start the new project — deliberately deferred to `onDestroy()`, not fired synchronously after `finish()`, so the new `PROJECT_PATH` can't race a `singleTask` re-delivery to the dying instance; `projectDirPath` **is still blank** — this instance never actually finished initializing a project (e.g. recreated after process death with no `PROJECT_PATH` extra), so `confirmProjectClose()` would silently no-op (`contentOrNull` is null); this case reuses the same `onDestroy()`-deferred hand-off instead of showing a close dialog for a project that was never really open; **nothing was open** — `MainActivity.openProject`/`EditorHandlerActivity.postProjectInit` apply the pending file request once the cold-opened project's sync succeeds.
+
+`DeepLinkActivity`'s "is a live editor already on screen" check (`ActionContextProvider.getActivity()`) is itself a heuristic, not a guarantee: Android can still spin up a genuinely new `EditorActivityKt` instance instead of delivering to the live one via `onNewIntent`. `BaseEditorActivity.onCreate` is `EXTRA_KEY`'s only other reader on the editor side for exactly this case — it compares the deep link's requested project name against whatever project the new instance actually ends up holding (explicit `PROJECT_PATH` extra, restored `savedInstanceState`, or the process-wide `ProjectManagerImpl` singleton's last-loaded project) and, on a mismatch, bounces back to `MainActivity` with the deep link forwarded rather than silently continuing to build editor UI for the wrong project.
+
+The optional file path is attacker-controllable (a URL segment), so it's resolved through `PathTraversal.resolveWithinDirectory`'s traversal/symlink guard rather than a bare `File` join, both when opening a file in the already-open project and when matching the requested project name to a directory under `Environment.PROJECTS_DIR` (`findValidProjectByName`).
+
 ## Module Structure
 
 Strategy: **layer-and-subsystem based**, not feature-by-feature. The Gradle build has ~80 modules (`settings.gradle.kts`) plus three included composite builds. `app` is the integration point; the rest are libraries it composes.
@@ -100,7 +108,7 @@ These structural facts shape every module. Day-to-day build *commands* live in `
 
 > **Persistence policy (authoritative):** new relational/queryable persistence uses **Room** (`@Entity` + DAO + `RoomDatabase` with explicit migrations, provided via Koin). Non-relational settings use the **filesystem/preferences (DataStore)**. **Raw SQLite is the exception, not the default** — see [ADR 0001](docs/adr/0001-prefer-room-for-persistence.md).
 >
-> **Recent Projects** is the reference example of the default: `app/src/main/java/com/itsaky/androidide/roomData/recentproject/` (`RecentProjectRoomDatabase`, `@Database version = 4` with migrations 1→4; `RecentProjectDao`; the `RecentProject` `@Entity` → table `recent_project_table`). It's provided via Koin in `di/AppModule.kt` and consumed by `MainViewModel`, `RecentProjectsViewModel`, `MainActivity`, `ProjectInfoBottomSheet`, and `ProjectCreationManager`.
+> **Recent Projects** is the reference example of the default: `app/src/main/java/com/itsaky/androidide/roomData/recentproject/` (`RecentProjectRoomDatabase`, `@Database version = 4` with migrations 1→4; `RecentProjectDao`; the `RecentProject` `@Entity` → table `recent_project_table`). It's provided via Koin in `di/AppModule.kt` and consumed by `RecentProjectsViewModel`, `MainActivity`, `EditorHandlerActivity`, `ProjectInfoBottomSheet`, and `ProjectCreationManager`.
 >
 > **Raw SQLite is allowed only when** the database is prebuilt and opened read-only, the data is performance/allocation-critical and needs granular schema control, or the schema is shared across a process/component boundary. Current exceptions: symbol indexing (`lsp/indexing/SQLiteIndex.kt`), tooltips (`idetooltips/ToolTipManager.kt`), in-app/plugin help (`plugin-manager/.../documentation/PluginDocumentationManager.kt`), and the local web server (`app/.../localWebServer/WebServer.kt`). The `androidx.room:*` strings in `editor`'s `GroovyAutoComplete` are autocomplete suggestions for the *user's* code, not CoGo persistence.
 >

app/src/main/AndroidManifest.xml

@@ -96,6 +96,22 @@
             android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize"
             android:exported="true"
             android:theme="@style/Theme.AndroidIDE" />
+        <activity
+            android:name=".activities.DeepLinkActivity"
+            android:exported="true"
+            android:excludeFromRecents="true"
+            android:noHistory="true"
+            android:theme="@android:style/Theme.Translucent.NoTitleBar">
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data
+                    android:scheme="https"
+                    android:host="www.appdevforall.org"
+                    android:pathPrefix="/device/open/project/" />
+            </intent-filter>
+        </activity>
         <activity
             android:name=".activities.editor.EditorActivityKt"
             android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|fontScale"

app/src/main/java/com/itsaky/androidide/activities/DeepLinkActivity.kt

@@ -0,0 +1,84 @@
+/*
+ *  This file is part of AndroidIDE.
+ *
+ *  AndroidIDE is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  AndroidIDE is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *   along with AndroidIDE.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.itsaky.androidide.activities
+
+import android.app.Activity
+import android.content.Intent
+import android.os.Bundle
+import android.widget.Toast
+import com.itsaky.androidide.activities.editor.EditorActivityKt
+import com.itsaky.androidide.api.ActionContextProvider
+import com.itsaky.androidide.models.DeepLinkRequest
+import com.itsaky.androidide.resources.R.string
+
+/**
+ * The sole `<intent-filter>` holder for `https://www.appdevforall.org/device/open/project/...` App
+ * Links. Never shows any UI -- it only parses the incoming [android.net.Uri], decides whether a
+ * project is already loaded, and hands off to whichever real activity owns that scenario:
+ * [MainActivity] if nothing is open yet, or the already-running [EditorActivityKt] (via its
+ * `singleTask` `onNewIntent`) if one is.
+ *
+ * Kept as a plain [Activity] (like [SplashActivity]), not [com.itsaky.androidide.app.BaseIDEActivity],
+ * since it never calls `setContentView` and has no theming needs of its own.
+ */
+class DeepLinkActivity : Activity() {
+	override fun onCreate(savedInstanceState: Bundle?) {
+		super.onCreate(savedInstanceState)
+
+		val request = DeepLinkRequest.parse(intent?.data)
+		if (request == null) {
+			// A Toast, not flashError -- this activity finishes immediately below, tearing down its
+			// window before a view-based Flashbar could ever render.
+			Toast.makeText(this, getString(string.msg_deeplink_invalid_link), Toast.LENGTH_LONG).show()
+			finish()
+			return
+		}
+
+		// ActionContextProvider tracks the live EditorHandlerActivity instance (set in its onCreate
+		// and re-asserted in onResume, cleared in onDestroy) -- this reflects "is an editor instance
+		// already alive to hand this off to via onNewIntent", unlike IProjectManager's workspace,
+		// which stays null for the whole duration of a Gradle sync even while EditorActivityKt is
+		// already open.
+		val target =
+			if (ActionContextProvider.getActivity() != null) {
+				EditorActivityKt::class.java
+			} else {
+				MainActivity::class.java
+			}
+
+		startActivity(
+			Intent(this, target).apply {
+				putExtra(DeepLinkRequest.EXTRA_KEY, request)
+				// If `target` is MainActivity and one already exists in the task, reuse it via
+				// onNewIntent instead of stacking a second instance -- SINGLE_TOP alone isn't enough
+				// here, since DeepLinkActivity (not MainActivity) is what's actually on top of the
+				// stack at this exact call, so SINGLE_TOP's "already at the top" check never matches;
+				// CLEAR_TOP finds MainActivity anywhere in the task and reuses it via onNewIntent
+				// (combined with SINGLE_TOP, rather than the destroy-and-recreate CLEAR_TOP alone
+				// would do). EditorActivityKt is singleTask, so it always reuses its live instance
+				// regardless of these flags.
+				addFlags(
+					Intent.FLAG_ACTIVITY_NEW_TASK or
+						Intent.FLAG_ACTIVITY_SINGLE_TOP or
+						Intent.FLAG_ACTIVITY_CLEAR_TOP,
+				)
+			},
+		)
+		finish()
+	}
+}