taphound 0.2.0-dev.11 → 0.2.0-dev.13

package/dist/domain/diagnostics.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { FAILURE_CODES } from "./failure.js";
+import { RuntimeBackendChoiceSchema } from "./runtime.js";
+import { UiBackendIdSchema, UiBackendSelectionSchema } from "./ui-backend.js";
+import { UiCacheTelemetrySchema } from "./ui-cache.js";
+/**
+ * Diagnostics exist so a user can attach evidence to TapHound feedback
+ * without leaking their project. Every schema here is an allowlist: a field
+ * that is not declared cannot reach the journal or an exported bundle, and
+ * no field carries a path, package, Activity, Journey name, locator value,
+ * device serial, or free-text message.
+ */
+export const DIAGNOSTICS_EVENTS_FILE = "events.jsonl";
+export const DIAGNOSTICS_EVENTS_ROTATED_FILE = "events.1.jsonl";
+export const DIAGNOSTICS_SALT_FILE = "salt";
+export const DIAGNOSTICS_DISABLE_ENV_VAR = "TAPHOUND_DIAGNOSTICS";
+/** Upper bounds (exclusive) of the capture latency buckets; the last bucket is open. */
+export const UI_CAPTURE_LATENCY_BUCKETS_MS = [250, 500, 1000, 2000, 5000];
+export const UI_CAPTURE_FAILURE_KINDS = [
+    "timeout",
+    "cancelled",
+    "http4xx",
+    "http5xx",
+    "error"
+];
+const CountSchema = z.number().int().nonnegative();
+const DurationSchema = z.number().nonnegative();
+const VersionSchema = z.string().regex(/^[\w.+-]{1,64}$/);
+const TokenSchema = z.string().regex(/^[a-zA-Z][a-zA-Z\d]{0,31}$/);
+export const DiagnosticsHostSchema = z.strictObject({
+    platform: TokenSchema,
+    arch: TokenSchema,
+    node: VersionSchema
+});
+export const UiBackendTelemetrySchema = z.strictObject({
+    backend: UiBackendIdSchema,
+    captures: CountSchema,
+    failures: z.strictObject({
+        timeout: CountSchema,
+        cancelled: CountSchema,
+        http4xx: CountSchema,
+        http5xx: CountSchema,
+        error: CountSchema
+    }),
+    totalMs: DurationSchema,
+    maxMs: DurationSchema,
+    latencyBuckets: z.array(CountSchema).length(UI_CAPTURE_LATENCY_BUCKETS_MS.length + 1),
+    sessionRecoveries: CountSchema,
+    sessionRecoveryFailures: CountSchema
+});
+/** One journal line: a finished CLI invocation. */
+export const CommandEventSchema = z.strictObject({
+    version: z.literal(1),
+    kind: z.literal("command"),
+    at: z.iso.datetime(),
+    taphoundVersion: VersionSchema,
+    host: DiagnosticsHostSchema,
+    command: z.string().regex(/^[a-z][a-z-]*(?: [a-z][a-z-]*){0,3}$/),
+    flags: z.array(TokenSchema),
+    durationMs: DurationSchema,
+    exitCode: z.number().int(),
+    status: TokenSchema.optional(),
+    failureCode: z.enum(FAILURE_CODES).optional(),
+    runId: z.string().regex(/^[\w.-]{1,128}$/).optional(),
+    ui: z.array(UiBackendTelemetrySchema)
+});
+const RunAliasSchema = z.string().regex(/^run#\d+$/);
+const ActivityAliasSchema = z.string().regex(/^activity#\d+$/);
+const DeviceAliasSchema = z.string().regex(/^device#\d+$/);
+const StepResultSchema = z.enum(["passed", "failed", "notRun", "manualRequired"]);
+const ActivityCheckSummarySchema = z.strictObject({
+    status: StepResultSchema,
+    expected: ActivityAliasSchema,
+    actual: ActivityAliasSchema.optional()
+});
+export const StepSummarySchema = z.strictObject({
+    index: CountSchema,
+    action: z.enum([
+        "click",
+        "longClick",
+        "inputText",
+        "swipe",
+        "scrollTo",
+        "back",
+        "wait",
+        "bridge"
+    ]),
+    status: StepResultSchema,
+    device: DeviceAliasSchema.optional(),
+    durationMs: DurationSchema,
+    locator: z.strictObject({
+        status: z.enum(["found", "failed", "notRun"]),
+        matchedBy: z.enum(["resourceId", "text", "contentDescription", "anchor"]).optional(),
+        requestedFields: z.array(z.enum(["resourceId", "text", "contentDescription", "index", "within"])),
+        locatorId: z.string().regex(/^[a-f\d]{16}$/).optional(),
+        anchorStatus: z.enum(["resolved", "locatorFallback", "failed"]).optional(),
+        fallbackUsed: z.boolean()
+    }).optional(),
+    idle: z.strictObject({
+        status: z.enum(["stable", "timeout", "cancelled", "notRun"]),
+        polls: CountSchema,
+        durationMs: DurationSchema.optional(),
+        samplingDurationMs: DurationSchema.optional(),
+        strategy: z.enum(["hybrid", "layoutDiff", "frameStats", "structural"]).optional(),
+        backend: z.enum(["uiautomator", "androidCli", "gfxFrameStats", "mobileMcp"]).optional(),
+        fallbackUsed: z.boolean().optional(),
+        frameActivityDetected: z.boolean().optional(),
+        lastDiffCount: CountSchema.optional()
+    }).optional(),
+    activity: z.strictObject({
+        before: ActivityCheckSummarySchema,
+        after: ActivityCheckSummarySchema
+    }).optional(),
+    expectation: z.strictObject({
+        type: z.enum(["activity", "element", "logcat", "logcatEvent"]),
+        status: StepResultSchema,
+        code: z.enum(FAILURE_CODES).optional()
+    }).optional(),
+    scroll: z.strictObject({
+        swipesUsed: CountSchema,
+        maxSwipes: CountSchema
+    }).optional()
+});
+const LayerStatusSchema = StepResultSchema;
+export const RunSummarySchema = z.strictObject({
+    run: RunAliasSchema,
+    status: z.enum(["passed", "failed", "error", "manualRequired"]),
+    durationMs: DurationSchema,
+    journey: z.string().regex(/^journey#\d+$/),
+    devices: z.array(z.strictObject({
+        device: DeviceAliasSchema,
+        uiBackend: z.strictObject({
+            id: UiBackendIdSchema,
+            adapterVersion: VersionSchema,
+            engineVersion: VersionSchema.optional()
+        }).optional(),
+        uiCache: UiCacheTelemetrySchema.optional()
+    })),
+    tools: z.partialRecord(z.enum(["node", "adb", "android"]), VersionSchema),
+    layers: z.strictObject({
+        run: LayerStatusSchema,
+        structural: LayerStatusSchema,
+        activityCheckpoint: LayerStatusSchema,
+        explicitExpect: LayerStatusSchema,
+        collection: LayerStatusSchema
+    }),
+    primaryFailure: z.strictObject({
+        code: z.enum(FAILURE_CODES),
+        phase: TokenSchema,
+        stepIndex: CountSchema.optional()
+    }).optional(),
+    secondaryErrorCodes: z.array(z.enum(FAILURE_CODES)),
+    fallbackUsed: z.boolean(),
+    logcatEvidence: z.array(z.strictObject({
+        device: DeviceAliasSchema,
+        droppedLines: CountSchema,
+        droppedBytes: CountSchema
+    })),
+    steps: z.array(StepSummarySchema)
+});
+export const DiagnosticsConfigSummarySchema = z.strictObject({
+    idle: z.strictObject({
+        strategy: z.enum(["hybrid", "layoutDiff", "frameStats", "structural"]),
+        pollIntervalMs: CountSchema,
+        stablePolls: CountSchema,
+        timeoutMs: CountSchema,
+        ignoreCursorBlink: z.boolean().optional(),
+        ignoreLayoutDrift: z.boolean().optional(),
+        deviceProfiles: CountSchema
+    }),
+    ui: z.strictObject({
+        backend: UiBackendSelectionSchema,
+        snapshotTimeoutMs: CountSchema.optional(),
+        cacheEnabled: z.boolean().optional()
+    }).optional(),
+    runtime: z.strictObject({
+        backend: RuntimeBackendChoiceSchema
+    }).optional()
+});
+export const DiagnosticsBundleSchema = z.strictObject({
+    version: z.literal(1),
+    generatedAt: z.iso.datetime(),
+    taphoundVersion: VersionSchema,
+    host: DiagnosticsHostSchema,
+    config: DiagnosticsConfigSummarySchema.optional(),
+    journal: z.strictObject({
+        events: z.array(CommandEventSchema.extend({
+            runId: RunAliasSchema.optional()
+        })),
+        skippedLines: CountSchema
+    }),
+    runs: z.array(RunSummarySchema)
+});

package/dist/domain/failure.js

@@ -81,7 +81,7 @@ const EXIT_CODES = {
     DEVICE_UNAVAILABLE: 3,
     UI_BACKEND_UNAVAILABLE: 3,
     RUNTIME_CAPABILITY_MISSING: 3,
-    UI_SNAPSHOT_FAILED: 1,
+    UI_SNAPSHOT_FAILED: 3,
     UI_SNAPSHOT_INVALID: 1,
     APP_NOT_INSTALLED: 3,
     APP_LAUNCH_FAILED: 1,

package/dist/domain/report.d.ts

@@ -150,8 +150,8 @@ export declare const StepReportSchema: z.ZodObject<{
     idle: z.ZodOptional<z.ZodObject<{
         status: z.ZodEnum<{
             cancelled: "cancelled";
-            notRun: "notRun";
             timeout: "timeout";
+            notRun: "notRun";
             stable: "stable";
         }>;
         polls: z.ZodNumber;
@@ -661,8 +661,8 @@ export declare const TapHoundReportV4Schema: z.ZodObject<{
         idle: z.ZodOptional<z.ZodObject<{
             status: z.ZodEnum<{
                 cancelled: "cancelled";
-                notRun: "notRun";
                 timeout: "timeout";
+                notRun: "notRun";
                 stable: "stable";
             }>;
             polls: z.ZodNumber;
@@ -851,6 +851,10 @@ export declare const TapHoundReportV4Schema: z.ZodObject<{
     logcatEvidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
         role: z.ZodString;
         status: z.ZodLiteral<"incomplete">;
+        expectationImpact: z.ZodEnum<{
+            none: "none";
+            possible: "possible";
+        }>;
         droppedLines: z.ZodNumber;
         droppedBytes: z.ZodNumber;
         lastDroppedAtMs: z.ZodOptional<z.ZodNumber>;
@@ -1288,8 +1292,8 @@ export declare const TapHoundReportSchema: z.ZodObject<{
         idle: z.ZodOptional<z.ZodObject<{
             status: z.ZodEnum<{
                 cancelled: "cancelled";
-                notRun: "notRun";
                 timeout: "timeout";
+                notRun: "notRun";
                 stable: "stable";
             }>;
             polls: z.ZodNumber;
@@ -1478,6 +1482,10 @@ export declare const TapHoundReportSchema: z.ZodObject<{
     logcatEvidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
         role: z.ZodString;
         status: z.ZodLiteral<"incomplete">;
+        expectationImpact: z.ZodEnum<{
+            none: "none";
+            possible: "possible";
+        }>;
         droppedLines: z.ZodNumber;
         droppedBytes: z.ZodNumber;
         lastDroppedAtMs: z.ZodOptional<z.ZodNumber>;

package/dist/domain/report.js

@@ -264,6 +264,7 @@ const ReportFields = {
     logcatEvidence: z.array(z.strictObject({
         role: DeviceRoleSchema,
         status: z.literal("incomplete"),
+        expectationImpact: z.enum(["none", "possible"]),
         droppedLines: z.number().int().positive(),
         droppedBytes: z.number().int().positive(),
         lastDroppedAtMs: z.number().nonnegative().optional()

package/dist/domain/verify-receipt.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const VERIFY_RECEIPT_FILE = "receipt.json";
+/**
+ * A process receipt that `verify --journey` writes beside the report it
+ * published. `argv` is the normalized invocation TapHound actually ran:
+ * absolute project and Journey paths and the selected device serial, so a
+ * Workflow checker never has to trust a hand-written record.
+ */
+export declare const VerifyReceiptSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    argv: z.ZodArray<z.ZodString>;
+    exitCode: z.ZodNumber;
+    journeySha256: z.ZodString;
+    reportPath: z.ZodString;
+    reportSha256: z.ZodString;
+}, z.core.$strict>;
+export type VerifyReceipt = z.infer<typeof VerifyReceiptSchema>;

package/dist/domain/verify-receipt.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const VERIFY_RECEIPT_FILE = "receipt.json";
+const DigestSchema = z.string().regex(/^[a-f\d]{64}$/);
+/**
+ * A process receipt that `verify --journey` writes beside the report it
+ * published. `argv` is the normalized invocation TapHound actually ran:
+ * absolute project and Journey paths and the selected device serial, so a
+ * Workflow checker never has to trust a hand-written record.
+ */
+export const VerifyReceiptSchema = z.strictObject({
+    version: z.literal(1),
+    argv: z.array(z.string().min(1)).min(1),
+    exitCode: z.number().int().min(0).max(4),
+    journeySha256: DigestSchema,
+    reportPath: z.string().min(1),
+    reportSha256: DigestSchema
+});

package/dist/domain/workspace.d.ts

@@ -12,11 +12,22 @@ export declare const JOURNEY_SOURCES_DIR = ".taphound/sources";
 export declare const JOURNEYS_DIR = ".taphound/journeys";
 export declare const CONTRACTS_DIR = ".taphound/contracts";
 export declare const BASELINES_DIR = ".taphound/baselines";
+export declare const BRIEFS_DIR = ".taphound/briefs";
+export declare const SUITES_DIR = ".taphound/suites";
+/**
+ * Journey Briefs are committed project material: standalone Briefs live under
+ * `.taphound/briefs/`, Case Suite Briefs under `.taphound/suites/<suite-id>/`.
+ * Nothing else in the project may be bound as a Brief.
+ */
+export declare const JOURNEY_BRIEF_ROOTS: readonly [".taphound/briefs", ".taphound/suites"];
+export declare function isJourneyBriefPath(path: string): boolean;
 export declare const BUILD_DIR = ".taphound/build";
 export declare const GENERATIONS_DIR = ".taphound/build/generations";
 export declare const JOBS_DIR = ".taphound/build/jobs";
 export declare const DEFAULT_ARTIFACTS_DIR = ".taphound/build/runs";
 export declare const WORKFLOWS_DIR = ".taphound/build/workflows";
+export declare const DIAGNOSTICS_LOG_DIR = ".taphound/build/log";
+export declare const DIAGNOSTICS_EXPORT_DIR = ".taphound/build/diagnostics";
 export declare function workflowManifestPath(caseId: string): string;
 export declare const BUILD_IGNORE_FILE = ".taphound/.gitignore";
 export declare const BUILD_IGNORE_CONTENT = "build/\n";

package/dist/domain/workspace.js

@@ -14,11 +14,25 @@ export const JOURNEY_SOURCES_DIR = `${TAPHOUND_DIR}/sources`;
 export const JOURNEYS_DIR = `${TAPHOUND_DIR}/journeys`;
 export const CONTRACTS_DIR = `${TAPHOUND_DIR}/contracts`;
 export const BASELINES_DIR = `${TAPHOUND_DIR}/baselines`;
+export const BRIEFS_DIR = `${TAPHOUND_DIR}/briefs`;
+export const SUITES_DIR = `${TAPHOUND_DIR}/suites`;
+/**
+ * Journey Briefs are committed project material: standalone Briefs live under
+ * `.taphound/briefs/`, Case Suite Briefs under `.taphound/suites/<suite-id>/`.
+ * Nothing else in the project may be bound as a Brief.
+ */
+export const JOURNEY_BRIEF_ROOTS = [BRIEFS_DIR, SUITES_DIR];
+export function isJourneyBriefPath(path) {
+    const normalized = posix.normalize(path.replaceAll("\\", "/"));
+    return JOURNEY_BRIEF_ROOTS.some((root) => normalized.startsWith(`${root}/`));
+}
 export const BUILD_DIR = `${TAPHOUND_DIR}/build`;
 export const GENERATIONS_DIR = `${BUILD_DIR}/generations`;
 export const JOBS_DIR = `${BUILD_DIR}/jobs`;
 export const DEFAULT_ARTIFACTS_DIR = `${BUILD_DIR}/runs`;
 export const WORKFLOWS_DIR = `${BUILD_DIR}/workflows`;
+export const DIAGNOSTICS_LOG_DIR = `${BUILD_DIR}/log`;
+export const DIAGNOSTICS_EXPORT_DIR = `${BUILD_DIR}/diagnostics`;
 export function workflowManifestPath(caseId) {
     if (!/^[a-z][a-z0-9-]{0,63}$/.test(caseId)) {
         throw new Error("Workflow Case id must be a safe lowercase path component");

package/dist/ports/diagnostics.d.ts

@@ -0,0 +1,15 @@
+import type { CommandEvent } from "../domain/diagnostics.js";
+import type { UiBackendId } from "../domain/ui-backend.js";
+/** Receives UI backend timing facts; never error text. */
+export interface UiCaptureObserver {
+    captured: (backend: UiBackendId, durationMs: number, error?: unknown) => void;
+    sessionRecovered: (backend: UiBackendId, succeeded: boolean) => void;
+}
+/** The local, Git-ignored diagnostics journal of one host project. */
+export interface DiagnosticsJournal {
+    append: (projectRoot: string, event: CommandEvent) => Promise<void>;
+    /** Raw journal lines, oldest first, including the rotated file. */
+    readLines: (projectRoot: string) => Promise<readonly string[]>;
+    /** A per-project random salt that never leaves the host. */
+    salt: (projectRoot: string) => Promise<Buffer>;
+}

package/dist/ports/diagnostics.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taphound",
-  "version": "0.2.0-dev.11",
+  "version": "0.2.0-dev.13",
   "description": "Deterministic app journey recording and verification",
   "license": "Apache-2.0",
   "repository": {
@@ -25,12 +25,13 @@
   },
   "type": "module",
   "bin": {
-    "taphound": "./dist/cli/main.js"
+    "taphound": "dist/cli/main.js"
   },
   "files": [
     "dist",
     "assets/brand/taphound-mark.svg",
-    "assets/skills"
+    "assets/skills",
+    "scripts/feedback-pack.mjs"
   ],
   "engines": {
     "node": ">=22"