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

package/dist/cli/commands/journey.js

@@ -0,0 +1,382 @@
+import { extname, resolve } from "node:path";
+import { Command } from "commander";
+import { z } from "zod";
+import { JourneyCheckError, JourneyCheckService } from "../../application/journey/journey-check-service.js";
+import { JourneyPromotionError, JourneyPromoter } from "../../application/journey/journey-promoter.js";
+import { JourneyRetireError, JourneyRetirer } from "../../application/journey/journey-retirer.js";
+import { JourneyCompositionError } from "../../application/journey/journey-resolver.js";
+import { ContextLoadError } from "../../application/context/context-loader.js";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { JourneyResolutionManifestSchema, ResolvedJourneyPathSchema } from "../../domain/journey-composition.js";
+import { JourneySchema } from "../../domain/journey.js";
+import { assertArtifactDirectory, CONFIG_PATH, CONTEXT_INDEX_PATH } from "../../domain/workspace.js";
+import { contextLoadHint, errorMessage, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
+import { canonicalProjectRoot } from "../project-root.js";
+function manifestPath(outputPath) {
+    const extension = extname(outputPath);
+    return extension.toLowerCase() === ".json"
+        ? `${outputPath.slice(0, -extension.length)}.resolve.json`
+        : `${outputPath}.resolve.json`;
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function requireComposition(dependencies) {
+    if (dependencies.journeyResolver === undefined
+        || dependencies.journeyCompositionStore === undefined) {
+        throw new Error("Journey composition runtime is unavailable");
+    }
+    return {
+        resolver: dependencies.journeyResolver,
+        store: dependencies.journeyCompositionStore
+    };
+}
+function writeFailure(dependencies, options, error) {
+    const known = error instanceof JourneyCompositionError
+        || error instanceof JourneyCheckError
+        || error instanceof JourneyPromotionError
+        || error instanceof JourneyRetireError
+        || error instanceof ContextLoadError
+        || error instanceof z.ZodError;
+    const hint = error instanceof ContextLoadError
+        ? contextLoadHint(error)
+        : undefined;
+    const output = {
+        status: "error",
+        exitCode: known ? 2 : 4,
+        failure: {
+            code: error instanceof JourneyCompositionError
+                ? error.code
+                : error instanceof JourneyCheckError
+                    ? error.code
+                    : error instanceof JourneyPromotionError
+                        ? error.code
+                        : error instanceof JourneyRetireError
+                            ? error.code
+                            : error instanceof ContextLoadError
+                                ? error.code
+                                : error instanceof z.ZodError
+                                    ? "CONFIG_INVALID"
+                                    : "INTERNAL_ERROR",
+            message: errorMessage(error),
+            ...(hint === undefined ? {} : { hint })
+        }
+    };
+    if (options.json === true) {
+        writeJson(dependencies.stdout, output);
+    }
+    else {
+        writeLine(dependencies.stderr, output.failure.message);
+    }
+    dependencies.setExitCode(output.exitCode);
+}
+function lifecycleSummary(entries) {
+    const counts = {
+        draft: 0,
+        verified: 0,
+        promoted: 0,
+        suspect: 0,
+        stale: 0,
+        retired: 0
+    };
+    for (const entry of entries) {
+        if (entry.lifecycle !== undefined) {
+            counts[entry.lifecycle] += 1;
+        }
+    }
+    return counts;
+}
+function createResolveCommand(dependencies) {
+    return new Command("resolve")
+        .description("Resolve a composed Journey source into Journey v1")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .requiredOption("--source <path>", "Project-relative Journey source path")
+        .requiredOption("--output <path>", "Project-relative Journey v1 output path")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        try {
+            await prepareWorkspace(dependencies, options.project);
+            const composition = requireComposition(dependencies);
+            const resolution = await composition.resolver.resolve({
+                projectRoot: options.project,
+                sourcePath: options.source
+            });
+            const journey = JourneySchema.parse(resolution.journey);
+            const manifest = JourneyResolutionManifestSchema.parse(resolution.manifest);
+            const journeyPath = ResolvedJourneyPathSchema.parse(options.output);
+            const sidecarPath = manifestPath(journeyPath);
+            await composition.store.writeText({
+                projectRoot: options.project,
+                relativePath: journeyPath,
+                content: serialize(journey)
+            });
+            await composition.store.writeText({
+                projectRoot: options.project,
+                relativePath: sidecarPath,
+                content: serialize(manifest)
+            });
+            const output = {
+                status: "resolved",
+                exitCode: 0,
+                journeyPath,
+                manifestPath: sidecarPath,
+                journeySha256: manifest.journey.sha256,
+                resolutionSha256: manifest.resolutionSha256,
+                stepCount: journey.steps.length,
+                flows: manifest.expansion
+            };
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stdout, `Resolved ${journey.name}: ${journeyPath}`);
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, options, error);
+        }
+    });
+}
+function createListFlowsCommand(dependencies) {
+    return new Command("list-flows")
+        .description("List and validate reusable local Flows")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--json", "Emit one machine-readable JSON value")
+        .option("--include-external", "Also list External Flows")
+        .action(async (options) => {
+        try {
+            await prepareWorkspace(dependencies, options.project);
+            const entries = await requireComposition(dependencies).resolver.listFlows(options.project);
+            const output = {
+                status: "listed",
+                exitCode: 0,
+                flows: entries
+            };
+            if (options.includeExternal === true) {
+                if (dependencies.externalFlowResolver === undefined) {
+                    throw new Error("External Flow resolver is unavailable");
+                }
+                const externalEntries = await dependencies.externalFlowResolver.list(options.project);
+                output.externalFlows = [...externalEntries];
+            }
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else if (entries.length === 0
+                && output.externalFlows === undefined) {
+                writeLine(dependencies.stdout, "No reusable Flows found");
+            }
+            else {
+                const lines = entries.map((entry) => `${entry.name}: ${entry.status}`);
+                if (output.externalFlows !== undefined) {
+                    if (output.externalFlows.length === 0) {
+                        lines.push("No External Flows found");
+                    }
+                    else {
+                        for (const entry of output.externalFlows) {
+                            const external = entry;
+                            lines.push(`${external.name}: ${external.status} (external, ${external.source})`);
+                        }
+                    }
+                }
+                writeLine(dependencies.stdout, lines.join("\n"));
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, options, error);
+        }
+    });
+}
+function checkEntryLine(entry) {
+    if (entry.reasons.length === 0) {
+        return `${entry.name}: ${entry.status}`;
+    }
+    const detail = entry.reasons.map((reason) => {
+        if (reason === "module-drift" || reason === "module-missing") {
+            const ids = entry.driftedModules
+                .filter((module) => (reason === "module-drift"
+                ? module.reason === "sha256"
+                : module.reason === "missing"))
+                .map((module) => module.id);
+            return `${reason}: ${ids.join(", ")}`;
+        }
+        return reason;
+    });
+    return `${entry.name}: ${entry.status} (${detail.join(", ")})`;
+}
+function createCheckCommand(dependencies) {
+    return new Command("check")
+        .description("Check committed Journeys against live project bindings")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
+        .option("--context <path>", "Project Context index path")
+        .option("--json", "Emit one machine-readable JSON value")
+        .option("--strict", "Exit non-zero when any Journey is not fresh")
+        .action(async (options) => {
+        try {
+            const projectRoot = await canonicalProjectRoot(dependencies.cwd(), options.project);
+            await prepareWorkspace(dependencies, projectRoot);
+            const composition = requireComposition(dependencies);
+            let config;
+            try {
+                config = TapHoundConfigSchema.parse(await dependencies.readJson(resolve(projectRoot, options.config)));
+                assertArtifactDirectory(projectRoot, config.artifactsDir);
+            }
+            catch (error) {
+                throw new JourneyCheckError("CONFIG_INVALID", error instanceof Error ? error.message : String(error), { cause: error });
+            }
+            const index = await dependencies.contextLoader.readIndex({
+                projectRoot,
+                contextPath: resolve(projectRoot, options.context ?? CONTEXT_INDEX_PATH)
+            });
+            const project = await dependencies.projectDescriber.describe({
+                projectRoot,
+                config,
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            const result = await new JourneyCheckService({
+                store: composition.store
+            }).check({
+                projectRoot,
+                config,
+                project,
+                bundle: index.bundle
+            });
+            const notFresh = result.summary.total - result.summary.fresh;
+            const exitCode = options.strict === true && notFresh > 0 ? 1 : 0;
+            const lifecycleCounts = lifecycleSummary(result.entries);
+            const output = {
+                status: "checked",
+                exitCode,
+                strict: options.strict === true,
+                summary: result.summary,
+                lifecycle: lifecycleCounts,
+                journeys: result.entries
+            };
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else if (result.entries.length === 0) {
+                writeLine(dependencies.stdout, "No Journeys found");
+            }
+            else {
+                const lines = result.entries.map(checkEntryLine);
+                for (const entry of result.entries) {
+                    if (entry.status === "invalid" && entry.message !== undefined) {
+                        lines.push(`  ${entry.message}`);
+                    }
+                }
+                lines.push(`Checked ${String(result.summary.total)} Journeys: `
+                    + `${String(result.summary.fresh)} fresh, `
+                    + `${String(result.summary.stale)} stale, `
+                    + `${String(result.summary.noMeta)} no-meta, `
+                    + `${String(result.summary.invalid)} invalid`);
+                lines.push(`Lifecycle: `
+                    + Object.entries(lifecycleCounts)
+                        .filter(([, count]) => count > 0)
+                        .map(([state, count]) => `${state} ${String(count)}`)
+                        .join(", "));
+                writeLine(dependencies.stdout, lines.join("\n"));
+            }
+            dependencies.setExitCode(exitCode);
+        }
+        catch (error) {
+            writeFailure(dependencies, options, error);
+        }
+    });
+}
+function createPromoteCommand(dependencies) {
+    return new Command("promote")
+        .description("Promote a replay-verified Journey into a durable asset")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .requiredOption("--journey <path>", "Project-relative Journey path")
+        .requiredOption("--reason <text>", "Why this Journey is worth keeping")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        try {
+            const projectRoot = options.project;
+            await prepareWorkspace(dependencies, projectRoot);
+            const composition = requireComposition(dependencies);
+            const result = await new JourneyPromoter({
+                store: composition.store
+            }).promote({
+                projectRoot,
+                journeyPath: options.journey,
+                reason: options.reason,
+                now: new Date()
+            });
+            const output = {
+                status: "promoted",
+                exitCode: 0,
+                journeyPath: result.journeyPath,
+                metaPath: result.metaPath,
+                generationId: result.generationId,
+                promotedAt: result.promotedAt
+            };
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stdout, `Promoted ${result.journeyPath} (${result.generationId})`);
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, options, error);
+        }
+    });
+}
+function createRetireCommand(dependencies) {
+    return new Command("retire")
+        .description("Retire a Journey; its replay can no longer be trusted")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .requiredOption("--journey <path>", "Project-relative Journey path")
+        .requiredOption("--reason <text>", "Why this Journey is retired")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        try {
+            const projectRoot = options.project;
+            await prepareWorkspace(dependencies, projectRoot);
+            const composition = requireComposition(dependencies);
+            const result = await new JourneyRetirer({
+                store: composition.store
+            }).retire({
+                projectRoot,
+                journeyPath: options.journey,
+                reason: options.reason,
+                now: new Date()
+            });
+            const output = {
+                status: "retired",
+                exitCode: 0,
+                journeyPath: result.journeyPath,
+                metaPath: result.metaPath,
+                retiredAt: result.retiredAt
+            };
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stdout, `Retired ${result.journeyPath}`);
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, options, error);
+        }
+    });
+}
+export function createJourneyCommand(dependencies) {
+    return new Command("journey")
+        .description("Compose reusable Flows into runnable Journeys")
+        .addCommand(createResolveCommand(dependencies))
+        .addCommand(createListFlowsCommand(dependencies))
+        .addCommand(createCheckCommand(dependencies))
+        .addCommand(createPromoteCommand(dependencies))
+        .addCommand(createRetireCommand(dependencies));
+}

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

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

package/dist/cli/commands/knowledge.js

@@ -0,0 +1,93 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { CONFIG_PATH } from "../../domain/workspace.js";
+import { errorMessage, writeJson, writeLine } from "../output.js";
+function requireKnowledge(dependencies) {
+    if (dependencies.knowledge === undefined) {
+        throw new Error("Knowledge services are unavailable");
+    }
+    return dependencies.knowledge;
+}
+function failure(dependencies, options, error) {
+    const output = {
+        status: "failed",
+        exitCode: 2,
+        code: "KNOWLEDGE_INVALID",
+        message: errorMessage(error)
+    };
+    if (options.json === true) {
+        writeJson(dependencies.stdout, output);
+    }
+    else {
+        writeLine(dependencies.stderr, `${output.code}: ${output.message}`);
+    }
+    dependencies.setExitCode(2);
+}
+function statusCommand(dependencies) {
+    return new Command("status")
+        .description("Validate and hash the committed Knowledge Registry")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        try {
+            const bundle = await requireKnowledge(dependencies).load({
+                projectRoot: options.project
+            });
+            const output = {
+                status: "valid",
+                exitCode: 0,
+                knowledgeHash: bundle.knowledgeHash,
+                revision: bundle.index.revision,
+                packageName: bundle.index.packageName,
+                counts: {
+                    anchors: bundle.anchors.length,
+                    screens: bundle.screens.length
+                }
+            };
+            if (options.json === true)
+                writeJson(dependencies.stdout, output);
+            else
+                writeLine(dependencies.stdout, `Knowledge ${bundle.knowledgeHash} (${String(bundle.anchors.length)} Anchors, ${String(bundle.screens.length)} Screens)`);
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            failure(dependencies, options, error);
+        }
+    });
+}
+function rehashCommand(dependencies) {
+    return new Command("rehash")
+        .description("Rebuild the Knowledge index from committed Anchor and Screen documents")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        try {
+            const config = TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config)));
+            const result = await requireKnowledge(dependencies).rehash({
+                projectRoot: options.project,
+                packageName: config.run.packageName
+            });
+            const output = {
+                status: result.changed ? "rehashed" : "unchanged",
+                exitCode: 0,
+                ...result
+            };
+            if (options.json === true)
+                writeJson(dependencies.stdout, output);
+            else
+                writeLine(dependencies.stdout, `Knowledge ${output.status} at revision ${String(result.revision)} (${String(result.anchors)} Anchors, ${String(result.screens)} Screens)`);
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            failure(dependencies, options, error);
+        }
+    });
+}
+export function createKnowledgeCommand(dependencies) {
+    return new Command("knowledge")
+        .description("Validate and index committed semantic Anchors and Screens")
+        .addCommand(statusCommand(dependencies))
+        .addCommand(rehashCommand(dependencies));
+}

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

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

package/dist/cli/commands/observe.js

@@ -0,0 +1,127 @@
+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 { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+function summarize(report) {
+    const logcatLine = report.logcat === undefined
+        ? "logcat: omitted"
+        : `logcat: ${String(report.logcat.length)} line(s)`;
+    return [
+        `TapHound observe: ${report.packageName} on ${report.deviceSerial}`,
+        `activity: ${report.activity ?? "(unavailable)"}`,
+        `foreground: ${report.foreground.packageName}/${report.foreground.activity}`,
+        `ui backend: ${report.uiBackend.id}`,
+        `ui capture: ${String(report.uiCaptureDurationMs)}ms`,
+        ...(report.uiCache === undefined
+            ? []
+            : [`ui cache: ${String(report.uiCache.hits)} hit(s), ${String(report.uiCache.misses)} miss(es), ${String(report.uiCache.capturesSaved)} capture(s) saved`]),
+        `layout: ${String(report.layout.length)} element(s)`,
+        logcatLine
+    ].join("\n");
+}
+export function createObserveCommand(dependencies) {
+    return new Command("observe")
+        .description("Capture a point-in-time device snapshot for the configured package")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
+        .option("--device <serial>", "Select an online Android device")
+        .option("--logcat-lines <n>", "Dump the last N logcat lines into the report", (value) => Number.parseInt(value, 10))
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        if (options.logcatLines !== undefined
+            && (!Number.isFinite(options.logcatLines) || options.logcatLines < 0
+                || !Number.isInteger(options.logcatLines))) {
+            const output = failureOutput(2, "CONFIG_INVALID", "--logcat-lines must be a non-negative integer");
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(2);
+            return;
+        }
+        let config;
+        try {
+            const rawConfig = await dependencies.readJson(resolve(options.project, options.config));
+            config = TapHoundConfigSchema.parse(rawConfig);
+        }
+        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(2);
+            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 (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");
+            }
+            const observer = dependencies.observer(config.ui?.snapshotTimeoutMs ?? config.idle.timeoutMs, config.ui?.backend ?? "auto", config.ui?.cacheEnabled ?? true);
+            const report = await observer.observe({
+                packageName: config.run.packageName,
+                deviceSerial,
+                ...(options.logcatLines === undefined
+                    ? {}
+                    : { logcatLines: options.logcatLines }),
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            if (options.json === true) {
+                writeJson(dependencies.stdout, {
+                    status: "observed",
+                    exitCode: 0,
+                    report
+                });
+            }
+            else {
+                writeLine(dependencies.stdout, summarize(report));
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (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(exitCode);
+        }
+    });
+}

package/dist/cli/commands/project.js

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { TapHoundConfigSchema } from "../../domain/config.js";
+import { CONFIG_PATH } from "../../domain/workspace.js";
 import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
 function writeFailure(dependencies, options, exitCode, error) {
     const output = failureOutput(exitCode, exitCode === 2 ? "CONFIG_INVALID" : "INTERNAL_ERROR", errorMessage(error));
@@ -16,7 +17,7 @@ export function createProjectCommand(dependencies) {
     const describe = new Command("describe")
         .description("Describe stable Android project facts")
         .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("--json", "Emit one machine-readable JSON value")
         .action(async (options) => {
         let config;