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

package/dist/cli/diff-verification.js

@@ -0,0 +1,192 @@
+import { resolve } from "node:path";
+import { TapHoundConfigSchema } from "../domain/config.js";
+import { DEFAULT_DEVICE_ROLE, JourneySchema } from "../domain/journey.js";
+import { assertArtifactDirectory, CONFIG_PATH } from "../domain/workspace.js";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../domain/failure.js";
+import { errorMessage, failureOutput, writeJson, writeLine } from "./output.js";
+import { prepareWorkspace } from "./workspace-guard.js";
+function selectedScopes(scope) {
+    const normalized = scope ?? "p0,p1";
+    const tiers = [];
+    for (const token of normalized.split(",").map((value) => value.trim())) {
+        if (token === "p0" || token === "p1" || token === "p2") {
+            tiers.push(token);
+        }
+    }
+    return tiers;
+}
+function toolVersions(checks) {
+    return Object.fromEntries(checks.flatMap((check) => (check.version === undefined
+        || !["node", "adb", "android"].includes(check.name)
+        ? []
+        : [[check.name, check.version]])));
+}
+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);
+}
+/**
+ * Diff-driven verification: compute the ImpactSet for a Git change, select
+ * the affected Journeys by tier (p0/p1/p2), and verify each one on the
+ * connected device.
+ *
+ * This is the Agent-facing entry behind `verify --diff`; it never parses the app's internals — the Coding Agent
+ * only sees Journey names + verdicts.
+ */
+export async function runDiffVerification(dependencies, options) {
+    try {
+        if (dependencies.gitDiff === undefined
+            || dependencies.impact === undefined) {
+            throw new Error("TapHound change verification is not configured");
+        }
+        const head = options.head ?? "HEAD";
+        const projectRoot = options.project;
+        const config = TapHoundConfigSchema.parse(await dependencies.readJson(resolve(projectRoot, options.config)));
+        assertArtifactDirectory(projectRoot, config.artifactsDir);
+        await prepareWorkspace(dependencies, projectRoot);
+        const changeSet = await dependencies.gitDiff.diff({
+            projectRoot,
+            base: options.base,
+            head
+        });
+        const impact = await dependencies.impact.resolve({
+            projectRoot,
+            packageName: config.run.packageName,
+            changeSet
+        });
+        const scopes = selectedScopes(options.scope);
+        const selected = scopes.flatMap((tier) => (impact.selectedJourneys[tier].map((entry) => ({
+            tier,
+            path: entry.id
+        }))));
+        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 (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(3);
+            return;
+        }
+        const deviceSerial = options.device ?? doctor.deviceSerial;
+        if (deviceSerial === undefined) {
+            throw new Error("Doctor did not select a device");
+        }
+        if (dependencies.journeyCompositionStore === undefined) {
+            throw new Error("TapHound change verification is not configured");
+        }
+        const results = [];
+        for (const entry of selected) {
+            const bytes = await dependencies.journeyCompositionStore.read({
+                projectRoot,
+                relativePath: entry.path
+            });
+            const journey = JourneySchema.parse(JSON.parse(bytes.toString("utf8")));
+            if (journey.devices.length > 1) {
+                writeFailure(dependencies, options.json === true, "DEVICE_ROLE_UNMAPPED", `Journey ${journey.name} declares multiple devices; map each role with --device <role>=<serial>`);
+                return;
+            }
+            writeLine(dependencies.stderr, `TapHound: verifying ${journey.name} (${entry.tier})`);
+            const result = await dependencies.verifier.verify({
+                config,
+                journey,
+                projectRoot,
+                devices: [{
+                        role: journey.devices[0]?.role ?? DEFAULT_DEVICE_ROLE,
+                        deviceSerial
+                    }],
+                toolVersions: toolVersions(doctor.checks),
+                manualReplay: process.stdin.isTTY,
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            results.push({
+                path: entry.path,
+                name: journey.name,
+                selection: entry.tier,
+                status: result.status,
+                exitCode: result.exitCode,
+                reportPath: result.reportPath
+            });
+        }
+        const failed = results.find((result) => result.status !== "passed");
+        let overall;
+        let note;
+        if (changeSet.files.length === 0) {
+            overall = "passed";
+            note = "No changes; nothing to verify";
+        }
+        else {
+            overall = results.length === 0
+                ? "error"
+                : failed === undefined
+                    ? "passed"
+                    : "failed";
+        }
+        const exitCode = results.length === 0
+            ? (changeSet.files.length === 0 ? 0 : 4)
+            : failed === undefined
+                ? 0
+                : failed.exitCode;
+        const payload = {
+            base: options.base,
+            head,
+            impact,
+            results,
+            overall,
+            exitCode,
+            ...(note === undefined ? {} : { note })
+        };
+        if (options.json === true) {
+            writeJson(dependencies.stdout, payload);
+        }
+        else {
+            const lines = [
+                `TapHound verify (${options.base}...${head}):`,
+                ...results.map((result) => (`  ${result.selection.toUpperCase()} ${result.name}: ${result.status.toUpperCase()}`)),
+                `overall: ${overall.toUpperCase()}`
+            ];
+            writeLine(dependencies.stdout, lines.join("\n"));
+        }
+        dependencies.setExitCode(exitCode);
+    }
+    catch (error) {
+        const code = failureCodeFromUnknown(error);
+        if (code !== undefined) {
+            writeFailure(dependencies, options.json === true, code, errorMessage(error));
+            return;
+        }
+        const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
+        if (options.json === true) {
+            writeJson(dependencies.stdout, output);
+        }
+        else {
+            writeLine(dependencies.stderr, output.failure.message);
+        }
+        dependencies.setExitCode(4);
+    }
+}
+export { CONFIG_PATH, writeFailure };

package/dist/cli/main.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { CommanderError } from "commander";
 import { createProductionDependencies } from "./dependencies.js";
+import { RuntimeBackendConfigError, RuntimeBackendSelectionError, resolveRuntimeBackendChoiceFromInvocation } from "./runtime-selection.js";
 import { errorMessage, failureOutput, writeJson, writeLine } from "./output.js";
 import { createProgram } from "./program.js";
 export async function withTerminationSignal(operation, source = process) {
@@ -69,5 +71,51 @@ export async function runMain(argv, dependencies = createProductionDependencies(
 const entryPath = process.argv[1];
 if (entryPath !== undefined
     && import.meta.url === pathToFileURL(realpathSync(resolve(entryPath))).href) {
-    await withTerminationSignal((signal) => runMain(process.argv, createProductionDependencies(signal)));
+    await withTerminationSignal(async (signal) => {
+        let dependencies;
+        try {
+            dependencies = createProductionDependencies(signal, {
+                runtimeBackendChoice: await resolveRuntimeBackendChoiceFromInvocation({
+                    env: process.env,
+                    argv: process.argv,
+                    cwd: process.cwd(),
+                    readConfigFile: (path) => readFile(path, "utf8")
+                })
+            });
+        }
+        catch (error) {
+            if (error instanceof RuntimeBackendSelectionError
+                || error instanceof RuntimeBackendConfigError) {
+                const output = failureOutput(2, "CONFIG_INVALID", error.message);
+                if (process.argv.includes("--json")) {
+                    writeJson({
+                        write: (content) => {
+                            process.stdout.write(content);
+                        }
+                    }, output);
+                }
+                else {
+                    writeLine({
+                        write: (content) => {
+                            process.stderr.write(content);
+                        }
+                    }, output.failure.message);
+                }
+                process.exitCode = 2;
+                return;
+            }
+            throw error;
+        }
+        try {
+            await runMain(process.argv, dependencies);
+        }
+        finally {
+            try {
+                await dependencies.close?.();
+            }
+            catch (error) {
+                process.stderr.write(`TapHound: failed to release the runtime backend: ${errorMessage(error)}\n`);
+            }
+        }
+    });
 }

package/dist/cli/output.d.ts

@@ -1,9 +1,10 @@
 import type { DoctorReport } from "../application/doctor/doctor-service.js";
-import type { FailureCode } from "../domain/failure.js";
+import type { ContextLoadError } from "../application/context/context-loader.js";
+import type { FailureCode, TapHoundExitCode } from "../domain/failure.js";
 import type { TextOutput } from "./dependencies.js";
 export interface CliFailureOutput {
     status: "error";
-    exitCode: 2 | 3 | 4;
+    exitCode: TapHoundExitCode;
     failure: {
         code: FailureCode;
         message: string;
@@ -11,6 +12,7 @@ export interface CliFailureOutput {
 }
 export declare function writeJson(output: TextOutput, value: unknown): void;
 export declare function writeLine(output: TextOutput, value: string): void;
-export declare function failureOutput(exitCode: 2 | 3 | 4, code: FailureCode, message: string): CliFailureOutput;
+export declare function failureOutput(exitCode: TapHoundExitCode, code: FailureCode, message: string): CliFailureOutput;
 export declare function doctorMessage(report: DoctorReport): string;
 export declare function errorMessage(error: unknown): string;
+export declare function contextLoadHint(error: ContextLoadError): string | undefined;

package/dist/cli/output.js

@@ -20,3 +20,15 @@ export function doctorMessage(report) {
 export function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+export function contextLoadHint(error) {
+    if (error.code !== "CONTEXT_INVALID"
+        || (!error.message.includes("index does not exist")
+            && !error.message.includes("shard does not exist"))) {
+        return undefined;
+    }
+    return "Project Context is missing at the resolved path. Generate the "
+        + "committed Context first with `taphound context generate`, or pass "
+        + "--context with an explicit index path. For a registered local "
+        + "target, run `taphound local sync <id>` before retrying. See "
+        + "docs/agent-integration.md and docs/local-target.md.";
+}

package/dist/cli/program.js

@@ -1,11 +1,20 @@
 import { Command } from "commander";
+import { readCliVersion } from "./version.js";
 import { createContextCommand } from "./commands/context.js";
 import { createDoctorCommand } from "./commands/doctor.js";
 import { createGenerationCommand } from "./commands/generation.js";
 import { createInitCommand } from "./commands/init.js";
+import { createJourneyCommand } from "./commands/journey.js";
+import { createObserveCommand } from "./commands/observe.js";
 import { createProjectCommand } from "./commands/project.js";
 import { createRecordCommand } from "./commands/record.js";
 import { createVerifyCommand } from "./commands/verify.js";
+import { createContractCommand } from "./commands/contract.js";
+import { createAlignCommand } from "./commands/align.js";
+import { createImpactCommand } from "./commands/impact.js";
+import { createKnowledgeCommand } from "./commands/knowledge.js";
+import { createBaselineCommand } from "./commands/baseline.js";
+import { createFailureCommand } from "./commands/failure.js";
 import { createProductionDependencies } from "./dependencies.js";
 export function createProgram(dependencies = createProductionDependencies()) {
     const configureOutput = (command) => {
@@ -25,6 +34,7 @@ export function createProgram(dependencies = createProductionDependencies()) {
     return new Command()
         .name("taphound")
         .description("Deterministic app journey recording and verification")
+        .version(readCliVersion(), "-v, --version")
         .configureOutput({
         writeOut: (content) => {
             dependencies.stdout.write(content);
@@ -36,8 +46,16 @@ export function createProgram(dependencies = createProductionDependencies()) {
         .addCommand(configureOutput(createDoctorCommand(dependencies)))
         .addCommand(configureOutput(createRecordCommand(dependencies)))
         .addCommand(configureOutput(createVerifyCommand(dependencies)))
+        .addCommand(configureOutput(createContractCommand(dependencies)))
+        .addCommand(configureOutput(createObserveCommand(dependencies)))
         .addCommand(configureOutput(createProjectCommand(dependencies)))
         .addCommand(configureOutput(createContextCommand(dependencies)))
+        .addCommand(configureOutput(createJourneyCommand(dependencies)))
         .addCommand(configureOutput(createGenerationCommand(dependencies)))
-        .addCommand(configureOutput(createInitCommand(dependencies)));
+        .addCommand(configureOutput(createKnowledgeCommand(dependencies)))
+        .addCommand(configureOutput(createBaselineCommand(dependencies)))
+        .addCommand(configureOutput(createFailureCommand(dependencies)))
+        .addCommand(configureOutput(createInitCommand(dependencies)))
+        .addCommand(configureOutput(createAlignCommand(dependencies)))
+        .addCommand(configureOutput(createImpactCommand(dependencies)));
 }

package/dist/cli/project-root.d.ts

@@ -0,0 +1 @@
+export declare function canonicalProjectRoot(cwd: string, projectRoot: string): Promise<string>;

package/dist/cli/project-root.js

@@ -0,0 +1,6 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+export async function canonicalProjectRoot(cwd, projectRoot) {
+    const absolute = resolve(cwd, projectRoot);
+    return realpath(absolute).catch(() => absolute);
+}

package/dist/cli/runtime-selection.d.ts

@@ -0,0 +1,22 @@
+import { type RuntimeBackendChoice } from "../domain/runtime.js";
+export declare const RUNTIME_BACKEND_ENV_VAR = "TAPHOUND_RUNTIME_BACKEND";
+export declare class RuntimeBackendSelectionError extends Error {
+    constructor(value: string);
+}
+export declare class RuntimeBackendConfigError extends Error {
+    constructor(path: string, value: unknown);
+}
+export declare function readRuntimeBackendChoice(env: Record<string, string | undefined>): RuntimeBackendChoice;
+export interface RuntimeBackendInvocation {
+    env: Record<string, string | undefined>;
+    argv: readonly string[];
+    cwd: string;
+    readConfigFile: (path: string) => Promise<string>;
+}
+/**
+ * Resolves the effective runtime backend choice for one CLI invocation.
+ * An explicit `TAPHOUND_RUNTIME_BACKEND` wins over the config file so CI and
+ * experiments can override committed project state; `auto` defers to the
+ * config's `runtime.backend`, which itself defaults to `auto`.
+ */
+export declare function resolveRuntimeBackendChoiceFromInvocation(invocation: RuntimeBackendInvocation): Promise<RuntimeBackendChoice>;

package/dist/cli/runtime-selection.js

@@ -0,0 +1,92 @@
+import { resolve } from "node:path";
+import { RuntimeBackendChoiceSchema } from "../domain/runtime.js";
+import { CONFIG_PATH } from "../domain/workspace.js";
+export const RUNTIME_BACKEND_ENV_VAR = "TAPHOUND_RUNTIME_BACKEND";
+export class RuntimeBackendSelectionError extends Error {
+    constructor(value) {
+        super(`${RUNTIME_BACKEND_ENV_VAR} must be one of ${RuntimeBackendChoiceSchema.options
+            .map((option) => `"${option}"`)
+            .join(", ")}, received "${value}"`);
+        this.name = "RuntimeBackendSelectionError";
+    }
+}
+export class RuntimeBackendConfigError extends Error {
+    constructor(path, value) {
+        super(`runtime.backend in ${path} must be one of ${RuntimeBackendChoiceSchema.options
+            .map((option) => `"${option}"`)
+            .join(", ")}, received ${typeof value === "string" ? `"${value}"` : String(value)}`);
+        this.name = "RuntimeBackendConfigError";
+    }
+}
+export function readRuntimeBackendChoice(env) {
+    const raw = env[RUNTIME_BACKEND_ENV_VAR];
+    if (raw === undefined || raw.trim() === "") {
+        return "auto";
+    }
+    const value = raw.trim();
+    const parsed = RuntimeBackendChoiceSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new RuntimeBackendSelectionError(value);
+    }
+    return parsed.data;
+}
+function argvOptionValue(argv, name) {
+    const prefix = `--${name}=`;
+    let value;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === undefined) {
+            continue;
+        }
+        if (argument === `--${name}` && argv[index + 1] !== undefined) {
+            value = argv[index + 1] ?? undefined;
+        }
+        else if (argument.startsWith(prefix)) {
+            value = argument.slice(prefix.length);
+        }
+    }
+    return value;
+}
+async function configBackendChoice(invocation) {
+    const project = argvOptionValue(invocation.argv, "project")
+        ?? invocation.cwd;
+    const configPath = resolve(project, argvOptionValue(invocation.argv, "config") ?? CONFIG_PATH);
+    let text;
+    try {
+        text = await invocation.readConfigFile(configPath);
+    }
+    catch {
+        return "auto";
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return "auto";
+    }
+    const backend = parsed === null || typeof parsed !== "object"
+        ? undefined
+        : parsed.runtime?.backend;
+    if (backend === undefined) {
+        return "auto";
+    }
+    const choice = RuntimeBackendChoiceSchema.safeParse(backend);
+    if (!choice.success) {
+        throw new RuntimeBackendConfigError(configPath, backend);
+    }
+    return choice.data;
+}
+/**
+ * Resolves the effective runtime backend choice for one CLI invocation.
+ * An explicit `TAPHOUND_RUNTIME_BACKEND` wins over the config file so CI and
+ * experiments can override committed project state; `auto` defers to the
+ * config's `runtime.backend`, which itself defaults to `auto`.
+ */
+export async function resolveRuntimeBackendChoiceFromInvocation(invocation) {
+    const fromEnv = readRuntimeBackendChoice(invocation.env);
+    if (fromEnv !== "auto") {
+        return fromEnv;
+    }
+    return configBackendChoice(invocation);
+}

package/dist/cli/version.d.ts

@@ -0,0 +1 @@
+export declare function readCliVersion(): string;

package/dist/cli/version.js

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function readCliVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(here, "../../package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/cli/workspace-guard.d.ts

@@ -0,0 +1,2 @@
+import type { CliDependencies } from "./dependencies.js";
+export declare function prepareWorkspace(dependencies: Pick<CliDependencies, "workspaceLayout">, projectRoot: string): Promise<void>;

package/dist/cli/workspace-guard.js

@@ -0,0 +1,3 @@
+export async function prepareWorkspace(dependencies, projectRoot) {
+    await dependencies.workspaceLayout.ensureBuildLayout(projectRoot);
+}

package/dist/domain/binding-reference.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const BINDING_REFERENCE: RegExp;
+export declare function bindingName(value: string): string | undefined;
+export declare function checkBindingReferences(value: unknown, context: z.RefinementCtx, allowed: readonly (readonly (string | number)[])[], path?: (string | number)[]): void;

package/dist/domain/binding-reference.js

@@ -0,0 +1,23 @@
+export const BINDING_REFERENCE = /^\$\{([a-z][a-zA-Z0-9_]{0,31})\}$/;
+export function bindingName(value) {
+    return BINDING_REFERENCE.exec(value)?.[1];
+}
+export function checkBindingReferences(value, context, allowed, path = []) {
+    if (typeof value === "string") {
+        if (value.includes("${") && (bindingName(value) === undefined
+            || !allowed.some((candidate) => (candidate.length === path.length
+                && candidate.every((item, index) => item === path[index]))))) {
+            context.addIssue({
+                code: "custom",
+                path,
+                message: "Binding references are permitted only as exact values in approved fields"
+            });
+        }
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    for (const [key, item] of Object.entries(value)) {
+        checkBindingReferences(item, context, allowed, [...path, ...(Array.isArray(value) ? [Number(key)] : [key])]);
+    }
+}