agent-qa 0.0.1 → 0.1.2

package/dist/index.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { getAgentQaVersion } from "@vostride/agent-qa-core";
+export * from "@vostride/agent-qa-core";
+
+// src/config.ts
+import { readFile } from "fs/promises";
+import { dirname, resolve as resolvePath } from "path";
+import { parse as parseYaml } from "yaml";
+import pc from "picocolors";
+import { AgentQaConfigSchema, loadLLMAuthPlugins } from "@vostride/agent-qa-core";
+var ENV_MAPPING = {
+  AGENT_QA_DASHBOARD_PORT: "services.dashboard.port",
+  AGENT_QA_MCP_PORT: "services.mcp.port",
+  AGENT_QA_CACHE_DIR: "services.cache.dir",
+  AGENT_QA_CACHE_TTL: "services.cache.ttl",
+  AGENT_QA_LOG_LEVEL: "services.logging.level",
+  AGENT_QA_HEADLESS: "use.browser.headless"
+};
+function setNestedValue(obj, path, value) {
+  const parts = path.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (!(key in current) || typeof current[key] !== "object" || current[key] === null) {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+function parseEnvValue(key, value) {
+  if (key === "AGENT_QA_DASHBOARD_PORT" || key === "AGENT_QA_MCP_PORT") {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isInteger(parsed)) return parsed;
+  }
+  if (key === "AGENT_QA_HEADLESS") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") return true;
+    if (normalized === "false") return false;
+  }
+  return value;
+}
+async function loadConfigFile(configPath) {
+  try {
+    const content = await readFile(configPath, "utf-8");
+    return parseYaml(content) ?? {};
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+async function loadRequiredConfigFile(configPath) {
+  try {
+    const content = await readFile(configPath, "utf-8");
+    return parseYaml(content) ?? {};
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`Config file not found: ${configPath}`);
+    }
+    throw err;
+  }
+}
+function loadEnvOverrides() {
+  const result = {};
+  for (const [envKey, configPath] of Object.entries(ENV_MAPPING)) {
+    const value = process.env[envKey];
+    if (value !== void 0) {
+      setNestedValue(result, configPath, parseEnvValue(envKey, value));
+    }
+  }
+  return result;
+}
+function isPlainObject(val) {
+  return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+function mergeConfigs(file, env, flags) {
+  return deepMerge(deepMerge(file ?? {}, env), flags);
+}
+function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) return override;
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    if (key in result && isPlainObject(result[key]) && isPlainObject(override[key])) {
+      result[key] = deepMerge(result[key], override[key]);
+    } else {
+      result[key] = override[key];
+    }
+  }
+  return result;
+}
+function mergeWithTestConfig(globalConfig, testConfig, flagOverrides) {
+  return deepMerge(deepMerge(globalConfig ?? {}, testConfig ?? {}), flagOverrides);
+}
+function normalizeConfigForValidation(config) {
+  if (!isPlainObject(config)) return config;
+  const normalized = deepMerge({}, config);
+  const use = normalized.use;
+  if (isPlainObject(use)) {
+    delete use.headless;
+  }
+  return normalized;
+}
+function mergeUseBlocks(globalUse, suiteUse, testUse, cliFlags) {
+  return deepMerge(
+    deepMerge(
+      deepMerge(globalUse ?? {}, suiteUse ?? {}),
+      testUse ?? {}
+    ),
+    cliFlags
+  );
+}
+function flattenObject(obj, prefix = "") {
+  const result = {};
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    if (prefix) result[prefix] = obj;
+    return result;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      Object.assign(result, flattenObject(value, path));
+    } else {
+      result[path] = value;
+    }
+  }
+  return result;
+}
+function formatConfigDebug(globalConfig, testConfig, flagOverrides) {
+  const layers = [
+    { flat: flattenObject(globalConfig), label: "global config" },
+    { flat: flattenObject(testConfig), label: "test yaml" },
+    { flat: flattenObject(flagOverrides), label: "cli flag" }
+  ];
+  const merged = mergeWithTestConfig(globalConfig, testConfig, flagOverrides);
+  const mergedFlat = flattenObject(merged);
+  const colorize = {
+    "global config": pc.dim,
+    "test yaml": pc.cyan,
+    "cli flag": pc.green
+  };
+  const rows = [];
+  for (const key of Object.keys(mergedFlat).sort()) {
+    let source = "global config";
+    for (const layer of layers) {
+      if (key in layer.flat) {
+        source = layer.label;
+      }
+    }
+    const valStr = typeof mergedFlat[key] === "string" ? mergedFlat[key] : JSON.stringify(mergedFlat[key]);
+    rows.push({ key, value: valStr, source });
+  }
+  if (rows.length === 0) return pc.dim("  (no config values)");
+  const maxKey = Math.max(...rows.map((r) => r.key.length), 3);
+  const maxVal = Math.max(...rows.map((r) => r.value.length), 5);
+  const header = `  ${"Key".padEnd(maxKey)}  ${"Value".padEnd(maxVal)}  Source`;
+  const sep = `  ${"\u2500".repeat(maxKey)}  ${"\u2500".repeat(maxVal)}  ${"\u2500".repeat(13)}`;
+  const lines = rows.map((r) => {
+    const color = colorize[r.source];
+    return `  ${r.key.padEnd(maxKey)}  ${r.value.padEnd(maxVal)}  ${color(r.source)}`;
+  });
+  return [header, sep, ...lines].join("\n");
+}
+async function resolveConfig(options) {
+  const configPath = options.configPath ?? "agent-qa.config.yaml";
+  const fileConfig = await loadRequiredConfigFile(configPath);
+  const envOverrides = loadEnvOverrides();
+  const merged = mergeConfigs(fileConfig, envOverrides, options.flags ?? {});
+  const normalized = normalizeConfigForValidation(merged);
+  const result = AgentQaConfigSchema.safeParse(normalized);
+  if (!result.success) {
+    const messages = result.error.issues.map((issue) => {
+      const path = issue.path.map(String).join(".");
+      return `  ${path}: ${issue.message}`;
+    });
+    const legacyDashboardEnabled = typeof merged === "object" && merged !== null && !Array.isArray(merged) && typeof merged.services === "object" && merged.services !== null && !Array.isArray(merged.services) && typeof merged.services.dashboard === "object" && merged.services.dashboard !== null && !Array.isArray(merged.services.dashboard) && "enabled" in merged.services.dashboard;
+    const dashboardHint = legacyDashboardEnabled ? `
+
+Hint: services.dashboard.enabled was removed. Dashboard behavior is enabled by the presence of the services.dashboard block itself. Remove the enabled key and keep fields like port, dbPath, or artifactsDir.` : "";
+    throw new Error(
+      `Config validation failed:
+${messages.join("\n")}
+
+Run 'agent-qa init' to generate a complete config file.` + dashboardHint
+    );
+  }
+  if (options.loadAuthPlugins !== false) {
+    await loadLLMAuthPlugins(result.data.plugins?.auth, {
+      baseDir: dirname(resolvePath(configPath))
+    });
+  }
+  return result.data;
+}
+
+// src/targets.ts
+function resolveTarget(config, targetName) {
+  const targets = config.registry?.targets;
+  if (!targets || !(targetName in targets)) {
+    throw new Error(`Target "${targetName}" not found in config. Available targets: ${targets ? Object.keys(targets).join(", ") : "none"}`);
+  }
+  const target = targets[targetName];
+  return {
+    name: targetName,
+    product: target.product ?? targetName,
+    platform: target.platform,
+    url: target.url,
+    bundleId: target.bundleId,
+    appPackage: target.appPackage,
+    appActivity: target.appActivity,
+    device: target.device
+  };
+}
+function listTargets(config) {
+  const targets = config.registry?.targets;
+  if (!targets) return [];
+  return Object.entries(targets).map(([name, entry]) => {
+    const typedEntry = entry;
+    return {
+      name,
+      platform: typedEntry.platform
+    };
+  });
+}
+
+// src/commands/cache.ts
+import { Command } from "commander";
+import pc2 from "picocolors";
+import { readFile as readFile2, readdir, rm, stat } from "fs/promises";
+import { parse } from "yaml";
+import { join, resolve, basename } from "path";
+import { createInterface } from "readline";
+import { DEFAULT_AGENT_QA_CACHE_DIR, hashStepInstruction } from "@vostride/agent-qa-core";
+async function purgeTest(testPath, cacheDir, configContent = "") {
+  const content = await readFile2(testPath, "utf-8");
+  const doc = parse(content);
+  const platform = doc.platform ?? "web";
+  const steps = (doc.steps ?? []).map(
+    (s) => typeof s === "string" ? s : s.step
+  );
+  const resolvedCacheDir = resolve(cacheDir);
+  let purged = 0;
+  for (let i = 0; i < steps.length; i++) {
+    const stepHash = hashStepInstruction(steps[i], platform, configContent, content, i);
+    const dirPath = join(resolvedCacheDir, stepHash);
+    try {
+      await stat(dirPath);
+      await rm(dirPath, { recursive: true, force: true });
+      purged++;
+    } catch {
+    }
+  }
+  return purged;
+}
+async function purgeAll(cacheDir, force) {
+  const resolvedDir = resolve(cacheDir);
+  let entries;
+  try {
+    entries = await readdir(resolvedDir);
+  } catch (err) {
+    if (err.code === "ENOENT") return 0;
+    throw err;
+  }
+  if (entries.length === 0) return 0;
+  if (!force) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => {
+      rl.question(`About to delete ${entries.length} cached plans. Continue? (y/N) `, res);
+    });
+    rl.close();
+    if (answer.toLowerCase() !== "y") {
+      console.log("Aborted.");
+      return 0;
+    }
+  }
+  for (const entry of entries) {
+    await rm(join(resolvedDir, entry), { recursive: true, force: true });
+  }
+  return entries.length;
+}
+
+// src/index.ts
+var VERSION = getAgentQaVersion();
+export {
+  VERSION,
+  deepMerge,
+  formatConfigDebug,
+  listTargets,
+  loadConfigFile,
+  loadEnvOverrides,
+  loadRequiredConfigFile,
+  mergeConfigs,
+  mergeUseBlocks,
+  mergeWithTestConfig,
+  purgeAll,
+  purgeTest,
+  resolveConfig,
+  resolveTarget
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/config.ts","../src/targets.ts","../src/commands/cache.ts"],"sourcesContent":["import { getAgentQaVersion } from '@vostride/agent-qa-core'\n\nexport * from '@vostride/agent-qa-core'\nexport const VERSION = getAgentQaVersion()\nexport * from './config.js'\nexport * from './targets.js'\nexport { purgeTest, purgeAll } from './commands/cache.js'\n","import { readFile } from 'node:fs/promises'\nimport { dirname, resolve as resolvePath } from 'node:path'\nimport { parse as parseYaml } from 'yaml'\nimport pc from 'picocolors'\nimport { AgentQaConfigSchema, loadLLMAuthPlugins } from '@vostride/agent-qa-core'\nimport type { AgentQaConfig } from '@vostride/agent-qa-core'\n\nconst ENV_MAPPING: Record<string, string> = {\n  AGENT_QA_DASHBOARD_PORT: 'services.dashboard.port',\n  AGENT_QA_MCP_PORT: 'services.mcp.port',\n  AGENT_QA_CACHE_DIR: 'services.cache.dir',\n  AGENT_QA_CACHE_TTL: 'services.cache.ttl',\n  AGENT_QA_LOG_LEVEL: 'services.logging.level',\n  AGENT_QA_HEADLESS: 'use.browser.headless',\n}\n\nfunction setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {\n  const parts = path.split('.')\n  let current: Record<string, unknown> = obj\n  for (let i = 0; i < parts.length - 1; i++) {\n    const key = parts[i]\n    if (!(key in current) || typeof current[key] !== 'object' || current[key] === null) {\n      current[key] = {}\n    }\n    current = current[key] as Record<string, unknown>\n  }\n  current[parts[parts.length - 1]] = value\n}\n\nfunction parseEnvValue(key: string, value: string): unknown {\n  if (key === 'AGENT_QA_DASHBOARD_PORT' || key === 'AGENT_QA_MCP_PORT') {\n    const parsed = Number.parseInt(value, 10)\n    if (Number.isInteger(parsed)) return parsed\n  }\n  if (key === 'AGENT_QA_HEADLESS') {\n    const normalized = value.trim().toLowerCase()\n    if (normalized === 'true') return true\n    if (normalized === 'false') return false\n  }\n  return value\n}\n\nexport async function loadConfigFile(configPath: string): Promise<unknown> {\n  try {\n    const content = await readFile(configPath, 'utf-8')\n    return parseYaml(content) ?? {}\n  } catch (err: unknown) {\n    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {}\n    throw err\n  }\n}\n\nexport async function loadRequiredConfigFile(configPath: string): Promise<unknown> {\n  try {\n    const content = await readFile(configPath, 'utf-8')\n    return parseYaml(content) ?? {}\n  } catch (err: unknown) {\n    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n      throw new Error(`Config file not found: ${configPath}`)\n    }\n    throw err\n  }\n}\n\nexport function loadEnvOverrides(): Record<string, unknown> {\n  const result: Record<string, unknown> = {}\n  for (const [envKey, configPath] of Object.entries(ENV_MAPPING)) {\n    const value = process.env[envKey]\n    if (value !== undefined) {\n      setNestedValue(result, configPath, parseEnvValue(envKey, value))\n    }\n  }\n  return result\n}\n\nfunction isPlainObject(val: unknown): val is Record<string, unknown> {\n  return typeof val === 'object' && val !== null && !Array.isArray(val)\n}\n\nexport function mergeConfigs(\n  file: unknown,\n  env: Record<string, unknown>,\n  flags: Record<string, unknown>,\n): unknown {\n  return deepMerge(deepMerge(file ?? {}, env), flags)\n}\n\nexport function deepMerge(base: unknown, override: unknown): unknown {\n  if (!isPlainObject(base) || !isPlainObject(override)) return override\n  const result: Record<string, unknown> = { ...base }\n  for (const key of Object.keys(override)) {\n    if (key in result && isPlainObject(result[key]) && isPlainObject(override[key])) {\n      result[key] = deepMerge(result[key], override[key])\n    } else {\n      result[key] = override[key]\n    }\n  }\n  return result\n}\n\nexport function mergeWithTestConfig(\n  globalConfig: unknown,\n  testConfig: unknown,\n  flagOverrides: Record<string, unknown>,\n): unknown {\n  return deepMerge(deepMerge(globalConfig ?? {}, testConfig ?? {}), flagOverrides)\n}\n\nfunction normalizeConfigForValidation(config: unknown): unknown {\n  if (!isPlainObject(config)) return config\n  const normalized = deepMerge({}, config) as Record<string, unknown>\n  const use = normalized.use\n  if (isPlainObject(use)) {\n    delete use.headless\n  }\n  return normalized\n}\n\nexport function mergeUseBlocks(\n  globalUse: Record<string, unknown> | undefined,\n  suiteUse: Record<string, unknown> | undefined,\n  testUse: Record<string, unknown> | undefined,\n  cliFlags: Record<string, unknown>,\n): Record<string, unknown> {\n  return deepMerge(\n    deepMerge(\n      deepMerge(globalUse ?? {}, suiteUse ?? {}),\n      testUse ?? {},\n    ),\n    cliFlags,\n  ) as Record<string, unknown>\n}\n\nfunction flattenObject(obj: unknown, prefix = ''): Record<string, unknown> {\n  const result: Record<string, unknown> = {}\n  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {\n    if (prefix) result[prefix] = obj\n    return result\n  }\n  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {\n    const path = prefix ? `${prefix}.${key}` : key\n    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {\n      Object.assign(result, flattenObject(value, path))\n    } else {\n      result[path] = value\n    }\n  }\n  return result\n}\n\ntype ConfigSource = 'global config' | 'test yaml' | 'cli flag'\n\nexport function formatConfigDebug(\n  globalConfig: unknown,\n  testConfig: unknown,\n  flagOverrides: Record<string, unknown>,\n): string {\n  const layers: { flat: Record<string, unknown>; label: ConfigSource }[] = [\n    { flat: flattenObject(globalConfig), label: 'global config' },\n    { flat: flattenObject(testConfig), label: 'test yaml' },\n    { flat: flattenObject(flagOverrides), label: 'cli flag' },\n  ]\n\n  const merged = mergeWithTestConfig(globalConfig, testConfig, flagOverrides)\n  const mergedFlat = flattenObject(merged)\n\n  const colorize: Record<ConfigSource, (s: string) => string> = {\n    'global config': pc.dim,\n    'test yaml': pc.cyan,\n    'cli flag': pc.green,\n  }\n\n  const rows: { key: string; value: string; source: ConfigSource }[] = []\n  for (const key of Object.keys(mergedFlat).sort()) {\n    let source: ConfigSource = 'global config'\n    // Check layers in reverse priority order — last match wins\n    for (const layer of layers) {\n      if (key in layer.flat) {\n        source = layer.label\n      }\n    }\n    const valStr = typeof mergedFlat[key] === 'string' ? mergedFlat[key] : JSON.stringify(mergedFlat[key])\n    rows.push({ key, value: valStr, source })\n  }\n\n  if (rows.length === 0) return pc.dim('  (no config values)')\n\n  const maxKey = Math.max(...rows.map(r => r.key.length), 3)\n  const maxVal = Math.max(...rows.map(r => r.value.length), 5)\n\n  const header = `  ${'Key'.padEnd(maxKey)}  ${'Value'.padEnd(maxVal)}  Source`\n  const sep = `  ${'─'.repeat(maxKey)}  ${'─'.repeat(maxVal)}  ${'─'.repeat(13)}`\n  const lines = rows.map(r => {\n    const color = colorize[r.source]\n    return `  ${r.key.padEnd(maxKey)}  ${r.value.padEnd(maxVal)}  ${color(r.source)}`\n  })\n\n  return [header, sep, ...lines].join('\\n')\n}\n\nexport async function resolveConfig(options: {\n  configPath?: string\n  flags?: Record<string, unknown>\n  loadAuthPlugins?: boolean\n}): Promise<AgentQaConfig> {\n  const configPath = options.configPath ?? 'agent-qa.config.yaml'\n  const fileConfig = await loadRequiredConfigFile(configPath)\n  const envOverrides = loadEnvOverrides()\n  const merged = mergeConfigs(fileConfig, envOverrides, options.flags ?? {})\n  const normalized = normalizeConfigForValidation(merged)\n\n  const result = AgentQaConfigSchema.safeParse(normalized)\n  if (!result.success) {\n    const messages = result.error.issues.map((issue: { path: PropertyKey[]; message: string }) => {\n      const path = issue.path.map(String).join('.')\n      return `  ${path}: ${issue.message}`\n    })\n    const legacyDashboardEnabled =\n      typeof merged === 'object'\n      && merged !== null\n      && !Array.isArray(merged)\n      && typeof (merged as Record<string, unknown>).services === 'object'\n      && (merged as Record<string, unknown>).services !== null\n      && !Array.isArray((merged as Record<string, unknown>).services)\n      && typeof ((merged as Record<string, unknown>).services as Record<string, unknown>).dashboard === 'object'\n      && ((merged as Record<string, unknown>).services as Record<string, unknown>).dashboard !== null\n      && !Array.isArray(((merged as Record<string, unknown>).services as Record<string, unknown>).dashboard)\n      && 'enabled' in (((merged as Record<string, unknown>).services as Record<string, unknown>).dashboard as Record<string, unknown>)\n\n    const dashboardHint = legacyDashboardEnabled\n      ? `\\n\\nHint: services.dashboard.enabled was removed. Dashboard behavior is enabled by the presence of the services.dashboard block itself. Remove the enabled key and keep fields like port, dbPath, or artifactsDir.`\n      : ''\n    throw new Error(\n      `Config validation failed:\\n${messages.join('\\n')}\\n\\n` +\n      `Run 'agent-qa init' to generate a complete config file.` +\n      dashboardHint\n    )\n  }\n  if (options.loadAuthPlugins !== false) {\n    await loadLLMAuthPlugins(result.data.plugins?.auth, {\n      baseDir: dirname(resolvePath(configPath)),\n    })\n  }\n  return result.data\n}\n","import type { AgentQaConfig } from '@vostride/agent-qa-core'\n\nexport interface ResolvedTarget {\n  name: string\n  product: string\n  platform: 'web' | 'android' | 'ios'\n  url?: string\n  bundleId?: string\n  appPackage?: string\n  appActivity?: string\n  device?: string\n}\n\nexport interface TargetSummary {\n  name: string\n  platform: 'web' | 'android' | 'ios'\n}\n\ninterface TargetEntry {\n  product?: string\n  platform: 'web' | 'android' | 'ios'\n  bundleId?: string\n  appPackage?: string\n  appActivity?: string\n  url?: string\n  device?: string\n}\n\nexport function resolveTarget(\n  config: AgentQaConfig,\n  targetName: string,\n): ResolvedTarget {\n  const targets = (config as any).registry?.targets\n  if (!targets || !(targetName in targets)) {\n    throw new Error(`Target \"${targetName}\" not found in config. Available targets: ${targets ? Object.keys(targets).join(', ') : 'none'}`)\n  }\n\n  const target = targets[targetName] as TargetEntry\n\n  return {\n    name: targetName,\n    product: target.product ?? targetName,\n    platform: target.platform,\n    url: target.url,\n    bundleId: target.bundleId,\n    appPackage: target.appPackage,\n    appActivity: target.appActivity,\n    device: target.device,\n  }\n}\n\nexport function listTargets(config: AgentQaConfig): TargetSummary[] {\n  const targets = (config as any).registry?.targets\n  if (!targets) return []\n\n  return Object.entries(targets).map(([name, entry]) => {\n    const typedEntry = entry as TargetEntry\n    return {\n      name,\n      platform: typedEntry.platform,\n    }\n  })\n}\n","import { Command } from 'commander'\nimport pc from 'picocolors'\nimport { readFile, readdir, rm, stat } from 'node:fs/promises'\nimport { parse } from 'yaml'\nimport { join, resolve, basename } from 'node:path'\nimport { createInterface } from 'node:readline'\nimport { DEFAULT_AGENT_QA_CACHE_DIR, hashStepInstruction } from '@vostride/agent-qa-core'\nimport { resolveConfig } from '../config.js'\n\nconst CACHE_DIR_FALLBACK = DEFAULT_AGENT_QA_CACHE_DIR || '.agent-qa/cache'\n\nexport async function purgeTest(testPath: string, cacheDir: string, configContent = ''): Promise<number> {\n  const content = await readFile(testPath, 'utf-8')\n  const doc = parse(content)\n  const platform: string = doc.platform ?? 'web'\n  const steps: string[] = (doc.steps ?? []).map((s: unknown) =>\n    typeof s === 'string' ? s : (s as Record<string, string>).step,\n  )\n\n  const resolvedCacheDir = resolve(cacheDir)\n  let purged = 0\n\n  for (let i = 0; i < steps.length; i++) {\n    const stepHash = hashStepInstruction(steps[i], platform, configContent, content, i)\n    const dirPath = join(resolvedCacheDir, stepHash)\n    try {\n      await stat(dirPath)\n      await rm(dirPath, { recursive: true, force: true })\n      purged++\n    } catch {\n      // directory doesn't exist — skip\n    }\n  }\n\n  return purged\n}\n\nexport async function purgeAll(cacheDir: string, force: boolean): Promise<number> {\n  const resolvedDir = resolve(cacheDir)\n  let entries: string[]\n  try {\n    entries = await readdir(resolvedDir)\n  } catch (err: unknown) {\n    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return 0\n    throw err\n  }\n\n  if (entries.length === 0) return 0\n\n  if (!force) {\n    const rl = createInterface({ input: process.stdin, output: process.stdout })\n    const answer = await new Promise<string>((res) => {\n      rl.question(`About to delete ${entries.length} cached plans. Continue? (y/N) `, res)\n    })\n    rl.close()\n    if (answer.toLowerCase() !== 'y') {\n      console.log('Aborted.')\n      return 0\n    }\n  }\n\n  for (const entry of entries) {\n    await rm(join(resolvedDir, entry), { recursive: true, force: true })\n  }\n\n  return entries.length\n}\n\nexport function createCacheCommand(): Command {\n  const cmd = new Command('cache').description('Manage action cache')\n\n  cmd\n    .command('purge')\n    .description('Clear cached action plans')\n    .option('--test <path>', 'purge cache for a specific test file')\n    .option('--all', 'purge all cached plans')\n    .option('--force', 'skip confirmation prompt')\n    .action(async (opts) => {\n      if (!opts.test && !opts.all) {\n        console.error(pc.red('Specify --test <path> or --all'))\n        process.exitCode = 1\n        return\n      }\n\n      const parentOpts = cmd.parent?.opts() ?? {}\n      const config = await resolveConfig({\n        configPath: parentOpts.config as string | undefined,\n      })\n      const cacheDir = config.services?.cache?.dir ?? CACHE_DIR_FALLBACK\n\n      // Read raw config file content for cache key scoping\n      const configPath = (parentOpts.config as string | undefined) ?? 'agent-qa.config.yaml'\n      let configContent = ''\n      try {\n        configContent = await readFile(configPath, 'utf-8')\n      } catch { /* config file may not exist */ }\n\n      if (opts.test) {\n        const count = await purgeTest(opts.test, cacheDir, configContent)\n        if (count === 0) {\n          console.log(pc.dim('No cached plans found'))\n        } else {\n          console.log(pc.green(`Purged ${count} cached plans for ${basename(opts.test)}`))\n        }\n      } else if (opts.all) {\n        const count = await purgeAll(cacheDir, !!opts.force)\n        if (count === 0) {\n          console.log(pc.dim('No cached plans found'))\n        } else {\n          console.log(pc.green(`Purged ${count} cached plans (all)`))\n        }\n      }\n    })\n\n  return cmd\n}\n"],"mappings":"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","names":["pc","readFile","readFile"]}

package/package.json

@@ -1,11 +1,82 @@
 {
   "name": "agent-qa",
-  "version": "0.0.1",
-  "author": {
-    "name": "Pranshu Chittora",
-    "email": "pranshuchittora17@gmail.com",
-    "url": "https://github.com/pranshuchittora"
-  },
-  "main": "index.js",
-  "license": "MIT"
+  "version": "0.1.2",
+  "private": false,
+  "description": "agent-qa command-line interface for AI-powered web and mobile testing.",
+  "keywords": [
+    "agent-qa",
+    "testing",
+    "automation",
+    "cli",
+    "web",
+    "mobile"
+  ],
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://github.com/vostride/agent-qa#readme",
+  "bugs": {
+    "url": "https://github.com/vostride/agent-qa/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vostride/agent-qa.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "bin": {
+    "agent-qa": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "LICENSE.md",
+    "NOTICE.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@inquirer/checkbox": "5.1.4",
+    "@inquirer/confirm": "6.0.12",
+    "@inquirer/input": "5.0.12",
+    "@inquirer/password": "5.0.12",
+    "@inquirer/select": "5.1.4",
+    "@vostride/agent-qa-android": "0.1.2",
+    "@vostride/agent-qa-core": "0.1.2",
+    "@vostride/agent-qa-dashboard": "0.1.2",
+    "@vostride/agent-qa-dashboard-ui": "0.1.2",
+    "@vostride/agent-qa-ids": "0.1.2",
+    "@vostride/agent-qa-ios": "0.1.2",
+    "@vostride/agent-qa-mcp": "0.1.2",
+    "@vostride/agent-qa-web": "0.1.2",
+    "ai": "6.0.174",
+    "commander": "14.0.3",
+    "glob": "13.0.6",
+    "picocolors": "1.1.1",
+    "yaml": "2.8.4",
+    "zod": "4.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "~24.12.2",
+    "tsup": "~8.5.1",
+    "typescript": "~6.0.3",
+    "vitest": "~4.1.5"
+  }
 }

package/skills/agent-qa-authoring/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agent-qa-authoring
+description: Use when creating, editing, validating, or running agent-qa tests, suites, or hooks. Prefer agent-qa MCP tools, enforce canonical agent-qa IDs, and use the bundled schema reference to avoid hallucinated config keys or YAML fields.
+metadata:
+  short-description: Author agent-qa tests safely
+---
+
+# agent-qa Authoring
+
+## Workflow
+
+1. Discover the local surface with `agent_qa_discover`.
+2. Inspect active config with `agent_qa_get_config`, especially targets, devices, providers, and `services.mcp`.
+3. Load `references/agent-qa-contracts.json` when you need exact schema fields or ID contracts.
+4. Generate every new ID with agent-qa tooling:
+   - MCP: `agent_qa_generate_id`
+   - CLI fallback: `agent-qa ids generate <test|suite|hook|run|observation>`
+   - npx fallback: `npx --yes agent-qa ids generate <type>`
+5. Never hand-write IDs. Validate existing IDs with `agent_qa_validate_id` or `agent-qa ids validate <type> <id> --json`.
+6. Validate definitions before saving:
+   - Tests: `agent_qa_validate_test` or `agent_qa_validate_definition` with `kind: "test"`
+   - Suites: `agent_qa_validate_suite` or `agent_qa_validate_definition` with `kind: "suite"`
+   - Hooks: `agent_qa_validate_definition` with `kind: "hooks"`
+7. Prefer MCP authoring mutations:
+   - Tests: `agent_qa_create_test`, `agent_qa_update_test`, `agent_qa_delete_test`
+   - Suites: `agent_qa_create_suite`, `agent_qa_update_suite`, `agent_qa_delete_suite`
+   - Hooks: `agent_qa_create_hook`, `agent_qa_update_hook`, `agent_qa_delete_hook`
+8. Use CLI/YAML fallback only when MCP is unavailable. Keep file paths matched by `workspace.testMatch` or `workspace.suiteMatch`.
+
+## Required ID Contracts
+
+- Test IDs: `t_` + 10 id-agent words.
+- Suite IDs: `s_` + 10 id-agent words.
+- Hook IDs: `h_` + 10 id-agent words.
+- Run IDs: `r_` + 10 id-agent words.
+- Observation IDs: `obs_` + 10 id-agent words.
+
+## Before Running
+
+- Validate YAML first.
+- Prefer `agent_qa_enqueue_test_run` and `agent_qa_enqueue_suite_run` over shelling out.
+- If using CLI fallback, run only after validation succeeds.
+
+## Do Not
+
+- Do not invent config keys.
+- Do not use legacy root config buckets.
+- Do not hand-write IDs.
+- Do not mutate files outside the configured workspace patterns.

package/skills/agent-qa-authoring/agents/openai.yaml

@@ -0,0 +1,15 @@
+interface:
+  display_name: "agent-qa Authoring"
+  short_description: "Author tests with real agent-qa contracts"
+  default_prompt: "Use $agent-qa-authoring to create and validate an agent-qa test with canonical IDs."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "agent-qa"
+      description: "agent-qa local MCP server for schema, ID, authoring, and run tools."
+      transport: "streamable_http"
+      url: "http://127.0.0.1:3471/mcp"
+
+policy:
+  allow_implicit_invocation: true

package/skills/agent-qa-authoring/references/agent-qa-contracts.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "source": "packages/mcp/references/agent-qa-contracts.json",
+  "ids": {
+    "instruction": "Generate IDs with agent_qa_generate_id or `agent-qa ids generate <type>`; never hand-write IDs.",
+    "contracts": [
+      { "type": "test", "prefix": "t", "prefixWithSeparator": "t_", "words": 10 },
+      { "type": "suite", "prefix": "s", "prefixWithSeparator": "s_", "words": 10 },
+      { "type": "hook", "prefix": "h", "prefixWithSeparator": "h_", "words": 10 },
+      { "type": "observation", "prefix": "obs", "prefixWithSeparator": "obs_", "words": 10 },
+      { "type": "run", "prefix": "r", "prefixWithSeparator": "r_", "words": 10 }
+    ]
+  },
+  "config": {
+    "rootKeys": ["workspace", "services", "registry", "use", "analytics"],
+    "mcpFields": ["enabled", "transport", "host", "port", "path"]
+  },
+  "test": {
+    "requiredKeys": ["test-id", "name", "target", "steps"],
+    "optionalKeys": ["context", "use", "meta", "setup", "teardown"]
+  },
+  "suite": {
+    "requiredKeys": ["name", "target", "tests"],
+    "optionalKeys": ["suite-id", "context", "setup", "teardown", "use"],
+    "testEntryKeys": ["test", "id"]
+  },
+  "hooks": {
+    "rootKeys": ["hooks"],
+    "hookKeys": ["id", "name", "runtime", "file", "deps", "packageFile", "timeout", "network"]
+  }
+}

package/skills/agent-qa-debug-fix/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: agent-qa-debug-fix
+description: Use after an agent-qa run has failed and you need to debug, patch, and verify the issue using MCP evidence, logs, artifacts, and local code changes instead of generated fix suggestions.
+metadata:
+  short-description: Debug and fix failed agent-qa runs
+---
+
+# agent-qa Debug Fix
+
+## Workflow
+
+1. Start with evidence collection:
+   - `agent_qa_get_run`
+   - `agent_qa_get_run_steps`
+   - `agent_qa_get_run_artifact`
+   - `agent_qa_get_run_logs`
+   - `agent_qa_get_run_execution_logs`
+2. Call `agent_qa_classify_failure` and treat its category as a hypothesis, not a verdict.
+3. Identify the failing surface: test definition, hook, application under test, runtime infrastructure, or agent behavior.
+4. Inspect the relevant local files directly. Do not infer patches from artifacts alone.
+5. Apply the smallest code or YAML change that explains the evidence.
+6. Re-run the narrowest affected agent-qa test, suite, hook, or unit test.
+7. Report the root cause, changed files, verification command, and any remaining risk.
+
+## Fix Rules
+
+- Do not invent selectors, screen states, screenshots, logs, or source files.
+- Do not rewrite a test just to make it pass if the artifact shows a product or runtime defect.
+- Preserve canonical agent-qa IDs when editing tests, suites, hooks, or memory files.
+- Prefer `agent_qa_validate_test`, `agent_qa_validate_suite`, and `agent_qa_validate_definition` before re-running edited YAML.
+- When MCP is unavailable, use dashboard REST APIs or local `.agent-qa` artifacts and state that MCP evidence was unavailable.

package/skills/agent-qa-debug-fix/agents/openai.yaml

@@ -0,0 +1,15 @@
+interface:
+  display_name: "agent-qa Debug Fix"
+  short_description: "Patch failed runs from evidence"
+  default_prompt: "Use $agent-qa-debug-fix to debug this failed agent-qa run, patch the root cause, and verify it."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "agent-qa"
+      description: "agent-qa local MCP server for run, artifact, log, validation, and triage tools."
+      transport: "streamable_http"
+      url: "http://127.0.0.1:3471/mcp"
+
+policy:
+  allow_implicit_invocation: true

package/skills/agent-qa-result-triage/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: agent-qa-result-triage
+description: Use when investigating failed agent-qa runs, inspecting artifacts, classifying failures, or comparing recent runs. Prefer agent-qa MCP run/artifact tools and produce evidence-backed triage.
+metadata:
+  short-description: Triage agent-qa run failures
+---
+
+# agent-qa Result Triage
+
+## Workflow
+
+1. Start with `agent_qa_get_run` for run status, suite child context, steps, and attempts.
+2. Fetch evidence before deciding:
+   - `agent_qa_get_run_artifact`
+   - `agent_qa_get_run_steps`
+   - `agent_qa_get_run_logs`
+   - `agent_qa_get_run_execution_logs`
+3. Call `agent_qa_classify_failure` and use its category as the default classification unless stronger evidence contradicts it.
+4. Compare recent related runs when available in the classifier output.
+5. Return a concise triage result: category, confidence, evidence, likely fix area, and next action.
+6. For code changes, switch to `agent-qa-debug-fix` after triage is complete.
+
+## Categories
+
+Use one of the fixed categories from `references/triage-categories.md`:
+
+- `timeout`
+- `appium_startup`
+- `browser_disconnect`
+- `element_not_found`
+- `assertion_failure`
+- `hook_failure`
+- `infrastructure`
+- `unknown_failure`
+
+## Evidence Rules
+
+- Quote or summarize concrete artifact/log/step evidence.
+- Mention missing artifact sections if they limit confidence.
+- Do not invent screenshots, videos, logs, or memory context that was not returned by MCP.
+- If MCP is unavailable, use dashboard REST APIs or `agent-qa` CLI output as fallback and say which evidence was unavailable.

package/skills/agent-qa-result-triage/agents/openai.yaml

@@ -0,0 +1,15 @@
+interface:
+  display_name: "agent-qa Result Triage"
+  short_description: "Classify failures from run artifacts"
+  default_prompt: "Use $agent-qa-result-triage to classify this failed agent-qa run with evidence."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "agent-qa"
+      description: "agent-qa local MCP server for run, artifact, log, and triage tools."
+      transport: "streamable_http"
+      url: "http://127.0.0.1:3471/mcp"
+
+policy:
+  allow_implicit_invocation: true

package/skills/agent-qa-result-triage/references/triage-categories.md

@@ -0,0 +1,16 @@
+# agent-qa Triage Categories
+
+Use exactly one category.
+
+| Category | Use When | First Checks |
+|---|---|---|
+| `timeout` | The run or step exceeded timeout. | Run failure summary, step duration, logs. |
+| `appium_startup` | Appium failed to start or acquire a mobile session. | Failure summary, execution logs, artifact runtime errors. |
+| `browser_disconnect` | Browser/page/context closed unexpectedly. | Error logs containing browser closed or target closed. |
+| `element_not_found` | Locator, element, selector, or UI description was unavailable. | Failed step error, observation, screenshot, DOM/accessibility context. |
+| `assertion_failure` | App was reachable but expected content/state did not match. | Failed assert/verify step, observation, screenshot. |
+| `hook_failure` | Setup/teardown/hook execution blocked the run. | Hook logs, hook artifact sections, hook registry errors. |
+| `infrastructure` | Network, Docker, farm, device, filesystem, or service dependency failed. | Execution logs, stderr, artifact runtime errors. |
+| `unknown_failure` | Evidence is insufficient for a stronger category. | Missing sections and next evidence to collect. |
+
+Always include evidence and a next action.