taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/cli/commands/contract.js

@@ -0,0 +1,120 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
+import { ContractReviewInputSchema, ContractVerdictViewSchema } from "../../domain/contract.js";
+import { failureOutput, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
+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);
+}
+export function createContractCommand(dependencies) {
+    const command = new Command("contract")
+        .description("Validate an Acceptance Contract without touching a device")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--contract <path>", "Acceptance Contract path")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        const json = options.json === true;
+        if (options.contract === undefined) {
+            writeFailure(dependencies, json, "CONTRACT_INVALID", "Missing required option '--contract'");
+            return;
+        }
+        if (dependencies.contractLoader === undefined) {
+            writeFailure(dependencies, json, "CONFIG_INVALID", "TapHound contract validation is not configured");
+            return;
+        }
+        const contractPath = resolve(options.project, options.contract);
+        try {
+            await prepareWorkspace(dependencies, options.project);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+            return;
+        }
+        try {
+            const loaded = await dependencies.contractLoader.load({
+                projectRoot: options.project,
+                contractPath
+            });
+            if (json) {
+                writeJson(dependencies.stdout, {
+                    status: "valid",
+                    contractId: loaded.contract.id,
+                    contractSha256: loaded.contractSha256,
+                    journeySha256: loaded.contract.journey.sha256,
+                    journeyPath: loaded.journeyPath
+                });
+            }
+            else {
+                writeLine(dependencies.stdout, `TapHound contract: ${loaded.contract.id} is valid (${loaded.contractSha256.slice(0, 12)}...)`);
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONTRACT_INVALID", error instanceof Error ? error.message : String(error));
+        }
+    });
+    command.addCommand(createContractReviewCommand(dependencies));
+    return command;
+}
+function createContractReviewCommand(dependencies) {
+    const command = new Command("review")
+        .description("Merge reviewer findings into a Verdict (never overwrites fail/invalid)")
+        .requiredOption("--verdict <path>", "Verdict JSON path (verdict.json)")
+        .requiredOption("--findings <path>", "Reviewer findings JSON path")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        // `--project` and `--json` are also declared on the parent command;
+        // commander routes them to the parent when both are declared, so fall
+        // back to the parent's values.
+        const parentOpts = command.parent?.opts() ?? {};
+        const project = parentOpts.project
+            ?? dependencies.cwd();
+        const json = options.json === true
+            || parentOpts.json === true;
+        if (dependencies.contractReview === undefined) {
+            writeFailure(dependencies, json, "CONFIG_INVALID", "TapHound contract review is not configured");
+            return;
+        }
+        const verdictPath = resolve(project, options.verdict);
+        const findingsPath = resolve(project, options.findings);
+        try {
+            await prepareWorkspace(dependencies, project);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+            return;
+        }
+        try {
+            const verdict = ContractVerdictViewSchema.parse(await dependencies.readJson(verdictPath));
+            const review = ContractReviewInputSchema.parse(await dependencies.readJson(findingsPath));
+            const merged = await dependencies.contractReview.merge({
+                view: verdict,
+                review
+            });
+            await dependencies.contractReview.writeVerdict({
+                verdictPath,
+                view: merged.view
+            });
+            if (json) {
+                writeJson(dependencies.stdout, merged.view);
+            }
+            else {
+                writeLine(dependencies.stdout, `TapHound contract review: ${merged.view.verdict.toUpperCase()} (findings applied: ${String(merged.applied)})`);
+            }
+            dependencies.setExitCode(merged.view.verdict === "pass" ? 0 : 1);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONTRACT_INVALID", error instanceof Error ? error.message : String(error));
+        }
+    });
+    return command;
+}

package/dist/cli/commands/doctor.js

@@ -1,10 +1,12 @@
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { TapHoundConfigSchema } from "../../domain/config.js";
+import { CONFIG_PATH } from "../../domain/workspace.js";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
 import { doctorMessage, errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
-async function configuredPackageName(dependencies, options) {
+async function configuredConfig(dependencies, options) {
     try {
-        return TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config))).run.packageName;
+        return TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config)));
     }
     catch {
         return undefined;
@@ -14,14 +16,18 @@ export function createDoctorCommand(dependencies) {
     return new Command("doctor")
         .description("Check TapHound tools, permissions, application, and device")
         .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")
         .option("--json", "Emit machine-readable JSON")
         .action(async (options) => {
+        const json = options.json === true;
         try {
-            const packageName = await configuredPackageName(dependencies, options);
+            const config = await configuredConfig(dependencies, options);
             const report = await dependencies.doctor.run({
-                ...(packageName === undefined ? {} : { packageName }),
+                ...(config === undefined ? {} : { packageName: config.run.packageName }),
+                ...(config?.ui?.backend === undefined
+                    ? {}
+                    : { requestedUiBackend: config.ui.backend }),
                 ...(options.device === undefined
                     ? {}
                     : { requestedDevice: options.device }),
@@ -29,7 +35,7 @@ export function createDoctorCommand(dependencies) {
                     ? {}
                     : { signal: dependencies.signal })
             });
-            if (options.json === true) {
+            if (json) {
                 writeJson(dependencies.stdout, report);
             }
             else {
@@ -38,14 +44,15 @@ export function createDoctorCommand(dependencies) {
             dependencies.setExitCode(report.status === "passed" ? 0 : 3);
         }
         catch (error) {
-            const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
-            if (options.json === true) {
+            const code = failureCodeFromUnknown(error) ?? "INTERNAL_ERROR";
+            const output = failureOutput(exitCodeForFailure(code), code, errorMessage(error));
+            if (json) {
                 writeJson(dependencies.stdout, output);
             }
             else {
                 writeLine(dependencies.stderr, output.failure.message);
             }
-            dependencies.setExitCode(4);
+            dependencies.setExitCode(exitCodeForFailure(code));
         }
     });
 }

package/dist/cli/commands/failure.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { CliDependencies } from "../dependencies.js";
+export declare function createFailureCommand(dependencies: CliDependencies): Command;

package/dist/cli/commands/failure.js

@@ -0,0 +1,63 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
+import { failureOutput, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
+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);
+}
+export function createFailureCommand(dependencies) {
+    const command = new Command("failure")
+        .description("Classify Verification failures into structured reports")
+        .addCommand(createClassifyCommand(dependencies));
+    return command;
+}
+function createClassifyCommand(dependencies) {
+    return new Command("classify")
+        .description("Classify a failed Verification report (offline, deterministic)")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .requiredOption("--report <path>", "Verification report.json path")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        const json = options.json === true;
+        if (dependencies.failureClassifier === undefined) {
+            writeFailure(dependencies, json, "CONFIG_INVALID", "TapHound failure classification is not configured");
+            return;
+        }
+        try {
+            await prepareWorkspace(dependencies, options.project);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+            return;
+        }
+        try {
+            const classification = await dependencies.failureClassifier.classify(resolve(options.project, options.report));
+            if (json) {
+                writeJson(dependencies.stdout, classification);
+            }
+            else {
+                writeLine(dependencies.stdout, `Failure classification: ${classification.type} (${classification.stage}) [${classification.code}]`);
+                if (classification.expected !== undefined) {
+                    writeLine(dependencies.stdout, `  expected: ${classification.expected}`);
+                }
+                if (classification.actual !== undefined) {
+                    writeLine(dependencies.stdout, `  actual: ${classification.actual}`);
+                }
+                writeLine(dependencies.stdout, `  evidence: ${classification.evidenceRefs.join(", ") || "(none)"}`);
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+        }
+    });
+}

package/dist/cli/commands/generation/lifecycle-commands.d.ts

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+import type { CliDependencies } from "../../dependencies.js";
+export declare function createFinalizeCommand(dependencies: CliDependencies): Command;
+export declare function createRecoverCommand(dependencies: CliDependencies): Command;
+export declare function createReopenCommand(dependencies: CliDependencies): Command;

package/dist/cli/commands/generation/lifecycle-commands.js

@@ -0,0 +1,211 @@
+// `generation` subcommands that verify and recover a session: finalize, recover, and reopen.
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { z } from "zod";
+import { GenerationOutputPathSchema } from "../../../application/generation/generation-finalizer.js";
+import { GenerationOperationError } from "../../../application/generation/generation-starter.js";
+import { GenerationSessionIdSchema } from "../../../domain/generation.js";
+import { JOBS_DIR } from "../../../domain/workspace.js";
+import { writeLine } from "../../output.js";
+import { addCommonOptions, assertRuntimeConfig, generationConfig, mappedFailure, requireRuntime, tools, writeFailure, writeSuccess } from "./shared.js";
+export function createFinalizeCommand(dependencies) {
+    return addCommonOptions(new Command("finalize")
+        .description("Verify and publish a generated Journey")
+        .requiredOption("--output <path>", "Journey output under .taphound/journeys")
+        .option("--name <name>", "Generated Journey name")
+        .option("--device <serial>", "Select an online Android device")
+        .option("--detach", "Run verification in a detached process and return immediately"), dependencies).action(async (options) => {
+        try {
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const outputPath = GenerationOutputPathSchema.parse(options.output);
+            const name = options.name === undefined
+                ? undefined
+                : z.string().trim().min(1).parse(options.name);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            const context = await runtime.readContextSnapshot(generationId);
+            if (options.detach === true) {
+                if (dependencies.detachedProcess === undefined
+                    || dependencies.cliEntryPath === undefined
+                    || dependencies.createDetachedJobId === undefined) {
+                    throw new Error("Detached finalization is unavailable");
+                }
+                const jobId = dependencies.createDetachedJobId();
+                const jobHome = projectRoot;
+                const outputJobPath = `${JOBS_DIR}/${generationId}/${jobId}-output.json`;
+                const progressJobPath = `${JOBS_DIR}/${generationId}/${jobId}-progress.log`;
+                const args = [
+                    dependencies.cliEntryPath,
+                    "generation",
+                    "finalize",
+                    "--project",
+                    projectRoot,
+                    "--config",
+                    options.config,
+                    "--session",
+                    generationId,
+                    "--output",
+                    options.output,
+                    ...(options.name === undefined ? [] : ["--name", options.name]),
+                    ...(options.device === undefined
+                        ? []
+                        : ["--device", options.device]),
+                    "--json"
+                ];
+                const launched = await dependencies.detachedProcess.launch({
+                    executable: process.execPath,
+                    args,
+                    cwd: jobHome,
+                    stdoutPath: resolve(jobHome, outputJobPath),
+                    stderrPath: resolve(jobHome, progressJobPath)
+                });
+                writeSuccess(dependencies, options, {
+                    status: "finalizationStarted",
+                    exitCode: 0,
+                    generationId,
+                    jobId,
+                    ownerPid: launched.pid,
+                    outputPath: outputJobPath,
+                    progressPath: progressJobPath
+                }, `Generation finalization started: ${generationId}`);
+                return;
+            }
+            const verdict = await dependencies.contextValidator.validate({
+                context,
+                projectRoot,
+                config
+            });
+            if (verdict.status !== "valid") {
+                writeLine(dependencies.stderr, `TapHound warning: live project context drifted from the session snapshot (${verdict.reason.code}: ${verdict.reason.message}); the session snapshot remains authoritative`);
+            }
+            const doctor = await dependencies.doctor.run({
+                packageName: config.run.packageName,
+                skipPermissionProbe: true,
+                ...(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, options, 3, 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) {
+                writeFailure(dependencies, options, 3, "DEVICE_UNAVAILABLE", "Doctor did not select a device");
+                return;
+            }
+            const project = await dependencies.projectDescriber.describe({
+                projectRoot: projectRoot,
+                config,
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            const result = await runtime.finalizer.finalize({
+                generationId,
+                projectRoot: projectRoot,
+                config,
+                context,
+                project,
+                outputPath,
+                ...(name === undefined ? {} : { name }),
+                deviceSerial,
+                manualReplay: process.stdin.isTTY,
+                toolVersions: tools(doctor.checks),
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            writeSuccess(dependencies, options, {
+                status: "verified",
+                exitCode: 0,
+                generationId,
+                bundlePath: result.bundlePath,
+                journeyPath: result.journeyPath,
+                metaPath: result.metaPath,
+                replayed: result.replayed
+            }, `Generation verified: ${result.journeyPath}`);
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}
+export function createRecoverCommand(dependencies) {
+    return addCommonOptions(new Command("recover")
+        .description("Explicitly reactivate an interrupted in-flight step")
+        .requiredOption("--decision <decision>", "Recovery decision; retry acknowledges the action may have executed"), dependencies).action(async (options) => {
+        try {
+            if (options.decision !== "retry") {
+                throw new GenerationOperationError("CONFIG_INVALID", "generation recover currently requires --decision retry");
+            }
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            const before = await runtime.recovery.status(generationId);
+            if (!before.recovery.available) {
+                throw new GenerationOperationError("RECOVERY_REQUIRED", "Generation session has no recoverable in-flight step");
+            }
+            const session = await runtime.recovery.retry(generationId);
+            const recoveryKind = before.recovery.kind;
+            const nextAction = recoveryKind === "verification"
+                ? "generation finalize"
+                : "retry the interrupted generation step";
+            writeSuccess(dependencies, options, {
+                status: "recovered",
+                exitCode: 0,
+                generationId,
+                revision: session.revision,
+                recoveryKind,
+                nextAction,
+                actionMayHaveExecuted: before.recovery.actionMayHaveExecuted,
+                previousAttemptOutcome: before.recovery.attemptOutcome
+            }, recoveryKind === "verification"
+                ? `Generation ${generationId} verification recovered. Rerun generation finalize to verify again.`
+                : `Generation ${generationId} recovered. Explicitly retry the interrupted generation step.`);
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}
+export function createReopenCommand(dependencies) {
+    return addCommonOptions(new Command("reopen")
+        .description("Reopen a deterministically failed verification for audited step repair")
+        .requiredOption("--reason <text>", "Reason for reopening the failed verification"), dependencies).action(async (options) => {
+        try {
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            const session = await runtime.reopen.reopen({
+                generationId,
+                reason: options.reason
+            });
+            writeSuccess(dependencies, options, {
+                status: "reopened",
+                exitCode: 0,
+                generationId,
+                revision: session.revision,
+                verification: session.verification,
+                preservedFailure: session.verificationHistory.at(-1),
+                nextAction: {
+                    command: "generation step --replace <index>",
+                    then: "generation finalize"
+                }
+            }, `Generation ${generationId} reopened. Repair with generation step --replace <index>, then rerun generation finalize.`);
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}

package/dist/cli/commands/generation/session-commands.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { type GenerationSession } from "../../../domain/generation.js";
+import type { CliDependencies } from "../../dependencies.js";
+export declare function createStartCommand(dependencies: CliDependencies): Command;
+export declare function createObserveCommand(dependencies: CliDependencies): Command;
+export declare function createStatusCommand(dependencies: CliDependencies): Command;
+export declare function createArchiveCommand(dependencies: CliDependencies): Command;
+export declare function idlePolicyText(policy: NonNullable<GenerationSession["idlePolicy"]>): string;
+export declare function createConfigCommand(dependencies: CliDependencies): Command;
+export declare function generationListText(sessions: readonly GenerationSession[]): string;
+export declare function createListCommand(dependencies: CliDependencies): Command;