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

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://appdevforall.org/device/open/project/...` (and the identical `www` subdomain). 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`, `ProjectInfoBottomSheet`, and `ProjectCreationManager` directly, and by `MainActivity`/`EditorHandlerActivity` indirectly through `RecentProjectRepository` (`repositories/RecentProjectRepository.kt`) -- kept behind that interface, rather than injecting the DAO into those two Activities directly, per this section's own UI -> ViewModel -> Repository -> data source layering.
 >
 > **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

@@ -91,11 +91,37 @@
             android:name=".activities.OnboardingActivity"
             android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize"
             android:exported="false" />
+        <!--
+            Not exported: this activity has no intent-filter, so nothing outside the app ever needs
+            to launch it, and DeepLinkActivity (same app) still can. Exported, any co-installed app
+            could send it a forged DEEP_LINK_REQUEST extra directly, skipping DeepLinkActivity's URI
+            validation, to force an arbitrary project open and navigate to a file inside it.
+        -->
         <activity
             android:name=".activities.MainActivity"
             android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize"
-            android:exported="true"
+            android:exported="false"
             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/" />
+                <data
+                    android:scheme="https"
+                    android:host="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,101 @@
+/*
+ *  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://appdevforall.org/device/open/project/...` (and the
+ * identical `www` subdomain) 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)
+
+		// A link can arrive before the IDE is usable -- a fresh install, or a Clear Data. Both targets
+		// below sit *past* SplashActivity and OnboardingActivity, which are the only things enforcing
+		// the terms, the permissions, the JDK and SDK install, the low-storage check and the x86
+		// exit, so following the link now would land the user in an editor that cannot build, on a
+		// device the app is supposed to refuse to run on at all (ADFA-5067 review).
+		//
+		// The link is dropped rather than deferred: carrying a request through an onboarding that can
+		// take several minutes, and may not finish at all, is a lot of machinery for a rare case. The
+		// user is told, and sent to the normal entry point, which decides what they actually need --
+		// storage, ABI and onboarding are SplashActivity's to enforce, not this activity's to repeat.
+		if (!isIdeSetupComplete()) {
+			Toast.makeText(this, getString(string.msg_deeplink_setup_incomplete), Toast.LENGTH_LONG).show()
+			startActivity(Intent(this, SplashActivity::class.java))
+			finish()
+			return
+		}
+
+		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)
+				// FLAG_ACTIVITY_CLEAR_TOP deliberately omitted: MainActivity has no special launch
+				// mode, so if an existing MainActivity instance sits lower in this task's back stack
+				// under a live EditorActivityKt - which ActionContextProvider.getActivity() can miss
+				// even when that editor is alive (see its KDoc) - CLEAR_TOP would destroy that editor
+				// to clear the path down to MainActivity, discarding unsaved work with no prompt.
+				// Without it, this may at worst stack a redundant MainActivity instance, a harmless
+				// nuisance; EditorActivityKt is singleTask, so it always reuses its live instance via
+				// onNewIntent regardless of these flags.
+				addFlags(
+					Intent.FLAG_ACTIVITY_NEW_TASK or
+						Intent.FLAG_ACTIVITY_SINGLE_TOP,
+				)
+			},
+		)
+		finish()
+	}
+}