@dailephd/my-dev-kit-lab 0.3.4 → 0.4.1

package/dist/src/mobile/android/gradle/readAndroidGradleMetadata.js

@@ -0,0 +1,210 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../core/pathSafety.js";
+import { extractVersionCatalogEvidence } from "../detect/versionCatalogEvidence.js";
+import { parseWrapperProperties } from "./wrapperMetadata.js";
+import { parseVersionCatalog } from "./versionCatalogMetadata.js";
+import { extractModuleGradleMetadata } from "./moduleMetadataExtractor.js";
+import { resolvePluginVersion } from "./pluginVersionExtractor.js";
+import { parseSettingsMetadata } from "./settingsMetadata.js";
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 4 — static Android Gradle metadata extraction entry point.
+//
+// Static, deterministic, read-only, network-free, and independent of Gradle
+// execution/Java/Android SDK availability — consumes only the Batch 2
+// AndroidDetectionResult (settings/build/wrapper/catalog file paths and
+// module records) plus direct filesystem reads of those same files.
+// ---------------------------------------------------------------------------
+function readTextSafe(absolutePath) {
+    try {
+        return readFileSync(absolutePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+const ANDROID_APPLICATION_PLUGIN_ID = "com.android.application";
+const ANDROID_LIBRARY_PLUGIN_ID = "com.android.library";
+const KOTLIN_ANDROID_PLUGIN_ID = "org.jetbrains.kotlin.android";
+const AGP_CLASSPATH_GROUP_ARTIFACT = "com.android.tools.build:gradle";
+export function readAndroidGradleMetadata(targetRoot, detection) {
+    const resolvedRoot = path.resolve(targetRoot);
+    const parseWarnings = [];
+    const unsupportedExpressions = [];
+    // ---- Wrapper ---------------------------------------------------------------
+    const wrapperPropertiesPath = "gradle/wrapper/gradle-wrapper.properties";
+    let wrapperPropertiesExists = false;
+    try {
+        resolveWithinRoot(resolvedRoot, wrapperPropertiesPath);
+        wrapperPropertiesExists = true;
+    }
+    catch {
+        wrapperPropertiesExists = false;
+    }
+    const wrapperText = wrapperPropertiesExists ? readTextSafe(path.join(resolvedRoot, wrapperPropertiesPath)) : undefined;
+    const gradlewPresent = readTextSafe(path.join(resolvedRoot, "gradlew")) !== undefined;
+    const gradlewBatPresent = readTextSafe(path.join(resolvedRoot, "gradlew.bat")) !== undefined;
+    const wrapperWarnings = [];
+    let wrapper;
+    if (wrapperText !== undefined) {
+        const parsed = parseWrapperProperties(wrapperText);
+        wrapperWarnings.push(...parsed.warnings);
+        if (!gradlewPresent && !gradlewBatPresent) {
+            wrapperWarnings.push("gradle-wrapper.properties exists but neither gradlew nor gradlew.bat was found.");
+        }
+        wrapper = {
+            present: detection.hasGradleWrapper,
+            wrapperPropertiesPath,
+            versionEvidence: parsed.gradleVersion,
+            distributionUrl: parsed.distributionUrl,
+            distributionType: parsed.distributionType,
+            checksumPropertyPresent: parsed.checksumPropertyPresent,
+            gradlewPresent,
+            gradlewBatPresent,
+            warnings: wrapperWarnings,
+        };
+    }
+    else {
+        if (gradlewPresent || gradlewBatPresent) {
+            wrapperWarnings.push("gradlew/gradlew.bat found but gradle-wrapper.properties is missing or unreadable.");
+        }
+        wrapper = {
+            present: detection.hasGradleWrapper,
+            gradlewPresent,
+            gradlewBatPresent,
+            warnings: wrapperWarnings,
+        };
+    }
+    parseWarnings.push(...wrapperWarnings);
+    // ---- Settings ---------------------------------------------------------------
+    let rootProjectName;
+    for (const settingsPath of detection.gradleSettingsFiles) {
+        const text = readTextSafe(path.join(resolvedRoot, settingsPath));
+        if (!text)
+            continue;
+        const parsed = parseSettingsMetadata(text);
+        if (parsed.rootProjectName && !rootProjectName)
+            rootProjectName = parsed.rootProjectName;
+        if (parsed.includedBuilds.length > 0) {
+            parseWarnings.push(`${settingsPath}: included build(s) present as unsupported/external evidence: ${parsed.includedBuilds.join(", ")}`);
+        }
+    }
+    // ---- Version catalog ---------------------------------------------------------
+    let versionCatalogEvidence;
+    let parsedCatalog;
+    if (detection.versionCatalogFiles.length > 0) {
+        const catalogText = readTextSafe(path.join(resolvedRoot, detection.versionCatalogFiles[0]));
+        if (catalogText) {
+            versionCatalogEvidence = extractVersionCatalogEvidence(catalogText);
+            parsedCatalog = parseVersionCatalog(catalogText);
+        }
+    }
+    // ---- Root build files: plugin/AGP/Kotlin version evidence --------------------
+    const pluginEvidence = {};
+    for (const rootBuildFilePath of detection.rootBuildFiles) {
+        const text = readTextSafe(path.join(resolvedRoot, rootBuildFilePath));
+        if (!text)
+            continue;
+        const hasDirectAgpTextEvidence = text.includes(ANDROID_APPLICATION_PLUGIN_ID) || text.includes(ANDROID_LIBRARY_PLUGIN_ID);
+        if (!pluginEvidence.androidGradlePluginVersion) {
+            const agpVersion = resolvePluginVersion(text, ANDROID_APPLICATION_PLUGIN_ID, parsedCatalog, AGP_CLASSPATH_GROUP_ARTIFACT);
+            if (agpVersion.version)
+                pluginEvidence.androidGradlePluginVersion = agpVersion.version;
+        }
+        if (!pluginEvidence.androidGradlePluginEvidence && (hasDirectAgpTextEvidence || pluginEvidence.androidGradlePluginVersion)) {
+            pluginEvidence.androidGradlePluginEvidence = hasDirectAgpTextEvidence
+                ? `Android Gradle Plugin referenced in ${rootBuildFilePath}`
+                : `Android Gradle Plugin referenced via version-catalog alias in ${rootBuildFilePath}`;
+        }
+        const hasDirectKotlinTextEvidence = text.includes(KOTLIN_ANDROID_PLUGIN_ID);
+        if (!pluginEvidence.kotlinAndroidPluginVersion) {
+            const kotlinVersion = resolvePluginVersion(text, KOTLIN_ANDROID_PLUGIN_ID, parsedCatalog);
+            if (kotlinVersion.version)
+                pluginEvidence.kotlinAndroidPluginVersion = kotlinVersion.version;
+        }
+        if (!pluginEvidence.kotlinAndroidPluginEvidence && (hasDirectKotlinTextEvidence || pluginEvidence.kotlinAndroidPluginVersion)) {
+            pluginEvidence.kotlinAndroidPluginEvidence = hasDirectKotlinTextEvidence
+                ? `Kotlin Android plugin referenced in ${rootBuildFilePath}`
+                : `Kotlin Android plugin referenced via version-catalog alias in ${rootBuildFilePath}`;
+        }
+    }
+    if (versionCatalogEvidence && versionCatalogEvidence.composeAliasEvidence.length > 0) {
+        pluginEvidence.composePluginEvidence = `Version-catalog Compose alias(es): ${versionCatalogEvidence.composeAliasEvidence.join(", ")}`;
+    }
+    if (!pluginEvidence.androidGradlePluginVersion && pluginEvidence.androidGradlePluginEvidence) {
+        unsupportedExpressions.push("Android Gradle Plugin version could not be statically resolved.");
+    }
+    // ---- Modules ------------------------------------------------------------------
+    const moduleBuildFiles = [];
+    const modules = [];
+    const applicationIdsByModule = [];
+    for (const module of detection.modules) {
+        const buildFileCandidates = [`${module.path}/build.gradle.kts`, `${module.path}/build.gradle`];
+        const buildFileRelPath = buildFileCandidates.find((candidate) => readTextSafe(path.join(resolvedRoot, candidate)) !== undefined);
+        if (!buildFileRelPath) {
+            modules.push({
+                path: module.path,
+                buildTypes: [],
+                sourceSetEvidence: [],
+                testSourceSetEvidence: [],
+                unsupportedExpressions: [],
+            });
+            continue;
+        }
+        moduleBuildFiles.push(buildFileRelPath);
+        const text = readTextSafe(path.join(resolvedRoot, buildFileRelPath)) ?? "";
+        const extracted = extractModuleGradleMetadata(text);
+        const javaSourceRoots = detection.javaSourceRoots.filter((p) => p.startsWith(`${module.path}/`));
+        const kotlinSourceRoots = detection.kotlinSourceRoots.filter((p) => p.startsWith(`${module.path}/`));
+        const unitTestRoots = detection.unitTestSourceRoots.filter((p) => p.startsWith(`${module.path}/`));
+        const instrumentedTestRoots = detection.instrumentedTestSourceRoots.filter((p) => p.startsWith(`${module.path}/`));
+        modules.push({
+            path: module.path,
+            buildFilePath: buildFileRelPath,
+            ...extracted.info,
+            sourceSetEvidence: [...extracted.info.sourceSetEvidence, ...javaSourceRoots, ...kotlinSourceRoots].sort((a, b) => a.localeCompare(b)),
+            testSourceSetEvidence: [...unitTestRoots, ...instrumentedTestRoots].sort((a, b) => a.localeCompare(b)),
+        });
+        if (extracted.info.applicationId) {
+            applicationIdsByModule.push({ modulePath: module.path, value: extracted.info.applicationId, sourceFile: buildFileRelPath });
+        }
+        unsupportedExpressions.push(...extracted.info.unsupportedExpressions.map((e) => `${buildFileRelPath}: ${e}`));
+    }
+    // ---- Conflicts ------------------------------------------------------------------
+    const conflicts = [];
+    const applicationModulePaths = new Set(detection.applicationModules);
+    const applicationIdConflictEntries = applicationIdsByModule.filter((e) => applicationModulePaths.has(e.modulePath));
+    const distinctApplicationModuleIds = new Set(applicationIdConflictEntries.map((e) => e.value));
+    if (distinctApplicationModuleIds.size > 1) {
+        conflicts.push({
+            field: "applicationId",
+            modulePath: [...applicationModulePaths].sort((a, b) => a.localeCompare(b)).join(", "),
+            values: applicationIdConflictEntries.map((e) => ({ value: e.value, sourceFile: e.sourceFile })),
+            note: `${distinctApplicationModuleIds.size} distinct applicationId values found across application modules; no primary value was selected.`,
+        });
+    }
+    // ---- Confidence ------------------------------------------------------------------
+    const hasAnyResolvedModuleMetadata = modules.some((m) => m.namespace || m.applicationId || m.minSdk || m.targetSdk || m.compileSdk);
+    const hasUnresolvedEvidence = unsupportedExpressions.length > 0 || conflicts.length > 0;
+    let metadataConfidence = "unknown";
+    if (hasAnyResolvedModuleMetadata) {
+        metadataConfidence = hasUnresolvedEvidence ? "medium" : "high";
+    }
+    else if (moduleBuildFiles.length > 0) {
+        metadataConfidence = "low";
+    }
+    return {
+        wrapper,
+        settingsFiles: detection.gradleSettingsFiles,
+        rootBuildFiles: detection.rootBuildFiles,
+        moduleBuildFiles: moduleBuildFiles.sort((a, b) => a.localeCompare(b)),
+        rootProjectName,
+        pluginEvidence,
+        modules: modules.sort((a, b) => a.path.localeCompare(b.path)),
+        versionCatalogEvidence,
+        conflicts: conflicts.length > 0 ? conflicts : undefined,
+        metadataConfidence,
+        parseWarnings: [...new Set(parseWarnings)],
+        unsupportedExpressions: [...new Set(unsupportedExpressions)].sort((a, b) => a.localeCompare(b)),
+    };
+}

package/dist/src/mobile/android/gradle/releaseMetadataSummary.js

@@ -0,0 +1,64 @@
+// Selects the application module deterministically only when exactly one
+// application module exists (agents.txt Batch 4 section 7.14 — never invent
+// a primary application module when several exist without a deterministic
+// rule).
+export function buildAndroidReleaseMetadataSummary(detection, gradle) {
+    const applicationModulePaths = detection.applicationModules;
+    const unresolvedFields = [];
+    if (applicationModulePaths.length === 0) {
+        return {
+            applicationModuleSelectionNote: "No application module was detected; release metadata is not available.",
+            buildTypes: [],
+            wrapperGradleVersion: gradle.wrapper.versionEvidence,
+            androidGradlePluginVersion: gradle.pluginEvidence.androidGradlePluginVersion,
+            kotlinAndroidPluginVersion: gradle.pluginEvidence.kotlinAndroidPluginVersion,
+            metadataConfidence: gradle.metadataConfidence,
+            unresolvedFields: [],
+            conflicts: gradle.conflicts ?? [],
+        };
+    }
+    if (applicationModulePaths.length > 1) {
+        return {
+            applicationModuleSelectionNote: `${applicationModulePaths.length} application modules were detected (${applicationModulePaths.join(", ")}); no single application module was selected deterministically.`,
+            buildTypes: [],
+            wrapperGradleVersion: gradle.wrapper.versionEvidence,
+            androidGradlePluginVersion: gradle.pluginEvidence.androidGradlePluginVersion,
+            kotlinAndroidPluginVersion: gradle.pluginEvidence.kotlinAndroidPluginVersion,
+            metadataConfidence: gradle.metadataConfidence,
+            unresolvedFields: [],
+            conflicts: gradle.conflicts ?? [],
+        };
+    }
+    const applicationModulePath = applicationModulePaths[0];
+    const moduleInfo = gradle.modules.find((m) => m.path === applicationModulePath);
+    for (const [field, value] of [
+        ["applicationId", moduleInfo?.applicationIdRaw],
+        ["versionCode", moduleInfo?.versionCodeRaw],
+        ["versionName", moduleInfo?.versionNameRaw],
+        ["minSdk", moduleInfo?.minSdkRaw],
+        ["targetSdk", moduleInfo?.targetSdkRaw],
+        ["compileSdk", moduleInfo?.compileSdkRaw],
+    ]) {
+        if (value)
+            unresolvedFields.push(`${field}: ${value}`);
+    }
+    return {
+        applicationModulePath,
+        applicationModuleSelectionNote: `Exactly one application module was detected (${applicationModulePath}); its metadata is used as the release metadata summary.`,
+        applicationId: moduleInfo?.applicationId,
+        namespace: moduleInfo?.namespace,
+        versionCode: moduleInfo?.versionCode,
+        versionName: moduleInfo?.versionName,
+        minSdk: moduleInfo?.minSdk,
+        targetSdk: moduleInfo?.targetSdk,
+        compileSdk: moduleInfo?.compileSdk,
+        buildTypes: moduleInfo?.buildTypes ?? [],
+        wrapperGradleVersion: gradle.wrapper.versionEvidence,
+        androidGradlePluginVersion: gradle.pluginEvidence.androidGradlePluginVersion,
+        kotlinAndroidPluginVersion: gradle.pluginEvidence.kotlinAndroidPluginVersion,
+        composeEnabled: moduleInfo?.composeEnabled,
+        metadataConfidence: gradle.metadataConfidence,
+        unresolvedFields,
+        conflicts: gradle.conflicts ?? [],
+    };
+}

package/dist/src/mobile/android/gradle/settingsMetadata.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 4 — bounded settings.gradle(.kts) metadata beyond Batch 2's
+// module-include parsing.
+//
+// Only extracts a direct `rootProject.name = "..."` / `rootProject.name "..."`
+// literal and detects included-build/plugin-management/dependency-resolution
+// presence as evidence — never evaluates the referenced build's contents.
+// ---------------------------------------------------------------------------
+const ROOT_PROJECT_NAME_PATTERN = /rootProject\.name\s*=?\s*['"]([^'"]+)['"]/;
+export function parseSettingsMetadata(text) {
+    const rootProjectName = text.match(ROOT_PROJECT_NAME_PATTERN)?.[1];
+    const includedBuilds = [...text.matchAll(/includeBuild\(\s*['"]([^'"]+)['"]\s*\)/g)].map((m) => m[1]);
+    return {
+        rootProjectName,
+        hasPluginManagement: /\bpluginManagement\s*\{/.test(text),
+        hasDependencyResolutionManagement: /\bdependencyResolutionManagement\s*\{/.test(text),
+        hasVersionCatalogDeclaration: /\bversionCatalogs\s*\{/.test(text) || /\bcreate\(\s*['"]libs['"]/.test(text),
+        includedBuilds: includedBuilds.sort((a, b) => a.localeCompare(b)),
+    };
+}

package/dist/src/mobile/android/gradle/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/mobile/android/gradle/validate/executor.js

@@ -0,0 +1,9 @@
+import { runSecurityCommand } from "../../../../securityValidation/commandRunner.js";
+export function createRealGradleCommandExecutor() {
+    return (plan) => runSecurityCommand({
+        command: plan.wrapperExecutablePath,
+        args: plan.args,
+        cwd: plan.cwd,
+        timeoutMs: plan.timeoutMs,
+    });
+}

package/dist/src/mobile/android/gradle/validate/operationCheckResult.js

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 4 — per-operation Gradle validation check-result construction
+// (agents.txt Batch 4 section 7.26).
+//
+// Status semantics differ slightly by operation:
+//   - wrapper-version: nonzero/spawn-failure -> "error" (this is the
+//     simplest possible invocation; a failure here is an orchestration
+//     problem, not a build/environment nuance).
+//   - tasks: nonzero/spawn-failure -> "inconclusive" (configuration or
+//     environment prevented task discovery, not a security-relevant
+//     failure).
+//   - assemble-debug / unit-test-debug / lint-debug: spawn-failure ->
+//     "inconclusive" (environment incomplete); nonzero exit with a real
+//     process result -> "failed" (a genuine build/test/lint failure is
+//     validation evidence, never a fabricated SecurityFinding — section
+//     7.27).
+// A timed-out operation is always "inconclusive", never "passed" or
+// silently "error" (section 7.22).
+// ---------------------------------------------------------------------------
+const MAX_OUTPUT_SUMMARY_LENGTH = 4000;
+function boundedSummary(text) {
+    if (text.length <= MAX_OUTPUT_SUMMARY_LENGTH)
+        return { summary: text, truncated: false };
+    return { summary: text.slice(0, MAX_OUTPUT_SUMMARY_LENGTH), truncated: true };
+}
+function statusForResult(operationId, result) {
+    if (result.timedOut)
+        return "inconclusive";
+    if (result.exitCode === null) {
+        return operationId === "wrapper-version" ? "error" : "inconclusive";
+    }
+    if (result.exitCode === 0)
+        return "passed";
+    if (operationId === "wrapper-version")
+        return "error";
+    if (operationId === "tasks")
+        return "inconclusive";
+    return "failed";
+}
+function confidenceForStatus(status) {
+    switch (status) {
+        case "passed":
+        case "failed":
+            return "high";
+        case "inconclusive":
+            return "medium";
+        default:
+            return "unknown";
+    }
+}
+export function buildGradleOperationCheckResult(plan, result, mutation) {
+    const status = statusForResult(plan.operationId, result);
+    const confidence = confidenceForStatus(status);
+    const stdoutBound = boundedSummary(result.stdout);
+    const stderrBound = boundedSummary(result.stderr);
+    const warnings = [];
+    if (result.timedOut)
+        warnings.push(`Operation timed out after ${plan.timeoutMs}ms.`);
+    if (result.exitCode === null && !result.timedOut)
+        warnings.push("Command could not be spawned or resolved (see stderr evidence).");
+    if (stdoutBound.truncated)
+        warnings.push("stdout was truncated for this result.");
+    if (stderrBound.truncated)
+        warnings.push("stderr was truncated for this result.");
+    if (!mutation.comparable)
+        warnings.push(`Target mutation evidence unavailable: ${mutation.reason ?? "unknown reason"}`);
+    if (mutation.unexpectedChanges.length > 0) {
+        warnings.push(`Unexpected target change(s) observed after this operation: ${mutation.unexpectedChanges.join(", ")}`);
+    }
+    const boundedCommand = {
+        ...result,
+        stdout: stdoutBound.summary,
+        stderr: stderrBound.summary,
+    };
+    return {
+        id: `android-gradle-${plan.operationId}`,
+        category: "android-gradle",
+        title: `Gradle operation: ${plan.operationId}`,
+        status,
+        requirementLevel: "optional",
+        ran: true,
+        skipped: false,
+        evidence: [
+            `exitCode=${result.exitCode ?? "null"}`,
+            `durationMs=${result.durationMs}`,
+            `expectedGeneratedPaths=${plan.expectedGeneratedPaths.join(",") || "(none)"}`,
+            ...mutation.expectedGeneratedChanges.map((p) => `generatedOutput=${p}`),
+        ],
+        findings: [],
+        warnings,
+        errors: result.exitCode === null && !result.timedOut ? [stderrBound.summary || "Command could not be spawned or resolved."] : [],
+        durationMs: result.durationMs,
+        command: boundedCommand,
+        sourcePaths: [plan.wrapperExecutablePath],
+        confidence,
+        environmentRequirements: plan.environmentLimitations,
+        targetModificationObserved: mutation.comparable ? mutation.unexpectedChanges.length > 0 : undefined,
+    };
+}

package/dist/src/mobile/android/gradle/validate/operations.js

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 4 — allowlisted optional Gradle validation operations
+// (agents.txt Batch 4 section 7.17).
+//
+// This is the ONLY place operation-to-argument mappings are defined. The
+// planner (planner.ts) rejects any operation id not in ALLOWLISTED_OPERATION_IDS
+// before a command is ever constructed — arbitrary task strings are never
+// accepted from a caller.
+// ---------------------------------------------------------------------------
+export const ALLOWLISTED_OPERATION_IDS = ["wrapper-version", "tasks", "assemble-debug", "unit-test-debug", "lint-debug"];
+export function isAllowlistedOperationId(value) {
+    return ALLOWLISTED_OPERATION_IDS.includes(value);
+}
+// Conservative, bounded timeouts (agents.txt section 7.22). No retries, no
+// unbounded execution — a timed-out operation is terminated and reported
+// inconclusive/error, never passed.
+const SHORT_TIMEOUT_MS = 30_000;
+const MODERATE_TIMEOUT_MS = 120_000;
+const LONG_TIMEOUT_MS = 600_000;
+// Safety flags applied to every operation: --no-daemon avoids leaving a
+// background Gradle daemon running after this process exits, --console=plain
+// keeps output parseable, and --offline prevents this batch from
+// intentionally triggering network access (agents.txt section 7.18) — the
+// tradeoff is that operations needing uncached dependencies will fail or
+// report inconclusive rather than silently downloading them.
+const SAFETY_FLAGS = ["--no-daemon", "--console=plain"];
+const OFFLINE_SAFETY_FLAGS = [...SAFETY_FLAGS, "--offline"];
+export const GRADLE_OPERATIONS = {
+    "wrapper-version": {
+        id: "wrapper-version",
+        args: ["--version"],
+        timeoutMs: SHORT_TIMEOUT_MS,
+        mayCreateBuildOutputs: true, // Gradle creates/updates .gradle/ on first invocation.
+        description: "Reports the Gradle version the wrapper would use, without building anything.",
+    },
+    tasks: {
+        id: "tasks",
+        gradleTaskName: "tasks",
+        args: ["tasks", "--all", ...OFFLINE_SAFETY_FLAGS],
+        timeoutMs: MODERATE_TIMEOUT_MS,
+        mayCreateBuildOutputs: true,
+        description: "Lists available Gradle tasks so later operations can be skipped safely when unavailable.",
+    },
+    "assemble-debug": {
+        id: "assemble-debug",
+        gradleTaskName: "assembleDebug",
+        args: ["assembleDebug", ...OFFLINE_SAFETY_FLAGS],
+        timeoutMs: LONG_TIMEOUT_MS,
+        mayCreateBuildOutputs: true,
+        description: "Assembles the debug variant (no signing, no release build, no publishing).",
+    },
+    "unit-test-debug": {
+        id: "unit-test-debug",
+        gradleTaskName: "testDebugUnitTest",
+        args: ["testDebugUnitTest", ...OFFLINE_SAFETY_FLAGS],
+        timeoutMs: LONG_TIMEOUT_MS,
+        mayCreateBuildOutputs: true,
+        description: "Runs local (non-instrumented) debug unit tests.",
+    },
+    "lint-debug": {
+        id: "lint-debug",
+        gradleTaskName: "lintDebug",
+        args: ["lintDebug", ...OFFLINE_SAFETY_FLAGS],
+        timeoutMs: LONG_TIMEOUT_MS,
+        mayCreateBuildOutputs: true,
+        description: "Runs Android Lint for the debug variant. Lint output is not parsed into security findings in this batch.",
+    },
+};

package/dist/src/mobile/android/gradle/validate/planner.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveWithinRoot } from "../../../../core/pathSafety.js";
+import { GRADLE_OPERATIONS, isAllowlistedOperationId } from "./operations.js";
+function wrapperScriptNameForPlatform(platform) {
+    return platform === "win32" ? "gradlew.bat" : "gradlew";
+}
+export function buildGradleCommandPlan(operationId, targetRoot, detection, platform = process.platform) {
+    if (!isAllowlistedOperationId(operationId)) {
+        return { rejected: true, reason: `Unknown or unsupported Gradle operation id: "${operationId}". Only allowlisted operations may be planned.` };
+    }
+    const resolvedRoot = path.resolve(targetRoot);
+    const wrapperScriptName = wrapperScriptNameForPlatform(platform);
+    let wrapperExecutablePath;
+    try {
+        wrapperExecutablePath = resolveWithinRoot(resolvedRoot, wrapperScriptName);
+    }
+    catch {
+        return { rejected: true, reason: `Wrapper path escapes the target root: ${wrapperScriptName}` };
+    }
+    if (!fs.existsSync(wrapperExecutablePath)) {
+        return {
+            rejected: true,
+            reason: `No ${wrapperScriptName} was found at the target root. Optional Gradle validation requires a Gradle wrapper checked into the target for this platform.`,
+        };
+    }
+    const definition = GRADLE_OPERATIONS[operationId];
+    const expectedGeneratedPaths = definition.mayCreateBuildOutputs
+        ? [".gradle/", "build/", ...detection.modules.map((m) => `${m.path}/build/`)]
+        : [];
+    const environmentLimitations = [
+        "Requires a local or downloadable Gradle distribution matching the wrapper version — this planner does not verify one is available.",
+        "Requires a Java runtime on PATH — this planner does not verify Java availability.",
+    ];
+    if (definition.args.includes("--offline")) {
+        environmentLimitations.push("Runs with --offline; tasks needing uncached dependencies will fail or report inconclusive rather than downloading them.");
+    }
+    return {
+        rejected: false,
+        operationId,
+        wrapperExecutablePath,
+        args: definition.args,
+        cwd: resolvedRoot,
+        timeoutMs: definition.timeoutMs,
+        mayCreateBuildOutputs: definition.mayCreateBuildOutputs,
+        expectedGeneratedPaths,
+        environmentLimitations,
+    };
+}

package/dist/src/mobile/android/gradle/validate/runOptionalGradleValidation.js

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+import { GRADLE_OPERATIONS } from "./operations.js";
+import { buildGradleCommandPlan } from "./planner.js";
+import { createRealGradleCommandExecutor } from "./executor.js";
+import { buildGradleOperationCheckResult } from "./operationCheckResult.js";
+import { buildTargetMutationReport, captureTargetSnapshot } from "./targetMutation.js";
+import { isGradleTaskAvailable, parseGradleTaskNames } from "./taskListParser.js";
+// ---------------------------------------------------------------------------
+// v0.4.0 Batch 4 — optional Gradle validation orchestrator (agents.txt Batch
+// 4 sections 7.17, 7.20, 7.24, 7.26).
+//
+// Static metadata collection (readAndroidGradleMetadata.ts) never calls this
+// module. This orchestrator only ever runs a Gradle command when
+// `enabled: true` is passed explicitly — every other code path returns a
+// "not-run" result without touching the filesystem beyond a target
+// git-status snapshot. Task-gated operations (assemble/test/lint) are
+// skipped, not attempted, unless task availability was already discovered
+// via the "tasks" operation earlier in the same call (or the caller opts in
+// via allowWithoutTaskDiscovery).
+// ---------------------------------------------------------------------------
+const TASK_GATED_OPERATIONS = new Set(["assemble-debug", "unit-test-debug", "lint-debug"]);
+function notRunResult(operationId) {
+    return {
+        id: `android-gradle-${operationId}`,
+        category: "android-gradle",
+        title: `Gradle operation: ${operationId}`,
+        status: "not-run",
+        requirementLevel: "optional",
+        ran: false,
+        skipped: false,
+        evidence: [],
+        findings: [],
+        warnings: [],
+        errors: [],
+        sourcePaths: [],
+        confidence: "unknown",
+        environmentRequirements: [],
+    };
+}
+function skippedResult(operationId, reason, missingCapability) {
+    return {
+        id: `android-gradle-${operationId}`,
+        category: "android-gradle",
+        title: `Gradle operation: ${operationId}`,
+        status: "skipped",
+        requirementLevel: "optional",
+        ran: false,
+        skipped: true,
+        skipInfo: {
+            checkId: `android-gradle-${operationId}`,
+            reason,
+            requirementLevel: "optional",
+            missingCapability,
+            verdictImpact: "optional Gradle validation evidence is unavailable for this operation",
+            recommendedNextAction: "Re-run with the required precondition satisfied, or accept reduced evidence.",
+        },
+        evidence: [],
+        findings: [],
+        warnings: [],
+        errors: [],
+        sourcePaths: [],
+        confidence: "unknown",
+        environmentRequirements: [],
+    };
+}
+function hasGitDirectory(targetRoot) {
+    try {
+        return fs.existsSync(path.join(targetRoot, ".git"));
+    }
+    catch {
+        return false;
+    }
+}
+export async function runOptionalGradleValidation(options) {
+    if (!options.enabled) {
+        return options.operationIds.map((id) => notRunResult(id));
+    }
+    const executor = options.executor ?? createRealGradleCommandExecutor();
+    const platform = options.platform ?? process.platform;
+    const resolvedRoot = path.resolve(options.targetRoot);
+    const hasGit = hasGitDirectory(resolvedRoot);
+    let discoveredTaskNames;
+    const results = [];
+    for (const operationId of options.operationIds) {
+        if (TASK_GATED_OPERATIONS.has(operationId)) {
+            if (!discoveredTaskNames && !options.allowWithoutTaskDiscovery) {
+                results.push(skippedResult(operationId, "Task availability was not discovered (the 'tasks' operation did not run successfully first) and allowWithoutTaskDiscovery was not set.", "gradle-task-discovery"));
+                continue;
+            }
+            const gradleTaskName = GRADLE_OPERATIONS[operationId].gradleTaskName;
+            if (discoveredTaskNames && !isGradleTaskAvailable(discoveredTaskNames, gradleTaskName)) {
+                results.push(skippedResult(operationId, `Task "${gradleTaskName}" is not available in this project.`, "gradle-task"));
+                continue;
+            }
+        }
+        const plan = buildGradleCommandPlan(operationId, resolvedRoot, options.detection, platform);
+        if (plan.rejected) {
+            results.push(skippedResult(operationId, plan.reason, "gradle-wrapper"));
+            continue;
+        }
+        const before = captureTargetSnapshot(resolvedRoot, hasGit);
+        const commandResult = await executor(plan);
+        const after = captureTargetSnapshot(resolvedRoot, hasGit);
+        const mutation = buildTargetMutationReport(before, after);
+        const checkResult = buildGradleOperationCheckResult(plan, commandResult, mutation);
+        results.push(checkResult);
+        if (operationId === "tasks" && checkResult.status === "passed") {
+            discoveredTaskNames = parseGradleTaskNames(commandResult.stdout);
+        }
+    }
+    return results;
+}