replicant-mcp 1.4.7 → 1.5.0

package/dist/services/process-runner.js

@@ -7,6 +7,20 @@ const BLOCKED_PATTERNS = [
     /^sudo(\s|$)/, // sudo
     /\bformat\b/, // format commands
 ];
+const BLOCKED_SHELL_PATTERNS = [
+    /^rm\s+(-[rf]+\s+)*\/\s*$/, // rm -rf / (root itself)
+    /^rm\s+(-[rf]+\s+)*\/(system|vendor|oem|product)(\/|\s|$)/, // rm on system partitions
+    /^su(\s|$)/, // su
+    /^sudo(\s|$)/, // sudo
+    /\bformat\b/, // format commands
+    /^setprop\s+persist\./, // persistent property changes
+    /^dd\s/, // raw disk operations
+    /^mkfs/, // filesystem creation
+    /^flash/, // flash operations
+    /^wipe/, // wipe data/cache
+    /^recovery\b/, // recovery mode
+    /^reboot\b/, // reboot device (also in BLOCKED_COMMANDS)
+];
 export class ProcessRunner {
     environment;
     defaultTimeoutMs = 30_000;
@@ -74,5 +88,42 @@ export class ProcessRunner {
                 throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Command '${fullCommand}' is not allowed`, "Use safe commands only");
             }
         }
+        this.validateShellPayload(command, args);
+    }
+    validateShellPayload(command, args) {
+        // Only validate shell payloads for adb commands
+        const basename = command.split("/").pop() ?? command;
+        if (basename !== "adb")
+            return;
+        const shellIndex = args.indexOf("shell");
+        if (shellIndex === -1 || shellIndex >= args.length - 1)
+            return;
+        let payloadArgs = args.slice(shellIndex + 1);
+        // Strip leading "--" (end-of-options marker)
+        if (payloadArgs[0] === "--") {
+            payloadArgs = payloadArgs.slice(1);
+        }
+        const shellPayload = payloadArgs.join(" ").trim();
+        if (!shellPayload)
+            return;
+        // Block shell metacharacters that enable command chaining/substitution.
+        // $letter/$(/$ are blocked (variable expansion, command substitution) but
+        // bare $ before digits is allowed (e.g., input text '$100').
+        if (/[;&|`()]|\$[({a-zA-Z_]/.test(shellPayload)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, "Shell metacharacters are not allowed in shell commands", "Use simple commands without chaining, pipes, or substitution");
+        }
+        // Block shell wrapper commands (sh -c, bash -c)
+        if (/^(sh|bash|dash|zsh)\s+-c\b/.test(shellPayload)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, "Shell interpreters with -c are not allowed", "Run the command directly without a shell wrapper");
+        }
+        const shellCommand = shellPayload.split(/\s+/)[0];
+        if (BLOCKED_COMMANDS.has(shellCommand)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Shell command '${shellPayload}' is not allowed`, "Use safe commands only");
+        }
+        for (const pattern of BLOCKED_SHELL_PATTERNS) {
+            if (pattern.test(shellPayload)) {
+                throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Shell command '${shellPayload}' is not allowed`, "Use safe commands only");
+            }
+        }
     }
 }

package/dist/services/test-baseline.d.ts

@@ -0,0 +1,18 @@
+export interface BaselineTestResult {
+    test: string;
+    status: "pass" | "fail" | "skip";
+}
+export interface TestBaseline {
+    savedAt: string;
+    task: string;
+    results: BaselineTestResult[];
+}
+export interface Regression {
+    test: string;
+    previousStatus: string;
+    currentStatus: string;
+}
+export declare function saveBaseline(taskName: string, results: BaselineTestResult[]): void;
+export declare function loadBaseline(taskName: string): TestBaseline | null;
+export declare function clearBaseline(taskName: string): void;
+export declare function compareResults(baseline: TestBaseline, current: BaselineTestResult[]): Regression[];

package/dist/services/test-baseline.js

@@ -0,0 +1,51 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+function getBaselineDir() {
+    const base = process.cwd() === "/" ? os.homedir() : process.cwd();
+    return path.join(base, ".replicant", "test-baselines");
+}
+function getBaselinePath(taskName) {
+    const safe = taskName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(getBaselineDir(), `${safe}.json`);
+}
+export function saveBaseline(taskName, results) {
+    const dir = getBaselineDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const baseline = {
+        savedAt: new Date().toISOString(),
+        task: taskName,
+        results,
+    };
+    fs.writeFileSync(getBaselinePath(taskName), JSON.stringify(baseline, null, 2));
+}
+export function loadBaseline(taskName) {
+    const filePath = getBaselinePath(taskName);
+    if (!fs.existsSync(filePath))
+        return null;
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+}
+export function clearBaseline(taskName) {
+    const filePath = getBaselinePath(taskName);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}
+export function compareResults(baseline, current) {
+    const currentMap = new Map(current.map(r => [r.test, r.status]));
+    const regressions = [];
+    for (const prev of baseline.results) {
+        if (prev.status === "pass") {
+            const currentStatus = currentMap.get(prev.test);
+            if (currentStatus && currentStatus !== "pass") {
+                regressions.push({
+                    test: prev.test,
+                    previousStatus: prev.status,
+                    currentStatus,
+                });
+            }
+        }
+    }
+    return regressions;
+}

package/dist/tools/adb-app.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CACHE_TTLS } from "../types/index.js";
+import { CACHE_TTLS, ReplicantError, ErrorCode } from "../types/index.js";
 export const adbAppInputSchema = z.object({
     operation: z.enum(["install", "uninstall", "launch", "stop", "clear-data", "list"]),
     apkPath: z.string().optional(),
@@ -10,32 +10,37 @@ export const adbAppInputSchema = z.object({
     offset: z.number().min(0).optional(),
 });
 async function handleInstall(input, deviceId, context) {
-    if (!input.apkPath)
-        throw new Error("apkPath is required for install operation");
+    if (!input.apkPath) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "apkPath is required for install operation", "Provide the path to the APK file to install");
+    }
     await context.adb.install(deviceId, input.apkPath);
     return { installed: input.apkPath, deviceId };
 }
 async function handleUninstall(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for uninstall operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for uninstall operation", "Provide the package name to uninstall");
+    }
     await context.adb.uninstall(deviceId, input.packageName);
     return { uninstalled: input.packageName, deviceId };
 }
 async function handleLaunch(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for launch operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for launch operation", "Provide the package name to launch");
+    }
     await context.adb.launch(deviceId, input.packageName);
     return { launched: input.packageName, deviceId };
 }
 async function handleStop(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for stop operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for stop operation", "Provide the package name to stop");
+    }
     await context.adb.stop(deviceId, input.packageName);
     return { stopped: input.packageName, deviceId };
 }
 async function handleClearData(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for clear-data operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for clear-data operation", "Provide the package name to clear data for");
+    }
     await context.adb.clearData(deviceId, input.packageName);
     return { cleared: input.packageName, deviceId };
 }
@@ -73,8 +78,9 @@ const operations = {
 export async function handleAdbAppTool(input, context) {
     const device = await context.deviceState.ensureDevice(context.adb);
     const handler = operations[input.operation];
-    if (!handler)
-        throw new Error(`Unknown operation: ${input.operation}`);
+    if (!handler) {
+        throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: install, uninstall, launch, stop, clear-data, list");
+    }
     return handler(input, device.id, context);
 }
 export const adbAppToolDefinition = {

package/dist/tools/adb-device.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CACHE_TTLS } from "../types/index.js";
+import { CACHE_TTLS, ReplicantError, ErrorCode } from "../types/index.js";
 export const adbDeviceInputSchema = z.object({
     operation: z.enum(["list", "select", "wait", "properties", "health-check"]),
     deviceId: z.string().optional(),
@@ -16,12 +16,12 @@ async function handleList(input, context) {
 }
 async function handleSelect(input, context) {
     if (!input.deviceId) {
-        throw new Error("deviceId is required for select operation");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "deviceId is required for select operation", "Use adb-device list to see available devices, then provide a deviceId");
     }
     const devices = await context.adb.getDevices();
     const device = devices.find((d) => d.id === input.deviceId);
     if (!device) {
-        throw new Error(`Device ${input.deviceId} not found`);
+        throw new ReplicantError(ErrorCode.DEVICE_NOT_FOUND, `Device ${input.deviceId} not found`, "Use adb-device list to see available devices");
     }
     context.deviceState.setCurrentDevice(device);
     return { selected: device };
@@ -77,7 +77,7 @@ async function handleHealthCheck(input, context) {
                 warnings.push("No devices connected. Start an emulator or connect a USB device.");
             }
         }
-        catch (e) {
+        catch {
             errors.push("adb server not responding. Run 'adb kill-server && adb start-server'");
         }
     }
@@ -103,8 +103,9 @@ const operations = {
 };
 export async function handleAdbDeviceTool(input, context) {
     const handler = operations[input.operation];
-    if (!handler)
-        throw new Error(`Unknown operation: ${input.operation}`);
+    if (!handler) {
+        throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: list, select, wait, properties, health-check");
+    }
     return handler(input, context);
 }
 export const adbDeviceToolDefinition = {

package/dist/tools/adb-logcat.d.ts

@@ -5,11 +5,11 @@ export declare const adbLogcatInputSchema: z.ZodObject<{
     package: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     level: z.ZodOptional<z.ZodEnum<{
-        debug: "debug";
+        error: "error";
+        warn: "warn";
         info: "info";
+        debug: "debug";
         verbose: "verbose";
-        warn: "warn";
-        error: "error";
     }>>;
     rawFilter: z.ZodOptional<z.ZodString>;
     since: z.ZodOptional<z.ZodString>;

package/dist/tools/adb-logcat.js

@@ -35,10 +35,12 @@ export async function handleAdbLogcatTool(input, context) {
     const output = await context.adb.logcat(deviceId, {
         lines: input.lines,
         filter: filter || undefined,
+        since: input.since,
+        package: input.package,
     });
     // Cache the full output and return a summary
     const logId = context.cache.generateId("logcat");
-    context.cache.set(logId, { output, deviceId, filter }, "logcat", CACHE_TTLS.UI_TREE);
+    context.cache.set(logId, { output, deviceId, filter }, "logcat", CACHE_TTLS.LOGCAT);
     // Parse log lines
     const lines = output.split("\n").filter(Boolean);
     const errorCount = lines.filter((l) => l.includes(" E ")).length;
@@ -65,7 +67,7 @@ export const adbLogcatToolDefinition = {
             tags: { type: "array", items: { type: "string" }, description: "Filter by log tags" },
             level: { type: "string", enum: ["verbose", "debug", "info", "warn", "error"] },
             rawFilter: { type: "string", description: "Raw logcat filter string" },
-            since: { type: "string", description: "Time filter (e.g., '5m' or ISO timestamp)" },
+            since: { type: "string", description: "Time filter in adb logcat -T format (e.g., '01-20 15:30:00.000')" },
         },
     },
 };

package/dist/tools/adb-shell.d.ts

@@ -3,6 +3,9 @@ import { ServerContext } from "../server.js";
 export declare const adbShellInputSchema: z.ZodObject<{
     command: z.ZodString;
     timeout: z.ZodOptional<z.ZodNumber>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    summaryOnly: z.ZodOptional<z.ZodBoolean>;
+    previewChars: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type AdbShellInput = z.infer<typeof adbShellInputSchema>;
 export declare function handleAdbShellTool(input: AdbShellInput, context: ServerContext): Promise<Record<string, unknown>>;
@@ -20,6 +23,18 @@ export declare const adbShellToolDefinition: {
                 type: string;
                 description: string;
             };
+            maxChars: {
+                type: string;
+                description: string;
+            };
+            summaryOnly: {
+                type: string;
+                description: string;
+            };
+            previewChars: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/dist/tools/adb-shell.js

@@ -2,17 +2,42 @@ import { z } from "zod";
 export const adbShellInputSchema = z.object({
     command: z.string(),
     timeout: z.number().optional(),
+    maxChars: z.number().min(1).optional(),
+    summaryOnly: z.boolean().optional(),
+    previewChars: z.number().min(1).optional(),
 });
 export async function handleAdbShellTool(input, context) {
     const device = await context.deviceState.ensureDevice(context.adb);
     const deviceId = device.id;
     const result = await context.adb.shell(deviceId, input.command, input.timeout);
-    return {
-        stdout: result.stdout,
-        stderr: result.stderr,
+    if (input.summaryOnly) {
+        const previewChars = input.previewChars ?? 200;
+        return {
+            exitCode: result.exitCode,
+            deviceId,
+            summarized: true,
+            stdoutPreview: result.stdout.slice(0, previewChars),
+            stderrPreview: result.stderr.slice(0, previewChars),
+            originalStdoutChars: result.stdout.length,
+            originalStderrChars: result.stderr.length,
+        };
+    }
+    const maxChars = input.maxChars;
+    const stdout = maxChars ? result.stdout.slice(0, maxChars) : result.stdout;
+    const stderr = maxChars ? result.stderr.slice(0, maxChars) : result.stderr;
+    const truncated = !!maxChars && (result.stdout.length > maxChars || result.stderr.length > maxChars);
+    const response = {
+        stdout,
+        stderr,
         exitCode: result.exitCode,
         deviceId,
+        truncated,
     };
+    if (maxChars !== undefined) {
+        response.originalStdoutChars = result.stdout.length;
+        response.originalStderrChars = result.stderr.length;
+    }
+    return response;
 }
 export const adbShellToolDefinition = {
     name: "adb-shell",
@@ -22,6 +47,9 @@ export const adbShellToolDefinition = {
         properties: {
             command: { type: "string", description: "Shell command to execute" },
             timeout: { type: "number", description: "Timeout in ms (default: 30s, max: 120s)" },
+            maxChars: { type: "number", description: "Truncate stdout/stderr to at most this many characters" },
+            summaryOnly: { type: "boolean", description: "Return only compact previews and counts, omitting full stdout/stderr" },
+            previewChars: { type: "number", description: "For summaryOnly: preview length in characters (default: 200)" },
         },
         required: ["command"],
     },

package/dist/tools/cache.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ReplicantError, ErrorCode } from "../types/index.js";
 export const cacheInputSchema = z.object({
     operation: z.enum(["get-stats", "clear", "get-config", "set-config"]),
     key: z.string().optional(),
@@ -29,7 +30,7 @@ export async function handleCacheTool(input, cache) {
             }
             return { config: cache.getConfig() };
         default:
-            throw new Error(`Unknown operation: ${input.operation}`);
+            throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: get-stats, clear, get-config, set-config");
     }
 }
 export const cacheToolDefinition = {

package/dist/tools/emulator-device.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ReplicantError, ErrorCode } from "../types/index.js";
 export const emulatorDeviceInputSchema = z.object({
     operation: z.enum([
         "list",
@@ -23,14 +24,14 @@ async function handleList(input, context) {
 }
 async function handleCreate(input, context) {
     if (!input.avdName || !input.device || !input.systemImage) {
-        throw new Error("avdName, device, and systemImage are required for create");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "avdName, device, and systemImage are required for create", "Provide all three parameters: avdName, device, and systemImage");
     }
     await context.emulator.create(input.avdName, input.device, input.systemImage);
     return { created: input.avdName };
 }
 async function handleStart(input, context) {
     if (!input.avdName) {
-        throw new Error("avdName is required for start");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "avdName is required for start", "Provide the AVD name to start");
     }
     const emulatorId = await context.emulator.start(input.avdName);
     const devices = await context.adb.getDevices();
@@ -43,7 +44,7 @@ async function handleStart(input, context) {
 async function handleKill(input, context) {
     const emulatorId = input.emulatorId || context.deviceState.getCurrentDevice()?.id;
     if (!emulatorId) {
-        throw new Error("emulatorId is required or select an emulator first");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "emulatorId is required or select an emulator first", "Use emulator-device list to see running emulators, or provide emulatorId");
     }
     await context.emulator.kill(emulatorId);
     if (context.deviceState.getCurrentDevice()?.id === emulatorId) {
@@ -53,7 +54,7 @@ async function handleKill(input, context) {
 }
 async function handleWipe(input, context) {
     if (!input.avdName) {
-        throw new Error("avdName is required for wipe");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "avdName is required for wipe", "Provide the AVD name to wipe");
     }
     await context.emulator.wipe(input.avdName);
     return { wiped: input.avdName };
@@ -61,21 +62,23 @@ async function handleWipe(input, context) {
 function resolveEmulatorId(input, context) {
     const emulatorId = input.emulatorId || context.deviceState.getCurrentDevice()?.id;
     if (!emulatorId) {
-        throw new Error(`emulatorId is required for ${input.operation}`);
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, `emulatorId is required for ${input.operation}`, "Use emulator-device list to see running emulators, or provide emulatorId");
     }
     return emulatorId;
 }
 async function handleSnapshotSave(input, context) {
     const emulatorId = resolveEmulatorId(input, context);
-    if (!input.snapshotName)
-        throw new Error("snapshotName is required for snapshot-save");
+    if (!input.snapshotName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "snapshotName is required for snapshot-save", "Provide the snapshot name to save");
+    }
     await context.emulator.snapshotSave(emulatorId, input.snapshotName);
     return { saved: input.snapshotName, emulatorId };
 }
 async function handleSnapshotLoad(input, context) {
     const emulatorId = resolveEmulatorId(input, context);
-    if (!input.snapshotName)
-        throw new Error("snapshotName is required for snapshot-load");
+    if (!input.snapshotName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "snapshotName is required for snapshot-load", "Provide the snapshot name to load");
+    }
     await context.emulator.snapshotLoad(emulatorId, input.snapshotName);
     return { loaded: input.snapshotName, emulatorId };
 }
@@ -86,8 +89,9 @@ async function handleSnapshotList(input, context) {
 }
 async function handleSnapshotDelete(input, context) {
     const emulatorId = resolveEmulatorId(input, context);
-    if (!input.snapshotName)
-        throw new Error("snapshotName is required for snapshot-delete");
+    if (!input.snapshotName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "snapshotName is required for snapshot-delete", "Provide the snapshot name to delete");
+    }
     await context.emulator.snapshotDelete(emulatorId, input.snapshotName);
     return { deleted: input.snapshotName, emulatorId };
 }
@@ -104,8 +108,9 @@ const operations = {
 };
 export async function handleEmulatorDeviceTool(input, context) {
     const handler = operations[input.operation];
-    if (!handler)
-        throw new Error(`Unknown operation: ${input.operation}`);
+    if (!handler) {
+        throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: list, create, start, kill, wipe, snapshot-save, snapshot-load, snapshot-list, snapshot-delete");
+    }
     return handler(input, context);
 }
 export const emulatorDeviceToolDefinition = {

package/dist/tools/gradle-get-details.d.ts

@@ -8,6 +8,9 @@ export declare const gradleGetDetailsInputSchema: z.ZodObject<{
         tasks: "tasks";
         logs: "logs";
     }>>>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    summaryOnly: z.ZodOptional<z.ZodBoolean>;
+    previewChars: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type GradleGetDetailsInput = z.infer<typeof gradleGetDetailsInputSchema>;
 export declare function handleGradleGetDetailsTool(input: GradleGetDetailsInput, context: ServerContext): Promise<Record<string, unknown>>;
@@ -26,6 +29,18 @@ export declare const gradleGetDetailsToolDefinition: {
                 enum: string[];
                 description: string;
             };
+            maxChars: {
+                type: string;
+                description: string;
+            };
+            summaryOnly: {
+                type: string;
+                description: string;
+            };
+            previewChars: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };