taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/cli/commands/record.js

@@ -1,20 +1,28 @@
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { TapHoundConfigSchema } from "../../domain/config.js";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
+import { assertArtifactDirectory, CONFIG_PATH } from "../../domain/workspace.js";
+import { ResolvedJourneyPathSchema } from "../../domain/journey-composition.js";
 import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
 export function createRecordCommand(dependencies) {
     return new Command("record")
         .description("Interactively record a TapHound Journey")
         .option("--project <path>", "Android project root", dependencies.cwd())
-        .option("--config <path>", "TapHound config path", "taphound.config.json")
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
         .option("--device <serial>", "Select an online Android device")
         .requiredOption("--name <name>", "Journey name")
-        .requiredOption("--output <path>", "Journey output path")
+        .requiredOption("--output <path>", "Journey output under .taphound/journeys")
         .option("--json", "Emit machine-readable JSON")
         .action(async (options) => {
         let config;
+        let outputPath;
         try {
             config = TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config)));
+            assertArtifactDirectory(options.project, config.artifactsDir);
+            outputPath = resolve(options.project, ResolvedJourneyPathSchema.parse(options.output));
+            await prepareWorkspace(dependencies, options.project);
         }
         catch (error) {
             const output = failureOutput(2, "CONFIG_INVALID", errorMessage(error));
@@ -30,6 +38,9 @@ export function createRecordCommand(dependencies) {
         try {
             const doctor = await dependencies.doctor.run({
                 packageName: config.run.packageName,
+                ...(config.ui?.backend === undefined
+                    ? {}
+                    : { requestedUiBackend: config.ui.backend }),
                 ...(options.device === undefined
                     ? {}
                     : { requestedDevice: options.device }),
@@ -58,7 +69,7 @@ export function createRecordCommand(dependencies) {
                 projectRoot: options.project,
                 deviceSerial,
                 journeyName: options.name,
-                outputPath: resolve(options.project, options.output),
+                outputPath,
                 ...(dependencies.signal === undefined
                     ? {}
                     : { signal: dependencies.signal })
@@ -75,14 +86,16 @@ export function createRecordCommand(dependencies) {
             dependencies.setExitCode(result.status === "failed" ? 1 : 0);
         }
         catch (error) {
-            const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
+            const code = failureCodeFromUnknown(error) ?? "INTERNAL_ERROR";
+            const exitCode = exitCodeForFailure(code);
+            const output = failureOutput(exitCode, code, errorMessage(error));
             if (options.json === true) {
                 writeJson(dependencies.stdout, output);
             }
             else {
                 writeLine(dependencies.stderr, output.failure.message);
             }
-            dependencies.setExitCode(4);
+            dependencies.setExitCode(exitCode);
         }
     });
 }

package/dist/cli/commands/verify.js

@@ -1,106 +1,368 @@
-import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
 import { Command } from "commander";
+import { readCliVersion } from "../version.js";
+import { runDiffVerification } from "../diff-verification.js";
+import { loadPublishedReplayPolicy } from "../../application/generation/replay-policy-loader.js";
+import { logcatEvidenceWarning } from "../../application/report/report-writer.js";
 import { TapHoundConfigSchema } from "../../domain/config.js";
-import { JourneySchema } from "../../domain/journey.js";
+import { DEFAULT_DEVICE_ROLE, JourneySchema } from "../../domain/journey.js";
+import { assertArtifactDirectory, CONFIG_PATH } from "../../domain/workspace.js";
+import { exitCodeForFailure } from "../../domain/failure.js";
+import { VERIFY_RECEIPT_FILE, VerifyReceiptSchema } from "../../domain/verify-receipt.js";
 import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
 function toolVersions(checks) {
     return Object.fromEntries(checks.flatMap((check) => (check.version === undefined
         || !["node", "adb", "android"].includes(check.name)
         ? []
         : [[check.name, check.version]])));
 }
-export function createVerifyCommand(dependencies) {
-    return new Command("verify")
-        .description("Deterministically verify a TapHound Journey")
-        .option("--project <path>", "Android project root", dependencies.cwd())
-        .option("--config <path>", "TapHound config path", "taphound.config.json")
-        .requiredOption("--journey <path>", "TapHound Journey path")
-        .option("--device <serial>", "Select an online Android device")
-        .option("--package <name>", "Override run.packageName")
-        .option("--activity <name>", "Override run.activity")
-        .option("--reports <path>", "Override report output directory")
-        .option("--json", "Emit one machine-readable JSON value")
-        .action(async (options) => {
-        let config;
-        let journey;
+function writeFailure(dependencies, json, code, message) {
+    const exitCode = exitCodeForFailure(code);
+    const output = failureOutput(exitCode, code, message);
+    if (json) {
+        writeJson(dependencies.stdout, output);
+    }
+    else {
+        writeLine(dependencies.stderr, output.failure.message);
+    }
+    dependencies.setExitCode(exitCode);
+}
+/** The normalized invocation TapHound ran, recorded in the process receipt. */
+function receiptArgv(options, projectRoot, deviceSerial) {
+    const root = resolve(projectRoot);
+    return [
+        "verify",
+        "--project", root,
+        "--config", resolve(root, options.config),
+        "--journey", resolve(root, options.journey),
+        "--device", deviceSerial,
+        ...(options.package === undefined ? [] : ["--package", options.package]),
+        ...(options.activity === undefined ? [] : ["--activity", options.activity]),
+        ...(options.reports === undefined ? [] : ["--reports", options.reports]),
+        ...(options.policyFromMeta === true ? ["--policy-from-meta"] : []),
+        ...(options.json === true ? ["--json"] : [])
+    ];
+}
+/**
+ * Publishes the process receipt beside the report. The report is already
+ * published, so a receipt failure is reported on stderr and leaves the
+ * verify result intact; a Workflow checker then pauses on the missing receipt.
+ */
+async function writeReceipt(dependencies, argv, result) {
+    if (dependencies.writeVerifyReceipt === undefined)
+        return undefined;
+    const receiptPath = join(dirname(result.reportPath), VERIFY_RECEIPT_FILE);
+    try {
+        const receipt = VerifyReceiptSchema.parse({
+            version: 1,
+            argv,
+            exitCode: result.exitCode,
+            journeySha256: result.report.journey.sha256,
+            reportPath: result.reportPath,
+            reportSha256: createHash("sha256")
+                .update(await dependencies.readFile(result.reportPath))
+                .digest("hex")
+        });
+        await dependencies.writeVerifyReceipt(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+        return receiptPath;
+    }
+    catch (error) {
+        writeLine(dependencies.stderr, `TapHound: verify receipt was not written: ${errorMessage(error)}`);
+        return undefined;
+    }
+}
+async function runDoctorAndVerify(dependencies, options, config, journey, projectRoot) {
+    const json = options.json === true;
+    let replayPolicy;
+    if (options.policyFromMeta === true) {
         try {
-            const rawConfig = await dependencies.readJson(resolve(options.project, options.config));
-            const parsed = TapHoundConfigSchema.parse(rawConfig);
-            config = TapHoundConfigSchema.parse({
-                ...parsed,
-                run: {
-                    packageName: options.package ?? parsed.run.packageName,
-                    activity: options.activity ?? parsed.run.activity
-                },
-                artifactsDir: options.reports ?? parsed.artifactsDir
+            const journeyPath = resolve(projectRoot, options.journey);
+            replayPolicy = await loadPublishedReplayPolicy({
+                readJson: dependencies.readJson,
+                projectRoot,
+                journeyPath,
+                journey
             });
-            journey = JourneySchema.parse(await dependencies.readJson(resolve(options.project, options.journey)));
         }
         catch (error) {
-            const output = failureOutput(2, "CONFIG_INVALID", errorMessage(error));
-            if (options.json === true) {
+            writeFailure(dependencies, json, "REPLAY_POLICY_UNAVAILABLE", errorMessage(error));
+            return;
+        }
+    }
+    try {
+        const doctor = await dependencies.doctor.run({
+            packageName: config.run.packageName,
+            ...(config.ui?.backend === undefined
+                ? {}
+                : { requestedUiBackend: config.ui.backend }),
+            ...(options.device === undefined
+                ? {}
+                : { requestedDevice: options.device }),
+            ...(dependencies.signal === undefined
+                ? {}
+                : { signal: dependencies.signal })
+        });
+        if (doctor.status === "failed") {
+            const output = failureOutput(3, doctor.failureCode ?? "ENVIRONMENT_MISSING_TOOL", doctor.checks.find((check) => check.status === "failed")?.message
+                ?? "TapHound environment preflight failed");
+            if (json) {
                 writeJson(dependencies.stdout, output);
             }
             else {
                 writeLine(dependencies.stderr, output.failure.message);
             }
-            dependencies.setExitCode(2);
+            dependencies.setExitCode(3);
+            return;
+        }
+        const deviceSerial = options.device ?? doctor.deviceSerial;
+        if (deviceSerial === undefined) {
+            throw new Error("Doctor did not select a device");
+        }
+        if (journey.devices.length > 1) {
+            const output = failureOutput(3, "DEVICE_ROLE_UNMAPPED", `Journey declares multiple devices; map each role with --device <role>=<serial> for: ${journey.devices.map((device) => device.role).join(", ")}`);
+            if (json) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(3);
             return;
         }
+        writeLine(dependencies.stderr, `TapHound: verifying ${journey.name}`);
+        const result = await dependencies.verifier.verify({
+            config: replayPolicy === undefined ? config : { ...config, idle: replayPolicy.idle },
+            journey,
+            projectRoot,
+            devices: [{
+                    role: journey.devices[0]?.role ?? DEFAULT_DEVICE_ROLE,
+                    deviceSerial
+                }],
+            toolVersions: toolVersions(doctor.checks),
+            manualReplay: process.stdin.isTTY,
+            ...(replayPolicy === undefined ? {} : {
+                generatedReplayPolicy: replayPolicy.generatedReplayPolicy,
+                requireFocusedInput: replayPolicy.requireFocusedInput
+            }),
+            ...(dependencies.signal === undefined
+                ? {}
+                : { signal: dependencies.signal })
+        });
+        const receiptPath = await writeReceipt(dependencies, receiptArgv(options, projectRoot, deviceSerial), result);
+        if (json) {
+            writeJson(dependencies.stdout, receiptPath === undefined ? result : { ...result, receiptPath });
+        }
+        else {
+            writeLine(dependencies.stdout, `TapHound verify: ${result.status.toUpperCase()}\nReport: ${result.reportPath}${receiptPath === undefined ? "" : `\nReceipt: ${receiptPath}`}`);
+        }
+        const logcatWarning = logcatEvidenceWarning(result.report);
+        if (logcatWarning !== undefined) {
+            writeLine(dependencies.stderr, logcatWarning);
+        }
+        dependencies.setExitCode(result.exitCode);
+    }
+    catch (error) {
+        const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
+        if (json) {
+            writeJson(dependencies.stdout, output);
+        }
+        else {
+            writeLine(dependencies.stderr, output.failure.message);
+        }
+        dependencies.setExitCode(4);
+    }
+}
+async function runContractVerify(dependencies, options, config, projectRoot) {
+    const json = options.json === true;
+    if (dependencies.contractVerifier === undefined) {
+        writeFailure(dependencies, json, "CONFIG_INVALID", "TapHound contract verification is not configured");
+        return;
+    }
+    let replayPolicy;
+    if (options.policyFromMeta === true) {
         try {
-            const doctor = await dependencies.doctor.run({
-                packageName: config.run.packageName,
-                ...(options.device === undefined
-                    ? {}
-                    : { requestedDevice: options.device }),
-                ...(dependencies.signal === undefined
-                    ? {}
-                    : { signal: dependencies.signal })
+            if (dependencies.contractLoader === undefined) {
+                throw new Error("Contract loader is not configured");
+            }
+            const loaded = await dependencies.contractLoader.load({
+                projectRoot,
+                contractPath: resolve(projectRoot, options.contract)
+            });
+            replayPolicy = await loadPublishedReplayPolicy({
+                readJson: dependencies.readJson,
+                projectRoot,
+                journeyPath: loaded.journeyPath,
+                journey: loaded.journey
             });
-            if (doctor.status === "failed") {
-                const output = failureOutput(3, doctor.failureCode ?? "ENVIRONMENT_MISSING_TOOL", doctor.checks.find((check) => check.status === "failed")?.message
-                    ?? "TapHound environment preflight failed");
+        }
+        catch (error) {
+            writeFailure(dependencies, json, "REPLAY_POLICY_UNAVAILABLE", errorMessage(error));
+            return;
+        }
+    }
+    try {
+        const doctor = await dependencies.doctor.run({
+            packageName: config.run.packageName,
+            ...(config.ui?.backend === undefined
+                ? {}
+                : { requestedUiBackend: config.ui.backend }),
+            ...(options.device === undefined
+                ? {}
+                : { requestedDevice: options.device }),
+            ...(dependencies.signal === undefined
+                ? {}
+                : { signal: dependencies.signal })
+        });
+        if (doctor.status === "failed") {
+            writeFailure(dependencies, json, doctor.failureCode ?? "ENVIRONMENT_MISSING_TOOL", doctor.checks.find((check) => check.status === "failed")?.message
+                ?? "TapHound environment preflight failed");
+            return;
+        }
+        const deviceSerial = options.device ?? doctor.deviceSerial;
+        if (deviceSerial === undefined) {
+            throw new Error("Doctor did not select a device");
+        }
+        writeLine(dependencies.stderr, `TapHound: verifying contract ${resolve(projectRoot, options.contract)}`);
+        const result = await dependencies.contractVerifier.verify({
+            projectRoot,
+            config: replayPolicy === undefined ? config : { ...config, idle: replayPolicy.idle },
+            devices: [{
+                    role: DEFAULT_DEVICE_ROLE,
+                    deviceSerial
+                }],
+            toolVersions: toolVersions(doctor.checks),
+            taphoundVersion: readCliVersion(),
+            contractPath: resolve(projectRoot, options.contract),
+            manualReplay: process.stdin.isTTY,
+            ...(replayPolicy === undefined ? {} : {
+                generatedReplayPolicy: replayPolicy.generatedReplayPolicy,
+                requireFocusedInput: replayPolicy.requireFocusedInput
+            }),
+            ...(dependencies.signal === undefined
+                ? {}
+                : { signal: dependencies.signal })
+        });
+        if (json) {
+            writeJson(dependencies.stdout, result.view);
+        }
+        else {
+            writeLine(dependencies.stdout, `TapHound verify --contract: ${result.view.verdict.toUpperCase()}\nReport: ${result.view.reportPath ?? "n/a"}`);
+        }
+        dependencies.setExitCode(result.exitCode);
+    }
+    catch (error) {
+        const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
+        if (json) {
+            writeJson(dependencies.stdout, output);
+        }
+        else {
+            writeLine(dependencies.stderr, output.failure.message);
+        }
+        dependencies.setExitCode(4);
+    }
+}
+export function createVerifyCommand(dependencies) {
+    return new Command("verify")
+        .description("Deterministically verify a TapHound Journey or Acceptance Contract")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
+        .option("--journey <path>", "TapHound Journey path")
+        .option("--contract <path>", "Acceptance Contract path (mutually exclusive with --journey)")
+        .option("--diff <ref>", "Verify the Journeys a Git change affects (diff mode)")
+        .option("--base <ref>", "Base Git ref for --diff (default origin/main)")
+        .option("--head <ref>", "Head Git ref for --diff (HEAD by default, or WORKTREE)")
+        .option("--scope <p0,p1,p2>", "Selection tiers for --diff", "p0,p1")
+        .option("--device <serial>", "Select an online Android device")
+        .option("--package <name>", "Override run.packageName")
+        .option("--activity <name>", "Override run.activity")
+        .option("--reports <path>", "Report output under .taphound/build")
+        .option("--policy-from-meta", "Require the bound strict Generation Replay policy")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        if (options.policyFromMeta === true && options.diff !== undefined) {
+            writeFailure(dependencies, options.json === true, "CONFIG_INVALID", "--policy-from-meta supports --journey or --contract, not --diff");
+            return;
+        }
+        if (options.diff !== undefined) {
+            await runDiffVerification(dependencies, {
+                project: options.project,
+                config: options.config,
+                base: options.base ?? options.diff,
+                ...(options.head === undefined ? {} : { head: options.head }),
+                ...(options.device === undefined ? {} : { device: options.device }),
+                ...(options.scope === undefined ? {} : { scope: options.scope }),
+                json: options.json === true
+            });
+            return;
+        }
+        if (options.journey === undefined && options.contract === undefined) {
+            writeFailure(dependencies, options.json === true, "CONFIG_INVALID", "verify requires exactly one of --journey or --contract");
+            return;
+        }
+        if (options.journey !== undefined && options.contract !== undefined) {
+            writeFailure(dependencies, options.json === true, "CONFIG_INVALID", "--journey and --contract are mutually exclusive");
+            return;
+        }
+        let config;
+        if (options.contract === undefined) {
+            let journey;
+            try {
+                const rawConfig = await dependencies.readJson(resolve(options.project, options.config));
+                const parsed = TapHoundConfigSchema.parse(rawConfig);
+                config = TapHoundConfigSchema.parse({
+                    ...parsed,
+                    run: {
+                        packageName: options.package ?? parsed.run.packageName,
+                        activity: options.activity ?? parsed.run.activity
+                    },
+                    artifactsDir: options.reports ?? parsed.artifactsDir
+                });
+                assertArtifactDirectory(options.project, config.artifactsDir);
+                await prepareWorkspace(dependencies, options.project);
+                journey = JourneySchema.parse(await dependencies.readJson(resolve(options.project, options.journey)));
+            }
+            catch (error) {
+                const output = failureOutput(2, "CONFIG_INVALID", errorMessage(error));
                 if (options.json === true) {
                     writeJson(dependencies.stdout, output);
                 }
                 else {
                     writeLine(dependencies.stderr, output.failure.message);
                 }
-                dependencies.setExitCode(3);
+                dependencies.setExitCode(2);
                 return;
             }
-            const deviceSerial = options.device ?? doctor.deviceSerial;
-            if (deviceSerial === undefined) {
-                throw new Error("Doctor did not select a device");
-            }
-            writeLine(dependencies.stderr, `TapHound: verifying ${journey.name}`);
-            const result = await dependencies.verifier.verify({
-                config,
-                journey,
-                projectRoot: options.project,
-                deviceSerial,
-                toolVersions: toolVersions(doctor.checks),
-                ...(dependencies.signal === undefined
-                    ? {}
-                    : { signal: dependencies.signal })
+            await runDoctorAndVerify(dependencies, options, config, journey, options.project);
+            return;
+        }
+        let contractConfig;
+        try {
+            const rawConfig = await dependencies.readJson(resolve(options.project, options.config));
+            const parsed = TapHoundConfigSchema.parse(rawConfig);
+            contractConfig = TapHoundConfigSchema.parse({
+                ...parsed,
+                run: {
+                    packageName: options.package ?? parsed.run.packageName,
+                    activity: options.activity ?? parsed.run.activity
+                },
+                artifactsDir: options.reports ?? parsed.artifactsDir
             });
-            if (options.json === true) {
-                writeJson(dependencies.stdout, result);
-            }
-            else {
-                writeLine(dependencies.stdout, `TapHound verify: ${result.status.toUpperCase()}\nReport: ${result.reportPath}`);
-            }
-            dependencies.setExitCode(result.exitCode);
+            assertArtifactDirectory(options.project, contractConfig.artifactsDir);
+            await prepareWorkspace(dependencies, options.project);
         }
         catch (error) {
-            const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
+            const output = failureOutput(2, "CONFIG_INVALID", errorMessage(error));
             if (options.json === true) {
                 writeJson(dependencies.stdout, output);
             }
             else {
                 writeLine(dependencies.stderr, output.failure.message);
             }
-            dependencies.setExitCode(4);
+            dependencies.setExitCode(2);
+            return;
         }
+        await runContractVerify(dependencies, options, contractConfig, options.project);
     });
 }